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