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