le_spi_interface.h

Go to the documentation of this file.
    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_spi SPI
   14  *
   15  * @ref le_spi_interface.h "API Reference" <br>
   16  * @subpage howToSPI "How To Setup SPI" <br>
   17  * @ref yoctoOutofTreeKernelModule
   18  *
   19  * <HR>
   20  *
   21  * @section spi_overview Overview
   22  *
   23  * This API is used by apps to control a Serial Peripheral Interface (SPI).
   24  *
   25  * The SPI API is configured as a four wire interface:
   26  * - Clock - Serial Clock
   27  * - MOSI - Master Output
   28  * - MISO - Master Input
   29  * - SS or CS - Chip select
   30  *
   31  * @section spi_usage Usage
   32  *
   33  * The sample code in this section shows how to use the SPI API for a user space app.
   34  *
   35  * Handle for passing to related functions to access the SPI device:
   36  * @code
   37  * le_spi_DeviceHandleRef_t spiHandle;
   38  * @endcode
   39  *
   40  * le_spi_Open() opens the @c spi file handle:
   41  * @code
   42  * le_result_t res;
   43  * res = le_spi_Open("spidev0.0", &spiHandle);
   44  * LE_FATAL_IF(res != LE_OK, "le_spi_Open failed with result=%s", LE_RESULT_TXT(res));
   45  * @endcode
   46  *
   47  * le_spi_Configure() initializes all the parameters on the master side based on the
   48  * implementation below uses mode = 0, 8 bit data, 960kbps and MSB first:
   49  * @code
   50  * le_spi_Configure(spiHandle, 0, 8, 960000, 0);
   51  * @endcode
   52  *
   53  * le_spi_WriteHD() writes data to slave device in half-duplex mode:
   54  * write_buffer_tx is an array. Example defined below:
   55  * @code
   56  * uinti8_t write_buffer_tx[] ={0xC7, 0x94, 0x80, 0x9A};
   57  * le_result_t res;
   58  * res = le_spi_WriteHD(spiHandle, write_buffer_tx, NUM_ARRAY_MEMBERS(write_buffer_tx));
   59  * LE_FATAL_IF(res != LE_OK, "le_spi_WriteHD failed with result=%s", LE_RESULT_TXT(res));
   60  * @endcode
   61  *
   62  * le_spi_WriteReadHD() writes and reads to/from slave device in half-duplex mode:
   63  * @code
   64  * le_result_t res;
   65  * le_spi_WriteReadHD(spiHandle, read_ID_tx, NUM_ARRAY_MEMBERS(read_ID_tx), ID_rx,
   66  *                    &readBufferSize);
   67  * LE_FATAL_IF(res != LE_OK, "le_spi_WriteReadHD failed with result=%s", LE_RESULT_TXT(res));
   68  * @endcode
   69  * read_ID_tx is an array that is transmitted to the device. ID_rx is a buffer reserved for
   70  * data received from  the device.
   71  *
   72  * le_spi_WriteReadFD() writes and reads to/from slave in full-duplex mode:
   73  * @code
   74  * le_result_t res;
   75  * res = le_spi_WriteReadHD(spiHandle, read_buffer_tx, read_rx, NUM_ARRAY_MEMBERS(read_buffer_tx);
   76  * LE_FATAL_IF(res != LE_OK, "le_spi_WriteReadHD failed with result=%s", LE_RESULT_TXT(res));
   77  * @endcode
   78  * read_buffer_tx is an array transmitted to the device. read_rx is a buffer reserved for
   79  * data received from the device. Buffer size for tx and rx must be the same.
   80  *
   81  * le_spi_Close() closes the spi handle:
   82  * @code
   83  * le_spi_Close(spiHandle);
   84  * @endcode
   85  *
   86  * @section spi_kernel_dep Kernel module dependency
   87  *
   88  * SPI Service has a build time dependency on the spisvc.ko kernel module for the subset of
   89  * targets on which the feature is currently supported (currently, WP76, WP77, WP75, WP85).
   90  * That means, spiService.adef file and default.sdef file both include kernelModules section
   91  * that lists spisvc.mdef as a dependency.
   92  * @note If the users is building their own configuration, extra attention has to be paid to
   93  * preserve this logic, i.e. retain the build-time dependency and avoid duplicated inclusion of
   94  * the spisvc.mdef (which may cause build errors).
   95  *
   96  * @section spi_scripts Automatic installation/removal of the kernel modules
   97  *
   98  * SPI service is started manually, i.e. it is not running by default. When the user starts
   99  * spiService, the install.sh scripts takes care of loading both "spidev" and "spisvc" kernel
  100  * modules.
  101  * Conversely, when spiService is stopped, the remove.sh script uloads both kernel modules.
  102  *
  103  * Copyright (C) Sierra Wireless Inc.
  104  */
  105 /**
  106  * @file le_spi_interface.h
  107  *
  108  * Legato @ref c_le_spi include file.
  109  *
  110  * Copyright (C) Sierra Wireless Inc.
  111  */
  112 
  113 #ifndef LE_SPI_INTERFACE_H_INCLUDE_GUARD
  114 #define LE_SPI_INTERFACE_H_INCLUDE_GUARD
  115 
  116 
  117 #include "legato.h"
  118 
  119 // Internal includes for this interface
  120 #include "le_spi_common.h"
  121 //--------------------------------------------------------------------------------------------------
  122 /**
  123  * Type for handler called when a server disconnects.
  124  */
  125 //--------------------------------------------------------------------------------------------------
  126 typedef void (*le_spi_DisconnectHandler_t)(void *);
  127 
  128 //--------------------------------------------------------------------------------------------------
  129 /**
  130  *
  131  * Connect the current client thread to the service providing this API. Block until the service is
  132  * available.
  133  *
  134  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  135  * called before any other functions in this API.  Normally, ConnectService is automatically called
  136  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  137  *
  138  * This function is created automatically.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 void le_spi_ConnectService
  142 (
  143     void
  144 );
  145 
  146 //--------------------------------------------------------------------------------------------------
  147 /**
  148  *
  149  * Try to connect the current client thread to the service providing this API. Return with an error
  150  * if the service is not available.
  151  *
  152  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  153  * called before any other functions in this API.  Normally, ConnectService is automatically called
  154  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  155  *
  156  * This function is created automatically.
  157  *
  158  * @return
  159  *  - LE_OK if the client connected successfully to the service.
  160  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  161  *    bound.
  162  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  163  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 le_result_t le_spi_TryConnectService
  167 (
  168     void
  169 );
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * Set handler called when server disconnection is detected.
  174  *
  175  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  176  * to continue without exiting, it should call longjmp() from inside the handler.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 LE_FULL_API void le_spi_SetServerDisconnectHandler
  180 (
  181     le_spi_DisconnectHandler_t disconnectHandler,
  182     void *contextPtr
  183 );
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  *
  188  * Disconnect the current client thread from the service providing this API.
  189  *
  190  * Normally, this function doesn't need to be called. After this function is called, there's no
  191  * longer a connection to the service, and the functions in this API can't be used. For details, see
  192  * @ref apiFilesC_client.
  193  *
  194  * This function is created automatically.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 void le_spi_DisconnectService
  198 (
  199     void
  200 );
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Handle for passing to related functions to access the SPI device
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Opens an SPI device so that the attached device may be accessed.
  213  *
  214  * @return
  215  *      - LE_OK on success
  216  *      - LE_BAD_PARAMETER if the device name string is bad
  217  *      - LE_NOT_FOUND if the SPI device file could not be found
  218  *      - LE_NOT_PERMITTED if the SPI device file can't be opened for read/write
  219  *      - LE_DUPLICATE if the given device file is already opened by another spiService client
  220  *      - LE_FAULT for non-specific failures
  221  */
  222 //--------------------------------------------------------------------------------------------------
  223 le_result_t le_spi_Open
  224 (
  225     const char* LE_NONNULL deviceName,
  226         ///< [IN] Handle for the SPI master to open
  227     le_spi_DeviceHandleRef_t* handlePtr
  228         ///< [OUT] Handle for passing to related functions in order to
  229         ///< access the SPI device
  230 );
  231 
  232 //--------------------------------------------------------------------------------------------------
  233 /**
  234  * Closes the device associated with the given handle and frees the associated resources.
  235  *
  236  * @note
  237  *      Once a handle is closed, it's not permitted to use it for future SPI access without first
  238  *      calling Open.
  239  */
  240 //--------------------------------------------------------------------------------------------------
  241 void le_spi_Close
  242 (
  243     le_spi_DeviceHandleRef_t handle
  244         ///< [IN] Handle for the SPI master to close
  245 );
  246 
  247 //--------------------------------------------------------------------------------------------------
  248 /**
  249  * Configures an SPI device's data sample settings. The required values should be
  250  * included in your target's datasheet. Most common @c Mode values are
  251  * @c 0 and @c 3.
  252  *
  253  * These are the SPI Mode options:
  254  * |   Mode  |   Clock Polarity   |  Clock Phase   |   Clock Edge   |
  255  * | :-----: | :----------------: | :------------: | :------------: |
  256  * |   0     |       0            |   0            |    1           |
  257  * |   1     |       0            |   1            |    0           |
  258  * |   2     |       1            |   0            |    1           |
  259  * |   3     |       1            |   1            |    0           |
  260  *
  261  * @note
  262  *      This function should be called before any of the Read/Write functions to ensure
  263  *      the SPI bus configuration is in a known state.
  264  */
  265 //--------------------------------------------------------------------------------------------------
  266 void le_spi_Configure
  267 (
  268     le_spi_DeviceHandleRef_t handle,
  269         ///< [IN] Handle for the SPI master to configure
  270     int32_t mode,
  271         ///< [IN] Choose mode options for the bus per above table
  272     uint8_t bits,
  273         ///< [IN] bits per word, typically 8 bits per word
  274     uint32_t speed,
  275         ///< [IN] max speed (Hz), this is slave dependant
  276     int32_t msb
  277         ///< [IN] set as 0 for MSB as first bit or 1 for LSB as first bit
  278 );
  279 
  280 //--------------------------------------------------------------------------------------------------
  281 /**
  282  * Performs SPI WriteRead Half Duplex. You can send send Read command/ address of data to read.
  283  *
  284  * @return
  285  *      LE_OK on success or LE_FAULT on failure.
  286  */
  287 //--------------------------------------------------------------------------------------------------
  288 le_result_t le_spi_WriteReadHD
  289 (
  290     le_spi_DeviceHandleRef_t handle,
  291         ///< [IN] Handle for the SPI master to perform the write-read on
  292     const uint8_t* writeDataPtr,
  293         ///< [IN] TX command/address being sent to slave with size
  294     size_t writeDataSize,
  295         ///< [IN]
  296     uint8_t* readDataPtr,
  297         ///< [OUT] RX response from slave with number of bytes reserved
  298         ///< on master
  299     size_t* readDataSizePtr
  300         ///< [INOUT]
  301 );
  302 
  303 //--------------------------------------------------------------------------------------------------
  304 /**
  305  * SPI Write for Half Duplex Communication
  306  *
  307  * @return
  308  *      LE_OK on success or LE_FAULT on failure.
  309  */
  310 //--------------------------------------------------------------------------------------------------
  311 le_result_t le_spi_WriteHD
  312 (
  313     le_spi_DeviceHandleRef_t handle,
  314         ///< [IN] Handle for the SPI master to perform the write on
  315     const uint8_t* writeDataPtr,
  316         ///< [IN] TX command/address being sent to slave with size
  317     size_t writeDataSize
  318         ///< [IN]
  319 );
  320 
  321 //--------------------------------------------------------------------------------------------------
  322 /**
  323  * SPI Read for Half Duplex Communication
  324  *
  325  * @return
  326  *      LE_OK on success or LE_FAULT on failure.
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 le_result_t le_spi_ReadHD
  330 (
  331     le_spi_DeviceHandleRef_t handle,
  332         ///< [IN] Handle for the SPI master to perform the read from
  333     uint8_t* readDataPtr,
  334         ///< [OUT] RX response from slave with number of bytes reserved
  335         ///<  on master
  336     size_t* readDataSizePtr
  337         ///< [INOUT]
  338 );
  339 
  340 //--------------------------------------------------------------------------------------------------
  341 /**
  342  * Simultaneous SPI Write and  Read for full duplex communication
  343  *
  344  * @return
  345  *      LE_OK on success or LE_FAULT on failure.
  346  */
  347 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_spi_WriteReadFD
  349 (
  350     le_spi_DeviceHandleRef_t handle,
  351         ///< [IN] Handle for the SPI master to perform full duplex write-read on
  352     const uint8_t* writeDataPtr,
  353         ///< [IN] TX command/address being sent to slave with size
  354     size_t writeDataSize,
  355         ///< [IN]
  356     uint8_t* readDataPtr,
  357         ///< [OUT] RX response from slave with same buffer size as TX
  358     size_t* readDataSizePtr
  359         ///< [INOUT]
  360 );
  361 
  362 #endif // LE_SPI_INTERFACE_H_INCLUDE_GUARD
le_spi_Close
void le_spi_Close(le_spi_DeviceHandleRef_t handle)


le_spi_WriteReadFD
le_result_t le_spi_WriteReadFD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataSize, uint8_t *readDataPtr, size_t *readDataSizePtr)


le_spi_SetServerDisconnectHandler
LE_FULL_API void le_spi_SetServerDisconnectHandler(le_spi_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_result_t
le_result_t
Definition: le_basics.h:45


le_spi_WriteHD
le_result_t le_spi_WriteHD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataSize)


le_spi_TryConnectService
le_result_t le_spi_TryConnectService(void)


le_spi_Configure
void le_spi_Configure(le_spi_DeviceHandleRef_t handle, int32_t mode, uint8_t bits, uint32_t speed, int32_t msb)


le_spi_DisconnectHandler_t
void(* le_spi_DisconnectHandler_t)(void *)
Definition: le_spi_interface.h:126


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_spi_ConnectService
void le_spi_ConnectService(void)


le_spi_DisconnectService
void le_spi_DisconnectService(void)


le_spi_WriteReadHD
le_result_t le_spi_WriteReadHD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataSize, uint8_t *readDataPtr, size_t *readDataSizePtr)


le_spi_Open
le_result_t le_spi_Open(const char *LE_NONNULL deviceName, le_spi_DeviceHandleRef_t *handlePtr)


le_spi_ReadHD
le_result_t le_spi_ReadHD(le_spi_DeviceHandleRef_t handle, uint8_t *readDataPtr, size_t *readDataSizePtr)