app_dspi.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file app_dspi.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of DSPI app library.
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 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 #ifndef _APP_DSPI_H_
38 #define _APP_DSPI_H_
39 
40 #include "grx_hal.h"
41 #include "app_io.h"
42 #include "app_dma.h"
43 #include "app_drv_error.h"
44 #include "app_drv_config.h"
45 
46 /** @addtogroup PERIPHERAL Peripheral Driver
47  * @{
48  */
49 
50 /** @addtogroup APP_DRIVER APP DRIVER
51  * @{
52  */
53 
54 /** @defgroup APP_DSPI DSPI
55  * @brief DSPI APP module driver.
56  * @{
57  */
58 
59 
60 
61 #ifdef HAL_DSPI_MODULE_ENABLED
62 
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66 
67 /** @addtogroup APP_DSPI_DEFINE Defines
68  * @{
69  */
70 
71 #define APP_DSPI_PIN_ENABLE 1 /**< DSPI pin enable */
72 #define APP_DSPI_PIN_DISABLE 0 /**< DSPI pin disable */
73 
74 /** @} */
75 
76 /** @addtogroup APP_DSPI_ENUM Enumerations
77  * @{
78  */
79 
80 /** @brief DSPI event Enumerations definition
81  */
82 typedef enum
83 {
84  APP_DSPI_EVT_ERROR, /**< Error reported by DSPI peripheral. */
85  APP_DSPI_EVT_TX_CPLT, /**< Requested TX transfer completed. */
86  APP_DSPI_EVT_ABORT, /**< Requested abort transfer completed.*/
88 /** @} */
89 
90 /** @addtogroup APP_DSPI_STRUCTURES Structures
91  * @{
92  */
93 
94 /**
95  * @brief DSPI IO configuration Structures
96  */
97 typedef struct
98 {
99  app_io_type_t type; /**< Specifies the type of DSPI IO. */
100  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
101  uint32_t pin; /**< Specifies the IO pins to be configured.
102  This parameter can be any value of @ref GR5xxx_pins. */
103  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
104  uint8_t enable; /**< Enable or disable the pin. */
106 
107 /**
108  * @brief DSPI Transmission IO configuration Structures
109  */
110 typedef struct
111 {
112  app_dspi_pin_t cs; /**< Set the configuration of DSPI CS pin. */
113  app_dspi_pin_t clk; /**< Set the configuration of DSPI CLK pin. */
114  app_dspi_pin_t mosi; /**< Set the configuration of DSPI MOSI pin. */
115  app_dspi_pin_t miso; /**< Set the configuration of DSPI MISO pin. */
116  app_dspi_pin_t dcx; /**< Set the configuration of DSPI DCX pin. */
118 
119 /**
120  * @brief DSPI DMA configuration Structures
121  */
122 typedef struct
123 {
124  dma_channel_t channel; /**< Specifies the dma channel of DSPI, and it uses DMA1 by default. */
126 
127 /**
128  * @brief DSPI event structure definition
129  */
130 typedef struct
131 {
132  app_dspi_evt_type_t type; /**< DSPI type of event. */
133  union
134  {
135  uint32_t error_code; /**< DSPI Error code. */
136  uint16_t size; /**< DSPI transmitted counter. */
137  } data; /**< DSPI Transmission status data. */
139 
140 /** @} */
141 
142 /** @addtogroup APP_DSPI_TYPEDEFS Type Definitions
143  * @{
144  */
145 /**
146  * @brief DSPI command structure definition
147  */
149 
150 /**
151  * @brief DSPI event callback definition
152  */
153 typedef void (*app_dspi_evt_handler_t)(app_dspi_evt_t *p_evt);
154 /** @} */
155 
156 /** @addtogroup APP_DSPI_ENUM Enumerations
157  * @{
158  */
159 /**@brief App dspi state types. */
160 typedef enum
161 {
164 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
165  APP_DSPI_SLEEP,
166 #endif
168 
169 /**@brief App dspi dma state types. */
170 typedef enum
171 {
175 
176 /** @} */
177 
178 /** @addtogroup APP_DSPI_STRUCTURES Structures
179  * @{
180  */
181 
182 typedef struct
183 {
184  app_dspi_evt_handler_t evt_handler; /**< DSPI event callback. */
185  dspi_handle_t handle; /**< DSPI handle Structure. */
186  app_dspi_pin_cfg_t *p_pin_cfg; /**< DSPI Transmission IO configuration Structures. */
187  dma_id_t dma_id; /**< DMA id. */
188  app_dspi_state_t dspi_state; /**< App dspi state types. */
189  app_dspi_dma_state_t dspi_dma_state; /**< App dspi dma state types. */
190 
191  bool start_flag; /**< start flag. */
192  volatile bool is_soft_cs; /**< soft cs. */
193 } dspi_env_t;
194 
195 /**
196  * @brief DSPI parameters structure definition
197  */
198 typedef struct
199 {
200  app_dspi_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified DSPI module. */
201  app_dspi_dma_cfg_t dma_cfg; /**< DSPI DMA configuration. */
202  dspi_init_t init; /**< DSPI communication parameters. */
203  bool is_soft_cs; /**< config whether to control CS signal by software. */
204  dspi_env_t dspi_env; /**< APP_DSPI_STRUCTURES Structures. */
206 
207 /** @} */
208 
209 /* Exported functions --------------------------------------------------------*/
210 /** @addtogroup APP_DSPI_DRIVER_FUNCTIONS Functions
211  * @{
212  */
213 /**
214  ****************************************************************************************
215  * @brief Initialize the APP DSPI DRIVER according to the specified parameters
216  * in the app_dspi_params_t and app_dspi_evt_handler_t.
217  * @note If interrupt mode is set, you can use blocking mode. Conversely, if blocking mode
218  * is set, you can't use interrupt mode.
219  *
220  * @param[in] p_params: Pointer to app_dspi_params_t parameter which contains the
221  * configuration information for the specified DSPI module.
222  * @param[in] evt_handler: DSPI user callback function.
223  *
224  * @return Result of initialization.
225  ****************************************************************************************
226  */
227 uint16_t app_dspi_init(app_dspi_params_t *p_params, app_dspi_evt_handler_t evt_handler);
228 
229 /**
230  ****************************************************************************************
231  * @brief De-initialize the APP DSPI DRIVER peripheral.
232  *
233  * @return Result of De-initialization.
234  ****************************************************************************************
235  */
236 uint16_t app_dspi_deinit(void);
237 
238 /**
239  ****************************************************************************************
240  * @brief Receive an amount of data with the specified instruction in blocking mode.
241  *
242  * @param[in] p_cmd: Pointer to a app_dspi_command_t structure that contains the instruction, length, data_size for data transfer.
243  * @param[out] p_data: Pointer to data buffer
244  * @param[in] timeout: Timeout duration
245  *
246  * @return Result of operation.
247  ****************************************************************************************
248  */
249 uint16_t app_dspi_command_transmit_sync(app_dspi_command_t *p_cmd, uint8_t *p_data, uint32_t timeout);
250 
251 /**
252  ****************************************************************************************
253  * @brief Receive an amount of data with the specified instruction in non-blocking mode with Interrupt.
254  *
255  * @param[in] p_cmd: Pointer to a app_dspi_command_t structure that contains the instruction, length, data_size for data transfer.
256  * @param[out] p_data: Pointer to data buffer
257  *
258  * @return Result of operation.
259  ****************************************************************************************
260  */
261 uint16_t app_dspi_command_transmit_async(app_dspi_command_t *p_cmd, uint8_t *p_data);
262 
263 /**
264  ****************************************************************************************
265  * @brief Transmit only instruction in blocking mode.
266  *
267  * @param[in] p_cmd: Pointer to a app_dspi_command_t structure that contains the instruction for data transfer.
268  * @param[in] timeout: Timeout duration
269  *
270  * @return Result of operation.
271  ****************************************************************************************
272  */
273 uint16_t app_dspi_command_sync(app_dspi_command_t *p_cmd, uint32_t timeout);
274 
275 /**
276  ****************************************************************************************
277  * @brief Transmit instruction in non-blocking mode with Interrupt.
278  *
279  * @param[in] p_cmd: Pointer to a app_dspi_command_t structure that contains the instruction for data transfer.
280  *
281  * @return Result of operation.
282  ****************************************************************************************
283  */
285 
286 /**
287  ****************************************************************************************
288  * @brief Transmit an amount of data in blocking mode.
289  *
290  * @param[in] p_data: Pointer to data buffer
291  * @param[in] length: Amount of data to be sent in bytes
292  * @param[in] timeout: Timeout duration
293  *
294  * @return Result of operation.
295  ****************************************************************************************
296  */
297 uint16_t app_dspi_transmit_sync(uint8_t *p_data, uint32_t length, uint32_t timeout);
298 
299 /**
300  ****************************************************************************************
301  * @brief Transmit an amount of data in non-blocking mode with Interrupt.
302  *
303  * @param[in] p_data: Pointer to data buffer
304  * @param[in] length: Amount of data to be sent in bytes
305  *
306  * @return Result of operation.
307  ****************************************************************************************
308  */
309 uint16_t app_dspi_transmit_async(uint8_t *p_data, uint32_t length);
310 
311 /**
312  ****************************************************************************************
313  * @brief Return the DSPI handle.
314  *
315  * @return Pointer to the DSPI handle.
316  ****************************************************************************************
317  */
319 
320 /**
321  ****************************************************************************************
322  * @brief Set the DSPI transmission mode.
323  *
324  * @param[in] mode: the DSPI transmission mode.This parameter can be one of the following values:
325  * @arg @ref DSPI_PROT_MODE_3W1L
326  * @arg @ref DSPI_PROT_MODE_4W1L
327  * @arg @ref DSPI_PROT_MODE_4W2L
328  *
329  * @return Result of operation.
330  ****************************************************************************************
331  */
332 uint16_t app_dspi_config_mode(uint32_t mode);
333 
334 /**
335  ****************************************************************************************
336  * @brief Set the DSPI transmission data size.
337  *
338  * @param[in] data_size: the DSPI transmission data size.This parameter can be one of the following values:
339  * @arg @ref DSPI_DATASIZE_04_BITS
340  * @arg @ref DSPI_DATASIZE_05_BITS
341  * @arg @ref DSPI_DATASIZE_06_BITS
342  * @arg @ref DSPI_DATASIZE_07_BITS
343  * @arg @ref DSPI_DATASIZE_08_BITS
344  * @arg @ref DSPI_DATASIZE_09_BITS
345  * @arg @ref DSPI_DATASIZE_10_BITS
346  * @arg @ref DSPI_DATASIZE_11_BITS
347  * @arg @ref DSPI_DATASIZE_12_BITS
348  * @arg @ref DSPI_DATASIZE_13_BITS
349  * @arg @ref DSPI_DATASIZE_14_BITS
350  * @arg @ref DSPI_DATASIZE_15_BITS
351  * @arg @ref DSPI_DATASIZE_16_BITS
352  * @arg @ref DSPI_DATASIZE_17_BITS
353  * @arg @ref DSPI_DATASIZE_18_BITS
354  * @arg @ref DSPI_DATASIZE_19_BITS
355  * @arg @ref DSPI_DATASIZE_20_BITS
356  * @arg @ref DSPI_DATASIZE_21_BITS
357  * @arg @ref DSPI_DATASIZE_22_BITS
358  * @arg @ref DSPI_DATASIZE_23_BITS
359  * @arg @ref DSPI_DATASIZE_24_BITS
360  * @arg @ref DSPI_DATASIZE_25_BITS
361  * @arg @ref DSPI_DATASIZE_26_BITS
362  * @arg @ref DSPI_DATASIZE_27_BITS
363  * @arg @ref DSPI_DATASIZE_28_BITS
364  * @arg @ref DSPI_DATASIZE_29_BITS
365  * @arg @ref DSPI_DATASIZE_30_BITS
366  * @arg @ref DSPI_DATASIZE_31_BITS
367  * @arg @ref DSPI_DATASIZE_32_BITS
368  *
369  * @return Result of operation.
370  ****************************************************************************************
371  */
372 uint16_t app_dspi_config_data_size(uint32_t data_size);
373 
374 /**
375  ****************************************************************************************
376  * @brief Abort the current transmission.
377  *
378  * @return Result of operation.
379  ****************************************************************************************
380  */
381 uint16_t app_dspi_abort(void);
382 
383 /**
384  ****************************************************************************************
385  * @brief Abort the current transmission (non-blocking function)
386  *
387  * @return Result of operation.
388  ****************************************************************************************
389  */
390 uint16_t app_dspi_abort_it(void);
391 
392 /** @} */
393 
394 #ifdef __cplusplus
395 }
396 #endif
397 
398 
399 #endif //END #ifdef HAL_DSPI_MODULE_ENABLED
400 #endif //END #ifndef _APP_DSPI_H_
401 
402 
403 /** @} */
404 
405 /** @} */
406 
407 /** @} */
app_dspi_command_transmit_async
uint16_t app_dspi_command_transmit_async(app_dspi_command_t *p_cmd, uint8_t *p_data)
Receive an amount of data with the specified instruction in non-blocking mode with Interrupt.
dspi_env_t::dspi_dma_state
app_dspi_dma_state_t dspi_dma_state
Definition: app_dspi.h:189
app_dspi_config_data_size
uint16_t app_dspi_config_data_size(uint32_t data_size)
Set the DSPI transmission data size.
app_dspi_state_t
app_dspi_state_t
App dspi state types.
Definition: app_dspi.h:161
app_dspi_init
uint16_t app_dspi_init(app_dspi_params_t *p_params, app_dspi_evt_handler_t evt_handler)
Initialize the APP DSPI DRIVER according to the specified parameters in the app_dspi_params_t and app...
app_dspi_command_transmit_sync
uint16_t app_dspi_command_transmit_sync(app_dspi_command_t *p_cmd, uint8_t *p_data, uint32_t timeout)
Receive an amount of data with the specified instruction in blocking mode.
APP_DSPI_DMA_ACTIVITY
@ APP_DSPI_DMA_ACTIVITY
Definition: app_dspi.h:173
_dspi_command_t
DSPI command Structure definition.
Definition: gr55xx_hal_dspi.h:161
app_dspi_pin_t::pull
app_io_pull_t pull
Definition: app_dspi.h:103
app_dspi_pin_cfg_t::mosi
app_dspi_pin_t mosi
Definition: app_dspi.h:114
dspi_env_t::is_soft_cs
volatile bool is_soft_cs
Definition: app_dspi.h:192
app_dspi_pin_t::mux
app_io_mux_t mux
Definition: app_dspi.h:100
dspi_env_t::start_flag
bool start_flag
Definition: app_dspi.h:191
app_dspi_dma_state_t
app_dspi_dma_state_t
App dspi dma state types.
Definition: app_dspi.h:171
app_dspi_pin_cfg_t::clk
app_dspi_pin_t clk
Definition: app_dspi.h:113
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:183
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:147
APP_DSPI_ACTIVITY
@ APP_DSPI_ACTIVITY
Definition: app_dspi.h:163
app_dspi_pin_cfg_t::cs
app_dspi_pin_t cs
Definition: app_dspi.h:112
dspi_env_t::evt_handler
app_dspi_evt_handler_t evt_handler
Definition: app_dspi.h:184
APP_DSPI_EVT_ERROR
@ APP_DSPI_EVT_ERROR
Definition: app_dspi.h:84
app_dspi_evt_type_t
app_dspi_evt_type_t
DSPI event Enumerations definition.
Definition: app_dspi.h:83
dspi_env_t::dma_id
dma_id_t dma_id
Definition: app_dspi.h:187
app_dspi_params_t::dspi_env
dspi_env_t dspi_env
Definition: app_dspi.h:204
app_dspi_pin_cfg_t::miso
app_dspi_pin_t miso
Definition: app_dspi.h:115
app_io.h
Header file containing functions prototypes of GPIO app library.
app_dspi_params_t::init
dspi_init_t init
Definition: app_dspi.h:202
app_dspi_abort_it
uint16_t app_dspi_abort_it(void)
Abort the current transmission (non-blocking function)
app_dspi_evt_t::type
app_dspi_evt_type_t type
Definition: app_dspi.h:132
app_dspi_transmit_async
uint16_t app_dspi_transmit_async(uint8_t *p_data, uint32_t length)
Transmit an amount of data in non-blocking mode with Interrupt.
app_dspi_pin_cfg_t::dcx
app_dspi_pin_t dcx
Definition: app_dspi.h:116
_dspi_init_t
QSPI init Structure definition.
Definition: gr55xx_hal_dspi.h:103
app_dspi_pin_t
DSPI IO configuration Structures.
Definition: app_dspi.h:98
APP_DSPI_EVT_ABORT
@ APP_DSPI_EVT_ABORT
Definition: app_dspi.h:86
app_dspi_command_async
uint16_t app_dspi_command_async(app_dspi_command_t *p_cmd)
Transmit instruction in non-blocking mode with Interrupt.
dspi_env_t::handle
dspi_handle_t handle
Definition: app_dspi.h:185
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_dspi_abort
uint16_t app_dspi_abort(void)
Abort the current transmission.
APP_DSPI_EVT_TX_CPLT
@ APP_DSPI_EVT_TX_CPLT
Definition: app_dspi.h:85
app_dspi_params_t::dma_cfg
app_dspi_dma_cfg_t dma_cfg
Definition: app_dspi.h:201
dspi_env_t::p_pin_cfg
app_dspi_pin_cfg_t * p_pin_cfg
Definition: app_dspi.h:186
dspi_env_t
Definition: app_dspi.h:183
_dspi_handle
DSPI handle Structure definition.
Definition: gr55xx_hal_dspi.h:124
app_dspi_params_t::is_soft_cs
bool is_soft_cs
Definition: app_dspi.h:203
app_dspi_pin_t::type
app_io_type_t type
Definition: app_dspi.h:99
app_dspi_params_t
DSPI parameters structure definition.
Definition: app_dspi.h:199
app_dspi_evt_t::size
uint16_t size
Definition: app_dspi.h:136
app_dspi_pin_t::enable
uint8_t enable
Definition: app_dspi.h:104
dspi_env_t::dspi_state
app_dspi_state_t dspi_state
Definition: app_dspi.h:188
app_dspi_evt_t::error_code
uint32_t error_code
Definition: app_dspi.h:135
app_dspi_transmit_sync
uint16_t app_dspi_transmit_sync(uint8_t *p_data, uint32_t length, uint32_t timeout)
Transmit an amount of data in blocking mode.
APP_DSPI_DMA_INVALID
@ APP_DSPI_DMA_INVALID
Definition: app_dspi.h:172
app_dma.h
Header file containing functions prototypes of DMA app library.
app_dspi_params_t::pin_cfg
app_dspi_pin_cfg_t pin_cfg
Definition: app_dspi.h:200
app_dspi_pin_t::pin
uint32_t pin
Definition: app_dspi.h:101
app_dspi_dma_cfg_t
DSPI DMA configuration Structures.
Definition: app_dspi.h:123
app_dspi_get_handle
dspi_handle_t * app_dspi_get_handle(void)
Return the DSPI handle.
app_dspi_command_t
dspi_command_t app_dspi_command_t
DSPI command structure definition.
Definition: app_dspi.h:148
app_dspi_config_mode
uint16_t app_dspi_config_mode(uint32_t mode)
Set the DSPI transmission mode.
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:255
app_dspi_pin_cfg_t
DSPI Transmission IO configuration Structures.
Definition: app_dspi.h:111
app_dspi_evt_t
DSPI event structure definition.
Definition: app_dspi.h:131
app_dspi_command_sync
uint16_t app_dspi_command_sync(app_dspi_command_t *p_cmd, uint32_t timeout)
Transmit only instruction in blocking mode.
app_dspi_dma_cfg_t::channel
dma_channel_t channel
Definition: app_dspi.h:124
app_dspi_deinit
uint16_t app_dspi_deinit(void)
De-initialize the APP DSPI DRIVER peripheral.
app_drv_error.h
Header file of app driver error code.
app_drv_config.h
Header file of app driver config code.
dma_id_t
int16_t dma_id_t
DMA id definition.
Definition: app_dma.h:98
APP_DSPI_INVALID
@ APP_DSPI_INVALID
Definition: app_dspi.h:162
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:94
app_dspi_evt_handler_t
void(* app_dspi_evt_handler_t)(app_dspi_evt_t *p_evt)
DSPI event callback definition.
Definition: app_dspi.h:153