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 "gr55xx_hal.h"
56 #include "ring_buffer.h"
57 #include "app_io.h"
58 
59 #ifdef ENV_USE_FREERTOS
60 #include "app_rtos_cfg.h"
61 #endif
62 
63 #ifdef __cplusplus
64 extern "C" {
65 #endif
66 
67 #ifdef HAL_UART_MODULE_ENABLED
68 
69 /** @addtogroup APP_UART_ENUMERATIONS Enumertations
70  * @{
71  */
72 
73 /**
74  * @brief UART module Enumerations definition
75  */
76 typedef enum
77 {
78  APP_UART_ID_0, /**< UART module 0 */
79  APP_UART_ID_1, /**< UART module 1 */
80  APP_UART_ID_MAX, /**< Only for check parameter, not used as input parameters. */
82 
83 /**
84  * @brief UART operating mode Enumerations definition
85  */
86 typedef enum
87 {
88  APP_UART_TYPE_INTERRUPT, /**< Interrupt operation mode */
89  APP_UART_TYPE_POLLING, /**< Polling operation mode */
90  APP_UART_TYPE_DMA, /**< DMA operation mode */
91  APP_UART_TYPE_MAX, /**< Only for check parameter, not used as input parameters. */
93 
94 /**
95  * @brief UART event Enumerations definition
96  */
97 typedef enum
98 {
99  APP_UART_EVT_ERROR, /**< Error reported by UART peripheral. */
100  APP_UART_EVT_TX_CPLT, /**< Requested TX transfer completed. */
101  APP_UART_EVT_RX_DATA, /**< Requested RX transfer completed. */
102  APP_UART_EVT_ABORT_TX, /**< Requested TX abort completed. */
103  APP_UART_EVT_ABORT_RX, /**< Requested RX abort completed. */
105 
106 /** @} */
107 
108 /** @addtogroup APP_UART_STRUCTURES Structures
109  * @{
110  */
111 
112 /**
113  * @brief UART IO Structures
114  */
115 typedef struct
116 {
117  app_io_type_t type; /**< Specifies the type of UART IO. */
118  app_io_mux_t mux; /**< Specifies the Peripheral to be connected to the selected pins. */
119  uint32_t pin; /**< Specifies the IO pins to be configured.
120  This parameter can be any value of @ref GR551x_pins. */
121  app_io_pull_t pull; /**< Specifies the Pull-up or Pull-Down activation for the selected pins. */
122 
124 
125 /**
126  * @brief UART IO configuration Structures
127  */
128 typedef struct
129 {
130  app_uart_pin_t tx; /**< Set the configuration of UART TX pin. */
131  app_uart_pin_t rx; /**< Set the configuration of UART RX pin. */
132  app_uart_pin_t cts; /**< Set the configuration of UART CTS pin. */
133  app_uart_pin_t rts; /**< Set the configuration of UART RTS pin. */
135 
136 /**
137  * @brief UART operate mode Enumerations definition
138  */
139 typedef struct
140 {
141  app_uart_type_t type; /**< Specifies the operation mode of UART. */
142  dma_channel_t tx_dma_channel; /**< Specifies the dma channel of UART TX. */
143  dma_channel_t rx_dma_channel; /**< Specifies the dma channel of UART RX. */
145 
146 /**
147  * @brief UART parameters structure definition
148  */
149 typedef struct
150 {
151  app_uart_id_t id; /**< specified UART module ID. */
152  app_uart_pin_cfg_t pin_cfg; /**< the pin configuration information for the specified UART module. */
153  app_uart_mode_t use_mode; /**< UART operate mode. */
154  uart_init_t init; /**< UART communication parameters. */
156 
157 /**
158  * @brief UART event structure definition
159  */
160 typedef struct
161 {
162  app_uart_evt_type_t type; /**< Type of event. */
163  union
164  {
165  uint32_t error_code; /**< UART Error code . */
166  uint16_t size; /**< UART transmitted/received counter. */
167  } data; /**< UART event data. */
169 
170 /**
171  * @brief UART event callback definition
172  */
173 typedef void (*app_uart_evt_handler_t)(app_uart_evt_t *p_evt);
174 
175 /**
176  * @brief UART buffer structure definition
177  */
178 typedef struct
179 {
180  uint8_t * tx_buf; /**< Pointer to the TX buffer. */
181  uint32_t tx_buf_size; /**< Size of the TX buffer. */
183 /** @} */
184 
185 
186 /* Exported functions --------------------------------------------------------*/
187 /** @addtogroup APP_UART_DRIVER_FUNCTIONS Functions
188  * @{
189  */
190 /**
191  ****************************************************************************************
192  * @brief Initialize the APP UART DRIVER according to the specified parameters
193  * in the app_uart_params_t and app_uart_evt_handler_t.
194  *
195  * @param[in] p_params: Pointer to app_uart_params_t parameter which contains the
196  * configuration information for the specified UART module.
197  * @param[in] evt_handler: UART user callback function.
198  * @param[in] tx_buffer: Pointer to tx send buffer.
199  *
200  * @return Result of initialization.
201  ****************************************************************************************
202  */
203 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);
204 
205 /**
206  ****************************************************************************************
207  * @brief De-initialize the APP UART DRIVER peripheral.
208  *
209  * @param[in] id: De-initialize for a specific ID.
210  *
211  * @return Result of De-initialization.
212  ****************************************************************************************
213  */
215 
216 /**
217  ****************************************************************************************
218  * @brief Send an amount of data in interrupt mode.
219  *
220  * @param[in] id: which UART module want to receive.
221  * @param[in] p_data: Pointer to data buffer
222  * @param[in] size: Amount of data to be sent
223  *
224  * @return Result of operation.
225  ****************************************************************************************
226  */
227 uint16_t app_uart_transmit_async(app_uart_id_t id, uint8_t *p_data, uint16_t size);
228 
229 /**
230  ****************************************************************************************
231  * @brief Send an amount of data in blocking mode.
232  *
233  * @param[in] id: which UART module want to receive.
234  * @param[in] p_data: Pointer to data buffer
235  * @param[in] size: Amount of data to be sent
236  * @param[in] timeout: Timeout duration
237  *
238  * @return Result of operation.
239  ****************************************************************************************
240  */
241 uint16_t app_uart_transmit_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout);
242 
243 /**
244  ****************************************************************************************
245  * @brief Receive an amount of data in interrupt mode.
246  *
247  * @param[in] id: which UART module want to transmit.
248  * @param[in] p_data: Pointer to data buffer
249  * @param[in] size: Amount of data to be sent
250  *
251  * @return Result of operation.
252  ****************************************************************************************
253  */
254 uint16_t app_uart_receive_async(app_uart_id_t id, uint8_t *p_data, uint16_t size);
255 
256 /**
257  ****************************************************************************************
258  * @brief Receive an amount of data in blocking mode.
259  *
260  * @param[in] id: which UART module want to transmit.
261  * @param[in] p_data: Pointer to data buffer
262  * @param[in] size: Amount of data to be sent
263  * @param[in] timeout: Timeout duration
264  *
265  * @return Result of operation.
266  ****************************************************************************************
267  */
268 uint16_t app_uart_receive_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size, uint32_t timeout);
269 
270 /**
271  ****************************************************************************************
272  * @brief Return the UART handle.
273  *
274  * @param[in] id: UART Channel ID.
275  *
276  * @return Pointer to the specified ID's UART handle.
277  ****************************************************************************************
278  */
280 
281 /**
282  *****************************************************************************************
283  * @brief Flush all log entries from the buffer
284  *
285  * @param[in] id: UART Channel ID.
286  *
287  *****************************************************************************************
288  */
290 
291 
292 #ifdef ENV_RTOS_USE_SEMP
293 /**
294  ****************************************************************************************
295  * @brief [RTOS] Receive an amount of data in blocking mode.
296  *
297  * @param[in] id: which UART module want to transmit.
298  * @param[in] p_data: Pointer to data buffer
299  * @param[in] size: Amount of data to be sent
300  *
301  * @return Result of operation.
302  ****************************************************************************************
303  */
304 uint16_t app_uart_receive_sem_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size);
305 
306 /**
307  ****************************************************************************************
308  * @brief [RTOS] Send an amount of data in blocking mode.
309  *
310  * @param[in] id: which UART module want to receive.
311  * @param[in] p_data: Pointer to data buffer
312  * @param[in] size: Amount of data to be sent
313  *
314  * @return Result of operation.
315  ****************************************************************************************
316  */
317 uint16_t app_uart_transmit_sem_sync(app_uart_id_t id, uint8_t *p_data, uint16_t size);
318 
319 #endif
320 
321 /** @} */
322 
323 #endif
324 
325 #ifdef __cplusplus
326 }
327 #endif
328 
329 #endif
330 
331 /** @} */
332 /** @} */
333 /** @} */
334 
335 
app_uart_pin_cfg_t::rx
app_uart_pin_t rx
Set the configuration of UART RX pin.
Definition: app_uart.h:131
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:152
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:121
app_uart_params_t::init
uart_init_t init
UART communication parameters.
Definition: app_uart.h:154
APP_UART_EVT_ABORT_RX
@ APP_UART_EVT_ABORT_RX
Requested RX abort completed.
Definition: app_uart.h:103
app_uart_evt_type_t
app_uart_evt_type_t
UART event Enumerations definition.
Definition: app_uart.h:98
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.
APP_UART_TYPE_MAX
@ APP_UART_TYPE_MAX
Only for check parameter, not used as input parameters.
Definition: app_uart.h:91
app_uart_params_t::use_mode
app_uart_mode_t use_mode
UART operate mode.
Definition: app_uart.h:153
app_uart_params_t::id
app_uart_id_t id
specified UART module ID.
Definition: app_uart.h:151
APP_UART_TYPE_POLLING
@ APP_UART_TYPE_POLLING
Polling operation mode
Definition: app_uart.h:89
app_uart_pin_cfg_t::cts
app_uart_pin_t cts
Set the configuration of UART CTS pin.
Definition: app_uart.h:132
app_uart_deinit
uint16_t app_uart_deinit(app_uart_id_t id)
De-initialize the APP UART DRIVER peripheral.
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:187
app_io_type_t
app_io_type_t
GPIO type Enumerations definition.
Definition: app_io.h:141
APP_UART_EVT_ABORT_TX
@ APP_UART_EVT_ABORT_TX
Requested TX abort completed.
Definition: app_uart.h:102
_uart_handle
UART handle Structure definition.
Definition: gr55xx_hal_uart.h:153
app_uart_params_t
UART parameters structure definition.
Definition: app_uart.h:150
app_uart_mode_t::tx_dma_channel
dma_channel_t tx_dma_channel
Specifies the dma channel of UART TX.
Definition: app_uart.h:142
app_uart_tx_buf_t
UART buffer structure definition.
Definition: app_uart.h:179
app_uart_tx_buf_t::tx_buf_size
uint32_t tx_buf_size
Size of the TX buffer.
Definition: app_uart.h:181
app_uart_pin_cfg_t::tx
app_uart_pin_t tx
Set the configuration of UART TX pin.
Definition: app_uart.h:130
app_uart_mode_t
UART operate mode Enumerations definition.
Definition: app_uart.h:140
_uart_init
UART init structure definition.
Definition: gr55xx_hal_uart.h:120
APP_UART_ID_0
@ APP_UART_ID_0
UART module 0.
Definition: app_uart.h:78
app_io.h
Header file containing functions prototypes of GPIO app library.
app_uart_tx_buf_t::tx_buf
uint8_t * tx_buf
Pointer to the TX buffer.
Definition: app_uart.h:180
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:173
app_uart_evt_t::type
app_uart_evt_type_t type
Type of event.
Definition: app_uart.h:162
APP_UART_EVT_RX_DATA
@ APP_UART_EVT_RX_DATA
Requested RX transfer completed.
Definition: app_uart.h:101
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_evt_t
UART event structure definition.
Definition: app_uart.h:161
app_uart_evt_t::size
uint16_t size
UART transmitted/received counter.
Definition: app_uart.h:166
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:80
app_uart_mode_t::type
app_uart_type_t type
Specifies the operation mode of UART.
Definition: app_uart.h:141
gr55xx_hal.h
This file contains all the functions prototypes for the HAL module driver.
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_TYPE_INTERRUPT
@ APP_UART_TYPE_INTERRUPT
Interrupt operation mode.
Definition: app_uart.h:88
app_uart_pin_t::mux
app_io_mux_t mux
Specifies the Peripheral to be connected to the selected pins.
Definition: app_uart.h:118
app_uart_id_t
app_uart_id_t
UART module Enumerations definition.
Definition: app_uart.h:77
app_io_mux_t
app_io_mux_t
GPIO mux Enumerations definition.
Definition: app_io.h:198
app_uart_pin_cfg_t::rts
app_uart_pin_t rts
Set the configuration of UART RTS pin.
Definition: app_uart.h:133
app_uart_pin_t::pin
uint32_t pin
Specifies the IO pins to be configured.
Definition: app_uart.h:119
APP_UART_TYPE_DMA
@ APP_UART_TYPE_DMA
DMA operation mode
Definition: app_uart.h:90
app_uart_pin_cfg_t
UART IO configuration Structures.
Definition: app_uart.h:129
app_uart_evt_t::error_code
uint32_t error_code
UART Error code .
Definition: app_uart.h:165
APP_UART_EVT_ERROR
@ APP_UART_EVT_ERROR
Error reported by UART peripheral.
Definition: app_uart.h:99
app_rtos_cfg.h
Header file of app rtos config code.
app_uart_pin_t
UART IO Structures.
Definition: app_uart.h:116
app_uart_flush
void app_uart_flush(app_uart_id_t id)
Flush all log entries from the buffer.
app_uart_type_t
app_uart_type_t
UART operating mode Enumerations definition.
Definition: app_uart.h:87
APP_UART_ID_1
@ APP_UART_ID_1
UART module 1.
Definition: app_uart.h:79
app_uart_pin_t::type
app_io_type_t type
Specifies the type of UART IO.
Definition: app_uart.h:117
app_uart_mode_t::rx_dma_channel
dma_channel_t rx_dma_channel
Specifies the dma channel of UART RX.
Definition: app_uart.h:143
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:100