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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 (
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 (
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 //--------------------------------------------------------------------------------------------------
303 (
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 //--------------------------------------------------------------------------------------------------
326 (
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 //--------------------------------------------------------------------------------------------------
344 (
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 //--------------------------------------------------------------------------------------------------
363 (
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
void le_spi_Close(le_spi_DeviceHandleRef_t handle)
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
Definition: le_basics.h:35
le_result_t le_spi_WriteHD(le_spi_DeviceHandleRef_t handle, const uint8_t *writeDataPtr, size_t writeDataSize)
le_result_t le_spi_TryConnectService(void)
void le_spi_Configure(le_spi_DeviceHandleRef_t handle, int32_t mode, uint8_t bits, uint32_t speed, int32_t msb)
void(* le_spi_DisconnectHandler_t)(void *)
Definition: le_spi_interface.h:125
void le_spi_SetServerDisconnectHandler(le_spi_DisconnectHandler_t disconnectHandler, void *contextPtr)
struct le_spi_DeviceHandle * le_spi_DeviceHandleRef_t
Definition: le_spi_interface.h:221
void le_spi_ConnectService(void)
void le_spi_DisconnectService(void)
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_result_t le_spi_Open(const char *LE_NONNULL deviceName, le_spi_DeviceHandleRef_t *handlePtr)
le_result_t le_spi_ReadHD(le_spi_DeviceHandleRef_t handle, uint8_t *readDataPtr, size_t *readDataSizePtr)