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 
  120 //--------------------------------------------------------------------------------------------------
  121 /**
  122  * Type for handler called when a server disconnects.
  123  */
  124 //--------------------------------------------------------------------------------------------------
  125 typedef void (*le_spi_DisconnectHandler_t)(void *);
  126 
  127 //--------------------------------------------------------------------------------------------------
  128 /**
  129  *
  130  * Connect the current client thread to the service providing this API. Block until the service is
  131  * available.
  132  *
  133  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  134  * called before any other functions in this API.  Normally, ConnectService is automatically called
  135  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  136  *
  137  * This function is created automatically.
  138  */
  139 //--------------------------------------------------------------------------------------------------
  140 void le_spi_ConnectService
  141 (
  142     void
  143 );
  144 
  145 //--------------------------------------------------------------------------------------------------
  146 /**
  147  *
  148  * Try to connect the current client thread to the service providing this API. Return with an error
  149  * if the service is not available.
  150  *
  151  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  152  * called before any other functions in this API.  Normally, ConnectService is automatically called
  153  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  154  *
  155  * This function is created automatically.
  156  *
  157  * @return
  158  *  - LE_OK if the client connected successfully to the service.
  159  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  160  *    bound.
  161  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  162  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 le_result_t le_spi_TryConnectService
  166 (
  167     void
  168 );
  169 
  170 //--------------------------------------------------------------------------------------------------
  171 /**
  172  * Set handler called when server disconnection is detected.
  173  *
  174  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  175  * to continue without exiting, it should call longjmp() from inside the handler.
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 void le_spi_SetServerDisconnectHandler
  179 (
  180     le_spi_DisconnectHandler_t disconnectHandler,
  181     void *contextPtr
  182 );
  183 
  184 //--------------------------------------------------------------------------------------------------
  185 /**
  186  *
  187  * Disconnect the current client thread from the service providing this API.
  188  *
  189  * Normally, this function doesn't need to be called. After this function is called, there's no
  190  * longer a connection to the service, and the functions in this API can't be used. For details, see
  191  * @ref apiFilesC_client.
  192  *
  193  * This function is created automatically.
  194  */
  195 //--------------------------------------------------------------------------------------------------
  196 void le_spi_DisconnectService
  197 (
  198     void
  199 );
  200 
  201 
  202 //--------------------------------------------------------------------------------------------------
  203 /**
  204  * Max byte storage size for write buffer
  205  */
  206 //--------------------------------------------------------------------------------------------------
  207 #define LE_SPI_MAX_WRITE_SIZE 1024
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Max byte storage size for read buffer
  212  */
  213 //--------------------------------------------------------------------------------------------------
  214 #define LE_SPI_MAX_READ_SIZE 1024
  215 
  216 //--------------------------------------------------------------------------------------------------
  217 /**
  218  * Handle for passing to related functions to access the SPI device
  219  */
  220 //--------------------------------------------------------------------------------------------------
  221 typedef struct le_spi_DeviceHandle* le_spi_DeviceHandleRef_t;
  222 
  223 
  224 //--------------------------------------------------------------------------------------------------
  225 /**
  226  * Opens an SPI device so that the attached device may be accessed.
  227  *
  228  * @return
  229  *      - LE_OK on success
  230  *      - LE_BAD_PARAMETER if the device name string is bad
  231  *      - LE_NOT_FOUND if the SPI device file could not be found
  232  *      - LE_NOT_PERMITTED if the SPI device file can't be opened for read/write
  233  *      - LE_DUPLICATE if the given device file is already opened by another spiService client
  234  *      - LE_FAULT for non-specific failures
  235  */
  236 //--------------------------------------------------------------------------------------------------
  237 le_result_t le_spi_Open
  238 (
  239     const char* LE_NONNULL deviceName,
  240         ///< [IN] Handle for the SPI master to open
  241     le_spi_DeviceHandleRef_t* handlePtr
  242         ///< [OUT] Handle for passing to related functions in order to
  243         ///< access the SPI device
  244 );
  245 
  246 //--------------------------------------------------------------------------------------------------
  247 /**
  248  * Closes the device associated with the given handle and frees the associated resources.
  249  *
  250  * @note
  251  *      Once a handle is closed, it's not permitted to use it for future SPI access without first
  252  *      calling Open.
  253  */
  254 //--------------------------------------------------------------------------------------------------
  255 void le_spi_Close
  256 (
  257     le_spi_DeviceHandleRef_t handle
  258         ///< [IN] Handle for the SPI master to close
  259 );
  260 
  261 //--------------------------------------------------------------------------------------------------
  262 /**
  263  * Configures an SPI device's data sample settings. The required values should be
  264  * included in your target's datasheet. Most common @c Mode values are
  265  * @c 0 and @c 3.
  266  *
  267  * These are the SPI Mode options:
  268  * |   Mode  |   Clock Polarity   |  Clock Phase   |   Clock Edge   |
  269  * | :-----: | :----------------: | :------------: | :------------: |
  270  * |   0     |       0            |   0            |    1           |
  271  * |   1     |       0            |   1            |    0           |
  272  * |   2     |       1            |   0            |    1           |
  273  * |   3     |       1            |   1            |    0           |
  274  *
  275  * @note
  276  *      This function should be called before any of the Read/Write functions to ensure
  277  *      the SPI bus configuration is in a known state.
  278  */
  279 //--------------------------------------------------------------------------------------------------
  280 void le_spi_Configure
  281 (
  282     le_spi_DeviceHandleRef_t handle,
  283         ///< [IN] Handle for the SPI master to configure
  284     int32_t mode,
  285         ///< [IN] Choose mode options for the bus per above table
  286     uint8_t bits,
  287         ///< [IN] bits per word, typically 8 bits per word
  288     uint32_t speed,
  289         ///< [IN] max speed (Hz), this is slave dependant
  290     int32_t msb
  291         ///< [IN] set as 0 for MSB as first bit or 1 for LSB as first bit
  292 );
  293 
  294 //--------------------------------------------------------------------------------------------------
  295 /**
  296  * Performs SPI WriteRead Half Duplex. You can send send Read command/ address of data to read.
  297  *
  298  * @return
  299  *      LE_OK on success or LE_FAULT on failure.
  300  */
  301 //--------------------------------------------------------------------------------------------------
  302 le_result_t le_spi_WriteReadHD
  303 (
  304     le_spi_DeviceHandleRef_t handle,
  305         ///< [IN] Handle for the SPI master to perform the write-read on
  306     const uint8_t* writeDataPtr,
  307         ///< [IN] TX command/address being sent to slave with size
  308     size_t writeDataSize,
  309         ///< [IN]
  310     uint8_t* readDataPtr,
  311         ///< [OUT] RX response from slave with number of bytes reserved
  312         ///< on master
  313     size_t* readDataSizePtr
  314         ///< [INOUT]
  315 );
  316 
  317 //--------------------------------------------------------------------------------------------------
  318 /**
  319  * SPI Write for Half Duplex Communication
  320  *
  321  * @return
  322  *      LE_OK on success or LE_FAULT on failure.
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 le_result_t le_spi_WriteHD
  326 (
  327     le_spi_DeviceHandleRef_t handle,
  328         ///< [IN] Handle for the SPI master to perform the write on
  329     const uint8_t* writeDataPtr,
  330         ///< [IN] TX command/address being sent to slave with size
  331     size_t writeDataSize
  332         ///< [IN]
  333 );
  334 
  335 //--------------------------------------------------------------------------------------------------
  336 /**
  337  * SPI Read for Half Duplex Communication
  338  *
  339  * @return
  340  *      LE_OK on success or LE_FAULT on failure.
  341  */
  342 //--------------------------------------------------------------------------------------------------
  343 le_result_t le_spi_ReadHD
  344 (
  345     le_spi_DeviceHandleRef_t handle,
  346         ///< [IN] Handle for the SPI master to perform the read from
  347     uint8_t* readDataPtr,
  348         ///< [OUT] RX response from slave with number of bytes reserved
  349         ///<  on master
  350     size_t* readDataSizePtr
  351         ///< [INOUT]
  352 );
  353 
  354 //--------------------------------------------------------------------------------------------------
  355 /**
  356  * Simultaneous SPI Write and  Read for full duplex communication
  357  *
  358  * @return
  359  *      LE_OK on success or LE_FAULT on failure.
  360  */
  361 //--------------------------------------------------------------------------------------------------
  362 le_result_t le_spi_WriteReadFD
  363 (
  364     le_spi_DeviceHandleRef_t handle,
  365         ///< [IN] Handle for the SPI master to perform full duplex write-read on
  366     const uint8_t* writeDataPtr,
  367         ///< [IN] TX command/address being sent to slave with size
  368     size_t writeDataSize,
  369         ///< [IN]
  370     uint8_t* readDataPtr,
  371         ///< [OUT] RX response from slave with same buffer size as TX
  372     size_t* readDataSizePtr
  373         ///< [INOUT]
  374 );
  375 
  376 #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_result_t
le_result_t
Definition: le_basics.h:35


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:125


le_spi_SetServerDisconnectHandler
void le_spi_SetServerDisconnectHandler(le_spi_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_spi_DeviceHandleRef_t
struct le_spi_DeviceHandle * le_spi_DeviceHandleRef_t
Definition: le_spi_interface.h:221



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)