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


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


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



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_ReadHD
le_result_t le_spi_ReadHD(le_spi_DeviceHandleRef_t handle, uint8_t *readDataPtr, size_t *readDataSizePtr)