app_spi_v2.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_spi_v2.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of SPI app library.
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2020 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  ****************************************************************************************
36  */
37 
38 /** @addtogroup PERIPHERAL Peripheral Driver
39  * @{
40  */
41 
42 /** @addtogroup APP_DRIVER APP DRIVER
43  * @{
44  */
45 
46 /** @defgroup APP_SPI SPI
47  * @brief SPI APP module driver.
48  * @{
49  */
50 #ifndef _APP_SPI_V2_H_
51 #define _APP_SPI_V2_H_
52 
53 #include "gr55xx_hal.h"
54 #include "app_io.h"
55 #include "app_drv_error.h"
56 #include "app_rtos_cfg.h"
57 
58 #ifdef __cplusplus
59 extern "C" {
60 #endif
61 
62 #ifdef HAL_SPI_V2_MODULE_ENABLED
63 
64 
65 #ifdef _APP_SPI_H_
66 #error "NOT Support USING app_spi AND app_spi_v2 AT The Same Time !!!"
67 #endif
68 
69 /** @addtogroup APP_SPI_DEFINE Defines
70  * @{
71  */
72 
73 #define APP_SPI_PIN_ENABLE 1 /**< SPI pin enable */
74 #define APP_SPI_PIN_DISABLE 0 /**< SPI pin disable */
75 
76 /** @} */
77 
78 /** @addtogroup APP_SPI_ENUM Enumerations
79  * @{
80  */
81 
82 /**
83  * @brief SPI module Enumerations definition
84  */
85 typedef enum
86 {
87  APP_SPI_ID_SLAVE, /**< SPI slave module. */
88  APP_SPI_ID_MASTER, /**< SPI master module. */
89  APP_SPI_ID_MAX, /**< Only for check parameter, not used as input parameters. */
90 } app_spi_id_t;
91 
92 /**
93  * @brief SPI operating mode Enumerations definition
94  */
95 typedef enum
96 {
97  APP_SPI_TYPE_POLLING, /**< Polling operation mode */
98  APP_SPI_TYPE_DMA, /**< DMA operation mode */
99  APP_SPI_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */
101 
102 /**
103  * @brief SPI operating mode Enumerations definition
104  */
105 typedef enum
106 {
107  APP_SPI_DATAWIDTH_8BIT = 0x00, /**< datasize : 8bit */
108  APP_SPI_DATAWIDTH_32BIT, /**< datasize : 32bit */
109 } app_spi_datawidth_t;
110 
111 
112 /**
113  * @brief SPI event Enumerations definition
114  */
115 typedef enum
116 {
117  APP_SPI_EVT_ERROR, /**< Error reported by UART peripheral. */
118  APP_SPI_EVT_TX_CPLT, /**< Requested TX transfer completed. */
119  APP_SPI_EVT_RX_DATA, /**< Requested RX transfer completed. */
120  APP_SPI_EVT_TX_RX, /**< Requested TX/RX transfer completed. */
122 /** @} */
123 
124 /** @addtogroup APP_SPI_STRUCTURES Structures
125  * @{
126  */
127 /**
128  * @brief SPI IO Structures
129  */
130 typedef struct
131 {
132  app_io_type_t type; /**< Specifies the type of SPI IO. */
133  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
134  uint32_t pin; /**< Specifies the IO pins to be configured.
135  This parameter can be any value of @ref GR551x_pins. */
136  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
137  uint8_t enable; /**< Enable or disable the pin. */
138 } app_spi_pin_t;
139 
140 /**
141  * @brief SPI IO configuration Structures
142  */
143 typedef struct
144 {
145  app_spi_pin_t cs; /**< Set the configuration of SPI CS pin. */
146  app_spi_pin_t clk; /**< Set the configuration of SPI CLK pin. */
147  app_spi_pin_t mosi; /**< Set the configuration of SPI MOSI pin. */
148  app_spi_pin_t miso; /**< Set the configuration of SPI MISO pin. */
150 
151 /**
152  * @brief SPI operate mode Enumerations definition
153  */
154 typedef struct
155 {
156  app_spi_type_t type; /**< Specifies the operation mode of SPI. */
157  dma_channel_t tx_dma_channel; /**< Specifies the dma channel of SPI TX. */
158  dma_channel_t rx_dma_channel; /**< Specifies the dma channel of SPI RX. */
160 
161 /**
162  * @brief SPI parameters structure definition
163  */
164 typedef struct
165 {
166  app_spi_id_t id; /**< specified SPI module ID. */
167  app_spi_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified SPI module. */
168  app_spi_mode_t use_mode; /**< SPI operate mode. */
169  spi_init_t init; /**< SPI communication parameters. */
170  uint32_t rx_sample_delay; /**< Specifies the RX sample delay. It is used to delay the sample of the RX input port.
171  This parameter can be a number between 0 and 0x7 */
173 
174 /**
175  * @brief SPI event structure definition
176  */
177 typedef struct
178 {
179  app_spi_evt_type_t type; /**< Type of event. */
180  union
181  {
182  uint32_t error_code; /**< SPI Error code . */
183  uint16_t size; /**< SPI transmitted/received counter. */
184  } data; /**< Event data. */
185 } app_spi_evt_t;
186 
187 /**
188  * @brief SPI event callback definition
189  */
190 typedef void (*app_spi_evt_handler_t)(app_spi_evt_t *p_evt);
191 
192 /** @} */
193 
194 /* Exported functions --------------------------------------------------------*/
195 /** @addtogroup APP_SPI_DRIVER_FUNCTIONS Functions
196  * @{
197  */
198 /**
199  ****************************************************************************************
200  * @brief Initialize the APP SPI DRIVER according to the specified parameters
201  * in the app_spi_params_t and app_spi_evt_handler_t.
202  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
203  * is set, you can't use interrupt mode.
204  *
205  * @param[in] p_params: Pointer to app_spi_params_t parameter which contains the
206  * configuration information for the specified SPI module.
207  * @param[in] evt_handler: SPI user callback function.
208  *
209  *
210  * @return Result of initialization.
211  ****************************************************************************************
212  */
213 uint16_t app_spi_v2_init(app_spi_params_t *p_params, app_spi_evt_handler_t evt_handler);
214 
215 /**
216  ****************************************************************************************
217  * @brief De-initialize the APP SPI DRIVER peripheral.
218  *
219  * @param[in] id: De-initialize for a specific ID.
220  *
221  * @return Result of De-initialization.
222  ****************************************************************************************
223  */
224 uint16_t app_spi_v2_deinit(app_spi_id_t id);
225 
226 
227 /**
228  ****************************************************************************************
229  * @brief Transmits in master or slave mode an amount of data in blocking mode, without inst & addr.
230  *
231  * @param[in] id: which SPI module want to transmit.
232  * @param[in] data_width : data sent width in SPI FIFO , supports 8bit / 32bit
233  * @param[in] p_data: Pointer to data buffer
234  * @param[in] size: Amount of data to be sent
235  * @param[in] timeout: Timeout duration
236  *
237  * @return Result of operation.
238  ****************************************************************************************
239  */
240 uint16_t app_spi_v2_transmit_poll_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size, uint32_t timeout);
241 
242 /**
243  ****************************************************************************************
244  * @brief Transmits an amount of data in blocking mode in master mode , with inst & addr.
245  *
246  * @param[in] id: which SPI module want to transmit.
247  * @param[in] data_width : data sent width in SPI FIFO , supports 8bit / 32bit
248  * @param[in] inst: instruction which just supports 8bit.
249  * @param[in] addr: address which just supports 24bit.
250  * @param[in] p_data: Pointer to data buffer
251  * @param[in] size: Amount of data to be sent
252  * @param[in] timeout: Timeout duration
253  *
254  * @return Result of operation.
255  ****************************************************************************************
256  */
257 uint16_t app_spi_v2_transmit_with_ia_poll_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size, uint32_t timeout);
258 
259 /**
260  ****************************************************************************************
261  * @brief Receive in master or slave mode an amount of data in blocking mode , without inst & addr.
262  *
263  * @param[in] id: which SPI module want to receive.
264  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
265  * @param[in] p_data: Pointer to data buffer
266  * @param[in] size: Amount of data to be sent
267  * @param[in] timeout: Timeout duration
268  *
269  * @return Result of operation.
270  ****************************************************************************************
271  */
272 uint16_t app_spi_v2_receive_poll_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size, uint32_t timeout);
273 
274 /**
275  ****************************************************************************************
276  * @brief Receivean amount of data in blocking mode in master mode with instruction and address .
277  *
278  * @param[in] id: which SPI module want to receive.
279  * @param[in] data_width: data receive width in SPI FIFO , supports 8bit / 32bit
280  * @param[in] inst: instruction which just supports 8bit.
281  * @param[in] addr: address which just supports 24bit.
282  * @param[in] p_data: Pointer to data buffer
283  * @param[in] size: Amount of data to be sent
284  * @param[in] timeout: Timeout duration
285  *
286  * @return Result of operation.
287  ****************************************************************************************
288  */
289 uint16_t app_spi_v2_receive_with_ia_poll_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size, uint32_t timeout);
290 
291 /**
292  ****************************************************************************************
293  * @brief Transmits then Receive an amount of data in blocking mode in master mode .
294  *
295  * @param[in] id: which SPI module want to transmit.
296  * @param[in] tx_data: transmit data.
297  * @param[in] tx_size: transmit data size.
298  * @param[in] rx_data: receive data.
299  * @param[in] rx_size: receive data size.
300  * @param[in] timeout: Timeout duration
301  *
302  * @return Result of operation.
303  ****************************************************************************************
304  */
305 uint16_t app_spi_v2_transmit_receive_8bit_poll_sync(app_spi_id_t id, uint8_t *tx_data, uint16_t tx_size, uint8_t *rx_data, uint16_t rx_size, uint32_t timeout);
306 
307 /**
308  ****************************************************************************************
309  * @brief Transmits in master mode an amount of data in dma mode, without inst & addr.
310  *
311  * @param[in] id: which SPI module want to transmit.
312  * @param[in] data_width: data sent width in SPI FIFO , supports 8bit / 32bit
313  * @param[in] p_data: Pointer to data buffer
314  * @param[in] size: Amount of data to be sent
315  *
316  * @return Result of operation.
317  ****************************************************************************************
318  */
319 uint16_t app_spi_v2_transmit_dma_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size);
320 
321 /**
322  ****************************************************************************************
323  * @brief Transmits in master mode an amount of data in dma mode, with inst & addr.
324  *
325  * @param[in] id: which SPI module want to transmit.
326  * @param[in] data_width : data sent width in SPI FIFO , supports 8bit / 32bit
327  * @param[in] inst: instruction which just supports 8bit.
328  * @param[in] addr: address which just supports 24bit.
329  * @param[in] p_data: Pointer to data buffer
330  * @param[in] size: Amount of data to be sent
331  *
332  * @return Result of operation.
333  ****************************************************************************************
334  */
335 uint16_t app_spi_v2_transmit_with_ia_dma_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size);
336 
337 /**
338  ****************************************************************************************
339  * @brief Receive in master mode an amount of data in dma mode, without inst & addr.
340  *
341  * @param[in] id: which SPI module want to receive.
342  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
343  * @param[in] p_data: Pointer to data buffer
344  * @param[in] size: Amount of data to be sent
345  *
346  * @return Result of operation.
347  ****************************************************************************************
348  */
349 uint16_t app_spi_v2_receive_dma_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size);
350 
351 /**
352  ****************************************************************************************
353  * Receive in master mode an amount of data in dma mode, with inst & addr.
354  *
355  * @param[in] id: which SPI module want to receive.
356  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
357  * @param[in] inst: instruction which just supports 8bit.
358  * @param[in] addr: address which just supports 24bit.
359  * @param[in] p_data: Pointer to data buffer
360  * @param[in] size: Amount of data to be sent
361  *
362  * @return Result of operation.
363  ****************************************************************************************
364  */
365 uint16_t app_spi_v2_receive_with_ia_dma_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size);
366 
367 /**
368  ****************************************************************************************
369  * (Sync mode) Using DMA to Transmit data by toggling CS in every data beat.
370  *
371  * @param[in] id: which SPI module want to receive.
372  * @param[in] data_width : optional value - @SPI_DATASIZE_8BIT @SPI_DATASIZE_16BIT @SPI_DATASIZE_32BIT
373  * @param[in] p_data: Pointer to data buffer
374  * @param[in] size: Amount of data to be sent
375  *
376  * @return Result of operation.
377  ****************************************************************************************
378  */
379 uint16_t app_spi_v2_cs_toggle_transmit_dma_sync(app_spi_id_t id, uint32_t data_width, uint8_t *p_data, uint16_t size);
380 
381 /**
382  ****************************************************************************************
383  * (Async mode) Using DMA to Transmit data by toggling CS in every data beat.
384  *
385  * @param[in] id: which SPI module want to receive.
386  * @param[in] data_width : optional value - @SPI_DATASIZE_8BIT @SPI_DATASIZE_16BIT @SPI_DATASIZE_32BIT
387  * @param[in] p_data: Pointer to data buffer
388  * @param[in] size: Amount of data to be sent
389  *
390  * @return Result of operation.
391  ****************************************************************************************
392  */
393 uint16_t app_spi_v2_cs_toggle_transmit_dma_async(app_spi_id_t id, uint32_t data_width, uint8_t *p_data, uint16_t size);
394 
395 #ifdef ENV_RTOS_USE_SEMP
396 
397 /**
398  ****************************************************************************************
399  * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode, with inst and addr.
400  *
401  * @param[in] id: which SPI module want to transmit.
402  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
403  * @param[in] inst: instruction which just supports 8bit.
404  * @param[in] addr: address which just supports 24bit.
405  * @param[in] p_data: Pointer to data buffer
406  * @param[in] size: Amount of data to be sent
407  *
408  * @return Result of operation.
409  ****************************************************************************************
410  */
411 uint16_t app_spi_v2_transmit_with_ia_dma_sem_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size);
412 
413 /**
414  ****************************************************************************************
415  * @brief [RTOS] Transmits in master or slave mode an amount of data in blocking mode, without inst and addr.
416  *
417  * @param[in] id: which SPI module want to transmit.
418  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
419  * @param[in] p_data: Pointer to data buffer
420  * @param[in] size: Amount of data to be sent
421  *
422  * @return Result of operation.
423  ****************************************************************************************
424  */
425 uint16_t app_spi_v2_transmit_dma_sem_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size);
426 
427 /**
428  ****************************************************************************************
429  * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode, with inst and addr.
430  *
431  * @param[in] id: which SPI module want to receive.
432  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
433  * @param[in] inst: instruction which just supports 8bit.
434  * @param[in] addr: address which just supports 24bit.
435  * @param[in] p_data: Pointer to data buffer
436  * @param[in] size: Amount of data to be sent
437  *
438  * @return Result of operation.
439  ****************************************************************************************
440  */
441 uint16_t app_spi_v2_receive_with_ia_dma_sem_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t inst, uint32_t addr, uint8_t *p_data, uint16_t size);
442 
443 /**
444  ****************************************************************************************
445  * @brief [RTOS] Receive in master or slave mode an amount of data in blocking mode, without inst and addr.
446  *
447  * @param[in] id: which SPI module want to receive.
448  * @param[in] data_width : data receive width in SPI FIFO , supports 8bit / 32bit
449  * @param[in] p_data: Pointer to data buffer
450  * @param[in] size: Amount of data to be sent
451  *
452  * @return Result of operation.
453  ****************************************************************************************
454  */
455 uint16_t app_spi_v2_receive_dma_sem_sync(app_spi_id_t id, app_spi_datawidth_t data_width, uint8_t *p_data, uint16_t size);
456 
457 #endif
458 
459 /**
460  ****************************************************************************************
461  * @brief Return the SPI handle.
462  *
463  * @param[in] id: SPI Channel ID.
464  *
465  * @return Pointer to the specified ID's SPI handle.
466  ****************************************************************************************
467  */
468 spi_handle_t *app_spi_v2_get_handle(app_spi_id_t id);
469 
470 
471 /** @} */
472 
473 
474 #endif
475 
476 #ifdef __cplusplus
477 }
478 #endif
479 
480 #endif
481 
482 /** @} */
483 /** @} */
484 /** @} */
485 
486 
app_spi_pin_cfg_t
SPI IO configuration Structures.
Definition: app_spi.h:136
_spi_handle
SPI handle Structure definition.
Definition: gr55xx_hal_spi.h:135
APP_SPI_TYPE_MAX
@ APP_SPI_TYPE_MAX
Only for check parameter, not used as input parameters.
Definition: app_spi.h:101
APP_SPI_ID_MAX
@ APP_SPI_ID_MAX
Only for check parameter, not used as input parameters.
Definition: app_spi.h:90
APP_SPI_ID_SLAVE
@ APP_SPI_ID_SLAVE
SPI slave module.
Definition: app_spi.h:88
APP_SPI_TYPE_DMA
@ APP_SPI_TYPE_DMA
DMA operation mode
Definition: app_spi.h:100
app_spi_evt_handler_t
void(* app_spi_evt_handler_t)(app_spi_evt_t *p_evt)
SPI event callback definition.
Definition: app_spi.h:180
app_spi_params_t
SPI parameters structure definition.
Definition: app_spi.h:157
_spi_init
SPI init Structure definition.
Definition: gr55xx_hal_spi.h:104
app_spi_evt_t
SPI event structure definition.
Definition: app_spi.h:168
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:187
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:141
APP_SPI_ID_MASTER
@ APP_SPI_ID_MASTER
SPI master module.
Definition: app_spi.h:89
APP_SPI_TYPE_POLLING
@ APP_SPI_TYPE_POLLING
Polling operation mode
Definition: app_spi.h:99
app_io.h
Header file containing functions prototypes of GPIO app library.
APP_SPI_EVT_TX_RX
@ APP_SPI_EVT_TX_RX
Requested TX/RX transfer completed.
Definition: app_spi.h:112
app_spi_id_t
app_spi_id_t
SPI module Enumerations definition.
Definition: app_spi.h:87
app_spi_pin_t
SPI IO Structures.
Definition: app_spi.h:123
app_spi_evt_type_t
app_spi_evt_type_t
SPI event Enumerations definition.
Definition: app_spi.h:108
app_spi_type_t
app_spi_type_t
SPI operating mode Enumerations definition.
Definition: app_spi.h:97
APP_SPI_EVT_TX_CPLT
@ APP_SPI_EVT_TX_CPLT
Requested TX transfer completed.
Definition: app_spi.h:110
APP_SPI_EVT_RX_DATA
@ APP_SPI_EVT_RX_DATA
Requested RX transfer completed.
Definition: app_spi.h:111
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:198
app_rtos_cfg.h
Header file of app rtos config code.
app_drv_error.h
Header file of app driver error code.
APP_SPI_EVT_ERROR
@ APP_SPI_EVT_ERROR
Error reported by UART peripheral.
Definition: app_spi.h:109
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
app_spi_mode_t
SPI operate mode Enumerations definition.
Definition: app_spi.h:147