app_uart.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file app_uart.h
5 * @author BLE Driver Team
6 * @brief Header file containing functions prototypes of UART 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
38 /** @addtogroup PERIPHERAL Peripheral Driver
39 * @{
40 */
41
42 /** @addtogroup APP_DRIVER APP DRIVER
43 * @{
44 */
45
46 /** @defgroup APP_UART UART
47 * @brief UART APP module driver.
48 * @{
49 */
50
51
52 #ifndef _APP_UART_H_
53 #define _APP_UART_H_
54
55 #include "grx_hal.h"
56 #include "ring_buffer.h"
57 #include "app_io.h"
58 #include "app_dma.h"
59 #include "app_drv_config.h"
60
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64
65 #ifdef HAL_UART_MODULE_ENABLED
66
67 /** @addtogroup APP_UART_MACRO Defines
68 * @{
69 */
70 #ifndef TX_ONCE_MAX_SIZE
71 #define TX_ONCE_MAX_SIZE 128 /**< UART max bytes size transmitted at one time */
72 #endif
73
74 /** @} */
75
76 /** @addtogroup APP_UART_ENUMERATIONS Enumerations
77 * @{
78 */
79
80 /**
81 * @brief UART module Enumerations definition
82 */
83 typedef enum
84 {
85 APP_UART_ID_0, /**< UART module 0. */
86 APP_UART_ID_1, /**< UART module 1. */
87 #if ((APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR5525X) || (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR5526X))
88 APP_UART_ID_2, /**< UART module 2. */
89 APP_UART_ID_3, /**< UART module 3. */
90 #endif
91 #if (APP_DRIVER_CHIP_TYPE == APP_DRIVER_GR5526X)
92 APP_UART_ID_4, /**< UART module 4. */
93 APP_UART_ID_5, /**< UART module 5. */
94 #endif
95 APP_UART_ID_MAX, /**< Only for check parameter, not used as input parameters. */
96 } app_uart_id_t;
97
98 /**
99 * @brief UART event Enumerations definition
100 */
101 typedef enum
102 {
103 APP_UART_EVT_ERROR, /**< Error reported by UART peripheral. */
104 APP_UART_EVT_TX_CPLT, /**< Requested TX transfer completed. */
105 APP_UART_EVT_RX_DATA, /**< Requested RX transfer completed. */
106 APP_UART_EVT_ABORT_TX, /**< Requested TX abort completed. */
107 APP_UART_EVT_ABORT_RX, /**< Requested RX abort completed. */
108 APP_UART_EVT_ABORT_TXRX, /**< Requested TX, RX abort completed. */
109 } app_uart_evt_type_t;
110
111 /**@brief App uart state types. */
112 typedef enum
113 {
114 APP_UART_INVALID = 0,
115 APP_UART_ACTIVITY,
116 #ifdef APP_DRIVER_WAKEUP_CALL_FUN
117 APP_UART_SLEEP,
118 #endif
119 } app_uart_state_t;
120
121 /** @} */
122
123 /** @addtogroup APP_UART_STRUCTURES Structures
124 * @{
125 */
126
127 /**
128 * @brief UART pins Structures
129 */
130 typedef struct
131 {
132 app_io_type_t type; /**< Specifies the type of UART 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 GR5xxx_pins. */
136 app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
137
138 } app_uart_pin_t;
139
140 /**
141 * @brief UART pins config Structures
142 */
143 typedef struct
144 {
145 app_uart_pin_t tx; /**< Set the configuration of UART TX pin. */
146 app_uart_pin_t rx; /**< Set the configuration of UART RX pin. */
147 app_uart_pin_t cts; /**< Set the configuration of UART CTS pin. */
148 app_uart_pin_t rts; /**< Set the configuration of UART RTS pin. */
149 } app_uart_pin_cfg_t;
150
151 /**
152 * @brief UART DMA configuration structure definition
153 */
154 typedef struct
155 {
156 dma_regs_t *tx_dma_instance;/**< Specifies the TX DMA instance.*/
157 dma_regs_t *rx_dma_instance;/**< Specifies the RX DMA instance.*/
158 dma_channel_t tx_dma_channel; /**< Specifies the dma channel of UART TX. */
159 dma_channel_t rx_dma_channel; /**< Specifies the dma channel of UART RX. */
160 } app_uart_dma_cfg_t;
161
162 /** @} */
163
164 /** @addtogroup APP_UART_ENUMERATIONS Enumerations
165 * @{
166 */
167 /**@brief App uart dma state types. */
168 typedef enum
169 {
170 APP_UART_DMA_INVALID = 0,
171 APP_UART_DMA_ACTIVITY,
172 } app_uart_dma_state_t;
173
174 /** @} */
175
176 /** @addtogroup APP_UART_STRUCTURES Structures
177 * @{
178 */
179 /**
180 * @brief UART event structure definition
181 */
182 typedef struct
183 {
184 app_uart_evt_type_t type; /**< Type of event. */
185 union
186 {
187 uint32_t error_code; /**< UART Error code . */
188 uint16_t size; /**< UART transmitted/received counter. */
189 } data; /**< Data of event. */
190 } app_uart_evt_t;
191
192 /** @} */
193
194 /** @addtogroup APP_UART_TYPEDEFS Type definitions
195 * @{
196 */
197
198 /**
199 * @brief UART event callback definition
200 */
201 typedef void (*app_uart_evt_handler_t)(app_uart_evt_t *p_evt);
202
203 /** @} */
204
205 /** @addtogroup APP_UART_STRUCTURES Structures
206 * @{
207 */
208
209
210 /**
211 * @brief UART device structure definition
212 */
213 typedef struct
214 {
215 app_uart_evt_handler_t evt_handler; /**< UART event callback. */
216 uart_handle_t handle; /**< UART handle Structure. */
217 app_uart_pin_cfg_t *p_pin_cfg; /**< UART pins config Structures. */
218 dma_id_t dma_id[2]; /**< DMA id. */
219 app_uart_state_t uart_state; /**< App uart state types. */
220 app_uart_dma_state_t uart_dma_state; /**< App uart dma state types. */
221 ring_buffer_t tx_ring_buffer; /**< RING_BUFFER_STRUCT Structures. */
222 uint8_t tx_send_buf[TX_ONCE_MAX_SIZE]; /**< tx send buf. */
223 volatile bool start_tx_flag; /**< start tx flag. */
224 volatile bool start_flush_flag; /**< start flush flag. */
225 bool tx_abort_flag; /**< tx abort flag. */
226 bool rx_abort_flag; /**< rx abort flag. */
227 bool is_dma_tx_mode; /**< dma tx mode. */
228 } uart_env_t;
229
230 /**
231 * @brief UART parameters structure definition
232 */
233 typedef struct
234 {
235 app_uart_id_t id; /**< specified UART module ID. */
236 app_uart_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified UART module. */
237 app_uart_dma_cfg_t dma_cfg; /**< UART DMA configuration. */
238 uart_init_t init; /**< UART communication parameters. */
239 uart_env_t uart_dev; /**< UART event data. */
240 } app_uart_params_t;
241
242 /**
243 * @brief UART buffer structure definition
244 */
245 typedef struct
246 {
247 //lint -e18 A symbol was declared in a typedef differently in two different modules is necessary
248 uint8_t * tx_buf; /**< Pointer to the TX buffer. */
249 uint32_t tx_buf_size; /**< Size of the TX buffer. */
250 } app_uart_tx_buf_t;
251 /** @} */
252
253 /* Exported functions --------------------------------------------------------*/
254 /** @addtogroup APP_UART_DRIVER_FUNCTIONS Functions
255 * @{
256 */
257 /**
258 ****************************************************************************************
259 * @brief Initialize the APP UART DRIVER according to the specified parameters
260 * in the app_uart_params_t and app_uart_evt_handler_t.
261 *
262 * @param[in] p_params: Pointer to app_uart_params_t parameter which contains the
263 * configuration information for the specified UART module.
264 * @param[in] evt_handler: UART user callback function.
265 * @param[in] tx_buffer: Pointer to tx send buffer.
266 *
267 * @return Result of initialization.
268 ****************************************************************************************
269 */
270 uint16_t app_uart_init(app_uart_params_t *p_params, app_uart_evt_handler_t evt_handler, app_uart_tx_buf_t *tx_buffer);
271
272 /**
273 ****************************************************************************************
274 * @brief De-initialize the APP UART DRIVER peripheral.
275 *
276 * @param[in] id: De-initialize for a specific ID.
277 *
278 * @return Result of De-initialization.
279 ****************************************************************************************
280 */
281 uint16_t app_uart_deinit(app_uart_id_t id);
282
283 /**
284 ****************************************************************************************
285 * @brief Send an amount of data in interrupt mode.
286 *
287 * @param[in] id: which UART module want to receive.
288 * @param[in] p_data: Pointer to data buffer
289 * @param[in] size: Amount of data to be sent
290 *
291 * @return Result of operation.
292 ****************************************************************************************
293 */
294 uint16_t app_uart_transmit_async(app_uart_id_t id, uint8_t *p_data, uint16_t size);
295
296 /**
297 ****************************************************************************************
298 * @brief Send an amount of data in blocking mode.
299 *
300 * @param[in] id: which UART module want to receive.
301 * @param[in] p_data: Pointer to data buffer
302 * @param[in] size: Amount of data to be sent
303 * @param[in] timeout: Timeout duration
304 *
305 * @return Result of operation.
306 ****************************************************************************************
307 */
308 uint16_t app_uart_transmit_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout);
309
310 /**
311 ****************************************************************************************
312 * @brief Receive an amount of data in interrupt mode.
313 *
314 * @param[in] id: which UART module want to transmit.
315 * @param[in] p_data: Pointer to data buffer
316 * @param[in] size: Amount of data to be sent
317 *
318 * @return Result of operation.
319 ****************************************************************************************
320 */
321 uint16_t app_uart_receive_async(app_uart_id_t id, uint8_t *p_data, uint16_t size);
322
323 /**
324 ****************************************************************************************
325 * @brief Receive an amount of data in blocking mode.
326 *
327 * @param[in] id: which UART module want to transmit.
328 * @param[in] p_data: Pointer to data buffer
329 * @param[in] size: Amount of data to be sent
330 * @param[in] timeout: Timeout duration
331 *
332 * @return Result of operation.
333 ****************************************************************************************
334 */
335 uint16_t app_uart_receive_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout);
336
337 /**
338 ****************************************************************************************
339 * @brief Return the UART handle.
340 *
341 * @param[in] id: UART Channel ID.
342 *
343 * @return Pointer to the specified ID's UART handle.
344 ****************************************************************************************
345 */
346 uart_handle_t *app_uart_get_handle(app_uart_id_t id);
347
348 /**
349 *****************************************************************************************
350 * @brief Flush all log entries from the buffer
351 *
352 * @param[in] id: UART Channel ID.
353 *
354 *****************************************************************************************
355 */
356 void app_uart_flush(app_uart_id_t id);
357
358 /**
359 ****************************************************************************************
360 * @brief Abort transmit and receive process and generate abort callback.
361 *
362 * @param[in] id: which UART module want to use.
363 *
364 * @return Result of operation.
365 ****************************************************************************************
366 */
367 uint16_t app_uart_abort(app_uart_id_t id);
368
369 /**
370 ****************************************************************************************
371 * @brief Abort transmit process and generate abort transmit callback.
372 *
373 * @param[in] id: which UART module want to use.
374 *
375 * @return Result of operation.
376 ****************************************************************************************
377 */
378 uint16_t app_uart_abort_transmit(app_uart_id_t id);
379
380 /**
381 ****************************************************************************************
382 * @brief Abort receive process and generate abort receive callback.
383 *
384 * @param[in] id: which UART module want to use.
385 *
386 * @return Result of operation.
387 ****************************************************************************************
388 */
389 uint16_t app_uart_abort_receive(app_uart_id_t id);
390
391 /** @} */
392
393 #endif
394
395 #ifdef __cplusplus
396 }
397 #endif
398
399 #endif
400
401 /** @} */
402
403 /** @} */
404
405 /** @} */
406
app_uart_pin_cfg_t::rx
app_uart_pin_t rx
Set the configuration of UART RX pin.
Definition: app_uart.h:146
uart_env_t::uart_dma_state
app_uart_dma_state_t uart_dma_state
App uart dma state types.
Definition: app_uart.h:220
app_uart_params_t::pin_cfg
app_uart_pin_cfg_t pin_cfg
the pin configuration information for the specified UART module.
Definition: app_uart.h:236
app_uart_pin_t::pull
app_io_pull_t pull
Specifies the Pull-up or Pull-Down activation for the selected pins.
Definition: app_uart.h:136
uart_env_t::evt_handler
app_uart_evt_handler_t evt_handler
UART event callback.
Definition: app_uart.h:215
app_uart_params_t::init
uart_init_t init
UART communication parameters.
Definition: app_uart.h:238
APP_UART_EVT_ABORT_RX
@ APP_UART_EVT_ABORT_RX
Requested RX abort completed.
Definition: app_uart.h:107
app_uart_evt_type_t
app_uart_evt_type_t
UART event Enumerations definition.
Definition: app_uart.h:102
app_uart_dma_state_t
app_uart_dma_state_t
App uart dma state types.
Definition: app_uart.h:169
app_uart_transmit_sync
uint16_t app_uart_transmit_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout)
Send an amount of data in blocking mode.
uart_env_t::is_dma_tx_mode
bool is_dma_tx_mode
dma tx mode.
Definition: app_uart.h:227
app_uart_params_t::id
app_uart_id_t id
specified UART module ID.
Definition: app_uart.h:235
uart_env_t::tx_ring_buffer
ring_buffer_t tx_ring_buffer
RING_BUFFER_STRUCT Structures.
Definition: app_uart.h:221
app_uart_pin_cfg_t::cts
app_uart_pin_t cts
Set the configuration of UART CTS pin.
Definition: app_uart.h:147
app_uart_dma_cfg_t::tx_dma_channel
dma_channel_t tx_dma_channel
Specifies the dma channel of UART TX.
Definition: app_uart.h:158
uart_env_t::uart_state
app_uart_state_t uart_state
App uart state types.
Definition: app_uart.h:219
app_uart_deinit
uint16_t app_uart_deinit(app_uart_id_t id)
De-initialize the APP UART DRIVER peripheral.
app_uart_abort
uint16_t app_uart_abort(app_uart_id_t id)
Abort transmit and receive process and generate abort callback.
app_uart_init
uint16_t app_uart_init(app_uart_params_t *p_params, app_uart_evt_handler_t evt_handler, app_uart_tx_buf_t *tx_buffer)
Initialize the APP UART DRIVER according to the specified parameters in the app_uart_params_t and app...
app_io_pull_t
app_io_pull_t
GPIO pull Enumerations definition.
Definition: app_io.h:183
app_uart_state_t
app_uart_state_t
App uart state types.
Definition: app_uart.h:113
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:147
app_uart_dma_cfg_t::rx_dma_channel
dma_channel_t rx_dma_channel
Specifies the dma channel of UART RX.
Definition: app_uart.h:159
APP_UART_EVT_ABORT_TX
@ APP_UART_EVT_ABORT_TX
Requested TX abort completed.
Definition: app_uart.h:106
APP_UART_DMA_INVALID
@ APP_UART_DMA_INVALID
Definition: app_uart.h:170
APP_UART_DMA_ACTIVITY
@ APP_UART_DMA_ACTIVITY
Definition: app_uart.h:171
uart_env_t::start_flush_flag
volatile bool start_flush_flag
start flush flag.
Definition: app_uart.h:224
uart_env_t::tx_abort_flag
bool tx_abort_flag
tx abort flag.
Definition: app_uart.h:225
_uart_handle
UART handle Structure definition.
Definition: gr55xx_hal_uart.h:153
app_uart_params_t
UART parameters structure definition.
Definition: app_uart.h:234
app_uart_tx_buf_t
UART buffer structure definition.
Definition: app_uart.h:246
app_uart_tx_buf_t::tx_buf_size
uint32_t tx_buf_size
Size of the TX buffer.
Definition: app_uart.h:249
app_uart_pin_cfg_t::tx
app_uart_pin_t tx
Set the configuration of UART TX pin.
Definition: app_uart.h:145
_uart_init
UART init structure definition.
Definition: gr55xx_hal_uart.h:120
app_uart_dma_cfg_t::rx_dma_instance
dma_regs_t * rx_dma_instance
Specifies the RX DMA instance.
Definition: app_uart.h:157
APP_UART_ID_0
@ APP_UART_ID_0
UART module 0.
Definition: app_uart.h:85
APP_UART_ACTIVITY
@ APP_UART_ACTIVITY
Definition: app_uart.h:115
app_io.h
Header file containing functions prototypes of GPIO app library.
app_uart_abort_receive
uint16_t app_uart_abort_receive(app_uart_id_t id)
Abort receive process and generate abort receive callback.
app_uart_tx_buf_t::tx_buf
uint8_t * tx_buf
Pointer to the TX buffer.
Definition: app_uart.h:248
APP_UART_EVT_ABORT_TXRX
@ APP_UART_EVT_ABORT_TXRX
Requested TX, RX abort completed.
Definition: app_uart.h:108
app_uart_evt_t::type
app_uart_evt_type_t type
Type of event.
Definition: app_uart.h:184
APP_UART_EVT_RX_DATA
@ APP_UART_EVT_RX_DATA
Requested RX transfer completed.
Definition: app_uart.h:105
app_uart_receive_sync
uint16_t app_uart_receive_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout)
Receive an amount of data in blocking mode.
app_uart_params_t::uart_dev
uart_env_t uart_dev
UART event data.
Definition: app_uart.h:239
grx_hal.h
This file contains all the functions prototypes for the HAL module driver.
app_uart_evt_handler_t
void(* app_uart_evt_handler_t)(app_uart_evt_t *p_evt)
UART event callback definition.
Definition: app_uart.h:201
uart_env_t
UART device structure definition.
Definition: app_uart.h:214
app_uart_dma_cfg_t::tx_dma_instance
dma_regs_t * tx_dma_instance
Specifies the TX DMA instance.
Definition: app_uart.h:156
uart_env_t::p_pin_cfg
app_uart_pin_cfg_t * p_pin_cfg
UART pins config Structures.
Definition: app_uart.h:217
app_uart_evt_t
UART event structure definition.
Definition: app_uart.h:183
app_uart_evt_t::size
uint16_t size
UART transmitted/received counter.
Definition: app_uart.h:188
app_uart_receive_async
uint16_t app_uart_receive_async(app_uart_id_t id, uint8_t *p_data, uint16_t size)
Receive an amount of data in interrupt mode.
APP_UART_ID_MAX
@ APP_UART_ID_MAX
Only for check parameter, not used as input parameters.
Definition: app_uart.h:95
app_dma.h
Header file containing functions prototypes of DMA app library.
app_uart_dma_cfg_t
UART DMA configuration structure definition.
Definition: app_uart.h:155
app_uart_transmit_async
uint16_t app_uart_transmit_async(app_uart_id_t id, uint8_t *p_data, uint16_t size)
Send an amount of data in interrupt mode.
app_uart_get_handle
uart_handle_t * app_uart_get_handle(app_uart_id_t id)
Return the UART handle.
app_uart_params_t::dma_cfg
app_uart_dma_cfg_t dma_cfg
UART DMA configuration.
Definition: app_uart.h:237
APP_UART_INVALID
@ APP_UART_INVALID
Definition: app_uart.h:114
app_uart_pin_t::mux
app_io_mux_t mux
Specifies the Peripheral to be connected to the selected pins.
Definition: app_uart.h:133
uart_env_t::rx_abort_flag
bool rx_abort_flag
rx abort flag.
Definition: app_uart.h:226
uart_env_t::handle
uart_handle_t handle
UART handle Structure.
Definition: app_uart.h:216
app_uart_id_t
app_uart_id_t
UART module Enumerations definition.
Definition: app_uart.h:84
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:255
app_uart_pin_cfg_t::rts
app_uart_pin_t rts
Set the configuration of UART RTS pin.
Definition: app_uart.h:148
app_uart_pin_t::pin
uint32_t pin
Specifies the IO pins to be configured.
Definition: app_uart.h:134
app_uart_pin_cfg_t
UART pins config Structures.
Definition: app_uart.h:144
app_uart_evt_t::error_code
uint32_t error_code
UART Error code .
Definition: app_uart.h:187
APP_UART_EVT_ERROR
@ APP_UART_EVT_ERROR
Error reported by UART peripheral.
Definition: app_uart.h:103
app_drv_config.h
Header file of app driver config code.
app_uart_pin_t
UART pins Structures.
Definition: app_uart.h:131
uart_env_t::start_tx_flag
volatile bool start_tx_flag
start tx flag.
Definition: app_uart.h:223
app_uart_flush
void app_uart_flush(app_uart_id_t id)
Flush all log entries from the buffer.
APP_UART_ID_1
@ APP_UART_ID_1
UART module 1.
Definition: app_uart.h:86
app_uart_pin_t::type
app_io_type_t type
Specifies the type of UART IO.
Definition: app_uart.h:132
TX_ONCE_MAX_SIZE
#define TX_ONCE_MAX_SIZE
UART max bytes size transmitted at one time.
Definition: app_uart.h:71
dma_id_t
int16_t dma_id_t
DMA id definition.
Definition: app_dma.h:98
dma_channel_t
dma_channel_t
HAL DMA Channel Enumerations definition.
Definition: gr55xx_hal_dma.h:93
APP_UART_EVT_TX_CPLT
@ APP_UART_EVT_TX_CPLT
Requested TX transfer completed.
Definition: app_uart.h:104
app_uart_abort_transmit
uint16_t app_uart_abort_transmit(app_uart_id_t id)
Abort transmit process and generate abort transmit callback.