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


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_DisconnectHandler_t
void(* le_spi_DisconnectHandler_t)(void *)
Definition: le_spi_interface.h:130


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


le_spi_Close
void le_spi_Close(le_spi_DeviceHandleRef_t handle)


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


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


le_spi_common.h


le_spi_DisconnectService
void le_spi_DisconnectService(void)


le_spi_DeviceHandleRef_t
struct le_spi_DeviceHandle * le_spi_DeviceHandleRef_t
Definition: le_spi_common.h:47


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40



le_spi_ConnectService
void le_spi_ConnectService(void)


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


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)