le_spi_interface.h

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


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


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


le_spi_TryConnectService
le_result_t le_spi_TryConnectService(void)


le_spi_WriteReadFD
le_result_t le_spi_WriteReadFD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataNumElements, uint8_t *readDataPtr, size_t *readDataNumElementsPtr)


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_WriteReadHD
le_result_t le_spi_WriteReadHD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataNumElements, uint8_t *readDataPtr, size_t *readDataNumElementsPtr)


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



le_spi_ConnectService
void le_spi_ConnectService(void)


le_spi_DisconnectService
void le_spi_DisconnectService(void)