1 /** 2 **************************************************************************************** 3 * 4 * @file gr55xx_hal_uart.h 5 * @author BLE Driver Team 6 * @brief Header file containing functions prototypes of UART HAL 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 HAL_DRIVER HAL Driver 43 * @{ 44 */ 45 46 /** @defgroup HAL_UART UART 47 * @brief UART HAL module driver. 48 * @{ 49 */ 50 51 /* Define to prevent recursive inclusion -------------------------------------*/ 52 #ifndef __GR55xx_HAL_UART_H__ 53 #define __GR55xx_HAL_UART_H__ 54 55 /* Includes ------------------------------------------------------------------*/ 56 #include "gr55xx_ll_uart.h" 57 #include "gr55xx_hal_def.h" 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 /* Exported types ------------------------------------------------------------*/ 64 /** @addtogroup HAL_UART_ENUMERATIONS Enumerations 65 * @{ 66 */ 67 68 /** @defgroup HAL_UART_state HAL UART state 69 * @{ 70 */ 71 72 /** 73 * @brief HAL UART State enumerations definition 74 * @note HAL UART State value is a combination of 2 different substates: gState and RxState. 75 */ 76 typedef enum { 77 HAL_UART_STATE_RESET = 0x00U, /**< Peripheral is not initialized. 78 Value is allowed for gState and RxState */ 79 80 HAL_UART_STATE_READY = 0x10U, /**< Peripheral initialized and ready for use. 81 Value is allowed for gState and RxState */ 82 83 HAL_UART_STATE_BUSY = 0x14U, /**< An internal process is ongoing. 84 Value is allowed for gState only */ 85 86 HAL_UART_STATE_BUSY_TX = 0x11U, /**< Data Transmission process is ongoing. 87 Value is allowed for gState only */ 88 89 HAL_UART_STATE_BUSY_RX = 0x12U, /**< Data Reception process is ongoing. 90 Value is allowed for RxState only */ 91 92 HAL_UART_STATE_BUSY_TXRX = 0x13U, /**< Data Transmission and Reception process is ongoing. 93 Value is allowed for gState only */ 94 95 HAL_UART_STATE_TIMEOUT = 0x30U, /**< Timeout state. 96 Value is allowed for gState only */ 97 98 HAL_UART_STATE_ERROR = 0x70U /**< Error. 99 Value is allowed for gState only */ 100 } hal_uart_state_t; 101 102 /** @} */ 103 104 /** @} */ 105 106 /** @addtogroup HAL_UART_STRUCTURES Structures 107 * @{ 108 */ 109 110 /** @defgroup UART_Configuration UART Configuration 111 * @{ 112 */ 113 114 /** 115 * @brief UART init structure definition 116 */ 117 typedef struct _uart_init { 118 uint32_t baud_rate; /**< This member configures the UART communication baud rate. */ 119 120 uint32_t data_bits; /**< Specifies the number of data bits transmitted or received in a frame. 121 This parameter can be a value of @ref UART_Data_Bits. */ 122 123 uint32_t stop_bits; /**< Specifies the number of stop bits transmitted. 124 This parameter can be a value of @ref UART_Stop_Bits. */ 125 126 uint32_t parity; /**< Specifies the parity mode. 127 This parameter can be a value of @ref UART_Parity. */ 128 129 uint32_t hw_flow_ctrl; /**< Specifies whether the hardware flow control mode is enabled or disabled. 130 This parameter can be a value of @ref UART_Hardware_Flow_Control. */ 131 132 uint32_t rx_timeout_mode; /**< Specifies whether the receive timeout mode is enabled or disabled. 133 When rx_timeout_mode is enabled, character timeout interrupt will disable 134 current receive process after the data in RxFIFO is received, and call 135 hal_uart_rx_cplt_callback(). Note that the rx_timeout_mode only works 136 in interrupt mode. 137 This parameter can be a value of @ref UART_Receiver_TimeOut. */ 138 } uart_init_t; 139 /** @} */ 140 141 /** @defgroup UART_handle UART handle 142 * @{ 143 */ 144 145 /** 146 * @brief UART handle Structure definition 147 */ 148 typedef struct _uart_handle { 149 uart_regs_t *p_instance; /**< UART registers base address */ 150 151 uart_init_t init; /**< UART communication parameters */ 152 153 uint8_t *p_tx_buffer; /**< Pointer to UART Tx transfer Buffer */ 154 155 uint16_t tx_xfer_size; /**< UART Tx Transfer size */ 156 157 __IO uint16_t tx_xfer_count; /**< UART Tx Transfer Counter */ 158 159 uint8_t *p_rx_buffer; /**< Pointer to UART Rx transfer Buffer */ 160 161 uint16_t rx_xfer_size; /**< UART Rx Transfer size */ 162 163 __IO uint16_t rx_xfer_count; /**< UART Rx Transfer Counter */ 164 165 dma_handle_t *p_dmatx; /**< UART Tx DMA Handle parameters */ 166 167 dma_handle_t *p_dmarx; /**< UART Rx DMA Handle parameters */ 168 169 functional_state_t dma_tx_mode; /**< UART Tx DMA mode state */ 170 171 functional_state_t dma_rx_mode; /**< UART Rx DMA mode state */ 172 173 hal_lock_t lock; /**< Locking object */ 174 175 __IO hal_uart_state_t tx_state; /**< UART state information related to Tx operations. 176 This parameter can be a value of @ref hal_uart_state_t */ 177 178 __IO hal_uart_state_t rx_state; /**< UART state information related to Rx operations. 179 This parameter can be a value of @ref hal_uart_state_t */ 180 181 __IO uint32_t error_code; /**< UART Error code */ 182 183 uint32_t retention[8]; /**< UART important register information. */ 184 } uart_handle_t; 185 /** @} */ 186 187 /** @} */ 188 189 /** @addtogroup HAL_UART_CALLBACK_STRUCTURES Callback Structures 190 * @{ 191 */ 192 193 /** @defgroup HAL_UART_Callback Callback 194 * @{ 195 */ 196 197 /** 198 * @brief HAL_UART Callback function definition 199 */ 200 201 typedef struct _hal_uart_callback { 202 void (*uart_msp_init)(uart_handle_t *p_uart); /**< UART init MSP callback */ 203 void (*uart_msp_deinit)(uart_handle_t *p_uart); /**< UART de-init MSP callback */ 204 void (*uart_tx_cplt_callback)(uart_handle_t *p_uart); /**< UART tx transfer completed callback */ 205 void (*uart_rx_cplt_callback)(uart_handle_t *p_uart); /**< UART rx transfer completed callback */ 206 void (*uart_error_callback)(uart_handle_t *p_uart); /**< UART error callback */ 207 void (*uart_abort_cplt_callback)(uart_handle_t *p_uart); /**< UART abort completed callback */ 208 void (*uart_abort_tx_cplt_callback)(uart_handle_t *p_uart); /**< UART abort tansmit complete callback */ 209 void (*uart_abort_rx_cplt_callback)(uart_handle_t *p_uart); /**< UART abort receive complete callback */ 210 } hal_uart_callback_t; 211 212 /** @} */ 213 214 /** @} */ 215 216 /** 217 * @defgroup HAL_UART_MACRO Defines 218 * @{ 219 */ 220 221 /* Exported constants --------------------------------------------------------*/ 222 /** @defgroup UART_Exported_Constants UART Exported Constants 223 * @{ 224 */ 225 226 /** @defgroup UART_Error_Code UART Error Code 227 * @{ 228 */ 229 #define HAL_UART_ERROR_NONE (0x00000000U) /**< No error */ 230 #define HAL_UART_ERROR_PE LL_UART_LSR_PE /**< Parity error */ 231 #define HAL_UART_ERROR_FE LL_UART_LSR_FE /**< frame error */ 232 #define HAL_UART_ERROR_OE LL_UART_LSR_OE /**< Overrun error */ 233 #define HAL_UART_ERROR_BI LL_UART_LSR_BI /**< Break dection error */ 234 #define HAL_UART_ERROR_DMA (0x00000100U) /**< DMA transfer error */ 235 #define HAL_UART_ERROR_BUSY (0x00000200U) /**< Busy Error */ 236 /** @} */ 237 238 /** @defgroup UART_Data_Bits UART Number of Data Bits 239 * @{ 240 */ 241 #define UART_DATABITS_5 LL_UART_DATABITS_5B /**< UART frame with 5 data bits */ 242 #define UART_DATABITS_6 LL_UART_DATABITS_6B /**< UART frame with 6 data bits */ 243 #define UART_DATABITS_7 LL_UART_DATABITS_7B /**< UART frame with 7 data bits */ 244 #define UART_DATABITS_8 LL_UART_DATABITS_8B /**< UART frame with 8 data bits */ 245 /** @} */ 246 247 /** @defgroup UART_Stop_Bits UART Number of Stop Bits 248 * @{ 249 */ 250 #define UART_STOPBITS_1 LL_UART_STOPBITS_1 /**< UART frame with 1 stop bit */ 251 #define UART_STOPBITS_1_5 LL_UART_STOPBITS_1_5 /**< UART frame with 1.5 stop bits */ 252 #define UART_STOPBITS_2 LL_UART_STOPBITS_2 /**< UART frame with 2 stop bits */ 253 /** @} */ 254 255 /** @defgroup UART_Parity UART Parity 256 * @{ 257 */ 258 #define UART_PARITY_NONE LL_UART_PARITY_NONE /**< No parity */ 259 #define UART_PARITY_ODD LL_UART_PARITY_ODD /**< Odd parity */ 260 #define UART_PARITY_EVEN LL_UART_PARITY_EVEN /**< Even parity */ 261 #define UART_PARITY_SP0 LL_UART_PARITY_SP0 /**< Stick Parity 0 */ 262 #define UART_PARITY_SP1 LL_UART_PARITY_SP1 /**< Stick Parity 1 */ 263 /** @} */ 264 265 /** @defgroup UART_Hardware_Flow_Control UART Hardware Flow Control 266 * @{ 267 */ 268 #define UART_HWCONTROL_NONE LL_UART_HWCONTROL_NONE /**< No hardware control */ 269 #define UART_HWCONTROL_RTS_CTS LL_UART_HWCONTROL_RTS_CTS /**< Auto RTS and CTS hardware flow control */ 270 /** @} */ 271 272 /** @defgroup UART_Receiver_TimeOut UART Receiver TimeOut 273 * @{ 274 */ 275 #define UART_RECEIVER_TIMEOUT_DISABLE (0x00000000U) /**< UART receiver timeout disable */ 276 #define UART_RECEIVER_TIMEOUT_ENABLE (0x00000001U) /**< UART receiver timeout enable */ 277 /** @} */ 278 279 /** @defgroup UART_Interrupt_definition UART Interrupt_definition 280 * @{ 281 */ 282 #define UART_IT_MS LL_UART_IER_MS /**< Enable Modem Status Interrupt */ 283 #define UART_IT_RLS LL_UART_IER_RLS /**< Enable Receiver Line Status Interrupt */ 284 #define UART_IT_THRE LL_UART_IER_THRE /**< Enable Transmit Holding Register Empty Interrupt */ 285 #define UART_IT_RDA LL_UART_IER_RDA /**< Enable Received Data Available Interrupt and 286 Character Timeout Interrupt */ 287 /** @} */ 288 289 /** @defgroup UART_Request_Parameters UART Request Parameters 290 * @{ 291 */ 292 #define UART_RXDATA_FLUSH_REQUEST UART_SRR_RFR /**< RX FIFO flush Request */ 293 #define UART_TXDATA_FLUSH_REQUEST UART_SRR_XFR /**< TX FIFO flush Request */ 294 #define UART_TXRXDATA_FLUSH_REQUEST (UART_SRR_XFR | UART_SRR_RFR) /**< TX FIFO and RX FIFO flush Request */ 295 /** @} */ 296 297 /** @defgroup UART_Interrupt_Mask UART Interrupt Flag Mask 298 * @{ 299 */ 300 #define UART_IT_MASK (0x008FU) /**< UART interruptions flags mask */ 301 /** @} */ 302 303 /** @defgroup UART_Line_Error_Mask UART Line Error Flag Mask 304 * @{ 305 */ 306 #define UART_LINE_ERROR_MASK (LL_UART_LSR_PE | LL_UART_LSR_OE | \ 307 LL_UART_LSR_FE | LL_UART_LSR_BI) /**< UART interruptions flags mask */ 308 /** @} */ 309 310 /** @defgroup UART_Retention_Length UART Retention Register Length 311 * @{ 312 */ 313 #define UART_RETENTION_LENGTH ((uint32_t)8) /**< the number of retention registers */ 314 /** @} */ 315 316 /** @defgroup UART_Timeout_definition UART Timeout_definition 317 * @{ 318 */ 319 #define HAL_UART_TIMEOUT_DEFAULT_VALUE ((uint32_t)5000) /**< 5s */ 320 /** @} */ 321 322 /** @} */ 323 324 /* Exported macro ------------------------------------------------------------*/ 325 /** @defgroup UART_Exported_Macros UART Exported Macros 326 * @{ 327 */ 328 329 /** @brief Reset UART handle states. 330 * @param __HANDLE__ UART handle. 331 * @retval None 332 */ 333 #define __HAL_UART_RESET_HANDLE_STATE(__HANDLE__) \ 334 do { \ 335 (__HANDLE__)->g_state = HAL_UART_STATE_RESET; \ 336 (__HANDLE__)->rx_state = HAL_UART_STATE_RESET; \ 337 } while (0U) 338 339 /** @brief Enable the specified UART interrupt. 340 * @param __HANDLE__ Specifies the UART Handle. 341 * @param __INTERRUPT__ Specifies the UART interrupt source to enable. 342 * This parameter can be one of the following values: 343 * @arg @ref UART_IT_RDA 344 * @arg @ref UART_IT_THRE 345 * @arg @ref UART_IT_RLS 346 * @arg @ref UART_IT_MS 347 * @retval None 348 */ 349 #define __HAL_UART_ENABLE_IT(__HANDLE__, __INTERRUPT__) \ 350 do { \ 351 GLOBAL_EXCEPTION_DISABLE(); \ 352 ll_uart_enable_it((__HANDLE__)->p_instance, (__INTERRUPT__)); \ 353 GLOBAL_EXCEPTION_ENABLE(); \ 354 } while (0U) 355 356 /** @brief Disable the specified UART interrupt. 357 * @param __HANDLE__ Specifies the UART Handle. 358 * @param __INTERRUPT__ Specifies the UART interrupt source to disable. 359 * This parameter can be one of the following values: 360 * @arg @ref UART_IT_RDA 361 * @arg @ref UART_IT_THRE 362 * @arg @ref UART_IT_RLS 363 * @arg @ref UART_IT_MS 364 * @retval None 365 */ 366 #define __HAL_UART_DISABLE_IT(__HANDLE__, __INTERRUPT__) \ 367 do { \ 368 GLOBAL_EXCEPTION_DISABLE(); \ 369 ll_uart_disable_it((__HANDLE__)->p_instance, (__INTERRUPT__)); \ 370 GLOBAL_EXCEPTION_ENABLE(); \ 371 } while (0) 372 373 /** @brief Flush the UART FIFO and treat FIFO as empty. 374 * @param __HANDLE__ Specifies the UART Handle. 375 * @param __REQ__ Specifies the request flag to set 376 * This parameter can be one of the following values: 377 * @arg @ref UART_RXDATA_FLUSH_REQUEST RX FIFO flush Request 378 * @arg @ref UART_TXDATA_FLUSH_REQUEST TX FIFO flush Request 379 * @arg @ref UART_TXRXDATA_FLUSH_REQUEST TX FIFO and RX FIFO flush 380 * @retval None 381 */ 382 #define __HAL_UART_SEND_REQ(__HANDLE__, __REQ__) ((__HANDLE__)->p_instance->SRR = (__REQ__)) 383 384 /** @} */ 385 386 /* Private macros ------------------------------------------------------------*/ 387 /** @defgroup UART_Private_Macro UART Private Macros 388 * @{ 389 */ 390 391 /** @brief Check if UART Baudrate is valid. 392 * @param __BAUDRATE__ UART Baudrate. 393 * @retval SET (__BAUDRATE__ is valid) or RESET (__BAUDRATE__ is invalid) 394 */ 395 #define IS_UART_BAUDRATE(__BAUDRATE__) ((__BAUDRATE__) < 921600U) 396 397 /** 398 * @brief Check if UART frame number of stop bits is valid. 399 * @param __STOPBITS__ UART frame number of stop bits. 400 * @retval SET (__STOPBITS__ is valid) or RESET (__STOPBITS__ is invalid) 401 */ 402 #define IS_UART_STOPBITS(__STOPBITS__) (((__STOPBITS__) == UART_STOPBITS_1) || \ 403 ((__STOPBITS__) == UART_STOPBITS_1_5) || \ 404 ((__STOPBITS__) == UART_STOPBITS_2)) 405 406 /** 407 * @brief Check if UART frame number of data bits is valid. 408 * @param __DATABITS__ UART frame number of data bits. 409 * @retval SET (__DATABITS__ is valid) or RESET (__DATABITS__ is invalid) 410 */ 411 #define IS_UART_DATABITS(__DATABITS__) (((__DATABITS__) == UART_DATABITS_5) || \ 412 ((__DATABITS__) == UART_DATABITS_6) || \ 413 ((__DATABITS__) == UART_DATABITS_7) || \ 414 ((__DATABITS__) == UART_DATABITS_8)) 415 416 /** 417 * @brief Check if UART frame parity is valid. 418 * @param __PARITY__ UART frame parity. 419 * @retval SET (__PARITY__ is valid) or RESET (__PARITY__ is invalid) 420 */ 421 #define IS_UART_PARITY(__PARITY__) (((__PARITY__) == UART_PARITY_NONE) || \ 422 ((__PARITY__) == UART_PARITY_EVEN) || \ 423 ((__PARITY__) == UART_PARITY_ODD) || \ 424 ((__PARITY__) == UART_PARITY_SP0) || \ 425 ((__PARITY__) == UART_PARITY_SP1)) 426 427 /** 428 * @brief Check if UART hardware flow control is valid. 429 * @param __CONTROL__ UART hardware flow control. 430 * @retval SET (__CONTROL__ is valid) or RESET (__CONTROL__ is invalid) 431 */ 432 #define IS_UART_HARDWARE_FLOW_CONTROL(__CONTROL__) (((__CONTROL__) == UART_HWCONTROL_NONE) || \ 433 ((__CONTROL__) == UART_HWCONTROL_RTS_CTS)) 434 /** @} */ 435 436 /** 437 * @brief Default configuartion for initializing structure 438 */ 439 #define UART_DEFAULT_CONFIG \ 440 { \ 441 .baud_rate = 9600, \ 442 .data_bits = UART_DATABITS_8, \ 443 .stop_bits = UART_STOPBITS_1, \ 444 .parity = UART_PARITY_NONE, \ 445 .hw_flow_ctrl = UART_HWCONTROL_NONE, \ 446 .rx_timeout_mode = UART_RECEIVER_TIMEOUT_DISABLE, \ 447 } 448 449 /** @} */ 450 451 /* Exported functions --------------------------------------------------------*/ 452 /** @addtogroup HAL_UART_DRIVER_FUNCTIONS Functions 453 * @{ 454 */ 455 456 /** @addtogroup UART_Exported_Functions_Group1 Initialization and de-initialization functions 457 * @brief Initialization and de-initialization functions 458 * 459 * @verbatim 460 =============================================================================== 461 ##### Initialization and de-initialization functions ##### 462 =============================================================================== 463 [..] 464 This subsection provides a set of functions allowing to initialize the UARTx. 465 (+) For the asynchronous mode the parameters below can be configured: 466 (++) Baud Rate 467 (++) Data Bit 468 (++) Stop Bit 469 (++) Parity 470 (++) Hardware flow control 471 [..] 472 The hal_uart_init() API follow the UART asynchronous configuration procedures. 473 474 @endverbatim 475 * @{ 476 */ 477 478 /** 479 **************************************************************************************** 480 * @brief Initialize the UART according to the specified 481 * parameters in the uart_init_t and initialize the associated handle. 482 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 483 * information for the specified UART module. 484 * @retval ::HAL_OK: Operation is OK. 485 * @retval ::HAL_ERROR: Parameter error or operation not supported. 486 * @retval ::HAL_BUSY: Driver is busy. 487 * @retval ::HAL_TIMEOUT: Timeout occurred. 488 **************************************************************************************** 489 */ 490 hal_status_t hal_uart_init(uart_handle_t *p_uart); 491 492 /** 493 **************************************************************************************** 494 * @brief De-initialize the UART peripheral. 495 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 496 * information for the specified UART module. 497 * @retval ::HAL_OK: Operation is OK. 498 * @retval ::HAL_ERROR: Parameter error or operation not supported. 499 * @retval ::HAL_BUSY: Driver is busy. 500 * @retval ::HAL_TIMEOUT: Timeout occurred. 501 **************************************************************************************** 502 */ 503 hal_status_t hal_uart_deinit (uart_handle_t *p_uart); 504 505 /** 506 **************************************************************************************** 507 * @brief Initialize the UART MSP. 508 * @note This function should not be modified. When the callback is needed, 509 the hal_uart_msp_init can be implemented in the user file. 510 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 511 * information for the specified UART module. 512 **************************************************************************************** 513 */ 514 void hal_uart_msp_init(uart_handle_t *p_uart); 515 516 /** 517 **************************************************************************************** 518 * @brief De-initialize the UART MSP. 519 * @note This function should not be modified. When the callback is needed, 520 the hal_uart_msp_deinit can be implemented in the user file. 521 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 522 * information for the specified UART module. 523 **************************************************************************************** 524 */ 525 void hal_uart_msp_deinit(uart_handle_t *p_uart); 526 527 /** @} */ 528 529 /** @addtogroup UART_Exported_Functions_Group2 IO operation functions 530 * @brief UART Transmit/Receive functions 531 * 532 @verbatim 533 =============================================================================== 534 ##### IO operation functions ##### 535 =============================================================================== 536 This subsection provides a set of functions allowing to manage the UART asynchronous 537 and Half duplex data transfers. 538 539 (#) There are two mode of transfer: 540 (++) Blocking mode: The communication is performed in polling mode. 541 The HAL status of all data processing is returned by the same function 542 after finishing transfer. 543 (++) Non-Blocking mode: The communication is performed using Interrupts 544 or DMA, These API's return the HAL status. 545 The end of the data processing will be indicated through the 546 dedicated UART IRQ when using Interrupt mode or the DMA IRQ when 547 using DMA mode. 548 The hal_uart_tx_cplt_callback(), hal_uart_rx_cplt_callback() user callbacks 549 will be executed respectively at the end of the transmit or Receive process 550 The hal_uart_error_callback() user callback will be executed when a 551 communication error is detected 552 553 (#) Blocking mode API's are : 554 (++) hal_uart_transmit() 555 (++) hal_uart_receive() 556 557 (#) Non-Blocking mode API's with Interrupt are : 558 (++) hal_uart_transmit_it() 559 (++) hal_uart_receive_it() 560 (++) hal_uart_irq_handler() 561 562 (#) Non-Blocking mode API's with DMA are : 563 (++) hal_uart_transmit_dma() 564 (++) hal_uart_receive_dma() 565 (++) hal_uart_dma_pause() 566 (++) hal_uart_dma_resume() 567 (++) hal_uart_dma_stop() 568 569 (#) A set of Transfer Complete Callbacks are provided in Non_Blocking mode: 570 (++) hal_uart_tx_cplt_callback() 571 (++) hal_uart_rx_cplt_callback() 572 (++) hal_uart_error_callback() 573 574 (#) Non-Blocking mode transfers could be aborted using Abort API's : 575 (++) hal_uart_abort() 576 (++) hal_uart_abort_transmit() 577 (++) hal_uart_abort_receive() 578 (++) hal_uart_abort_it() 579 (++) hal_uart_abort_transmit_it() 580 (++) hal_uart_abort_receive_it() 581 582 (#) For Abort services based on interrupts (hal_uart_abort_xxx_it), a set 583 of Abort Complete Callbacks are provided: 584 (++) hal_uart_abort_cplt_callback() 585 (++) hal_uart_abort_tx_cplt_callback() 586 (++) hal_uart_abort_rx_cplt_callback() 587 588 (#) In Non-Blocking mode transfers, possible errors are split into 2 categories. 589 Errors are handled as follows : 590 (++) Error is considered as Recoverable and non blocking. Transfer could go till end, but error severity is to 591 be evaluated by user : this concerns Frame Error, Parity Error or Noise Error in Interrupt mode reception. 592 Received character is then retrieved and stored in Rx buffer, Error code is set to allow user to identify 593 error type, and hal_uart_error_callback() user callback is executed. Transfer is kept ongoing on UART side. 594 If user wants to abort it, Abort services should be called by user. 595 (++) Error is considered as Blocking : Transfer could not be completed properly and is aborted. 596 This concerns Overrun Error In Interrupt mode reception and all errors in DMA mode. 597 Error code is set to allow user to identify error type, and hal_uart_error_callback() user 598 callback is executed. 599 600 -@- In the Half duplex communication, it is forbidden to run the transmit 601 and receive process in parallel, the UART state hal_uart_state_busy_tx_rx can't be useful. 602 603 @endverbatim 604 * @{ 605 */ 606 607 /** 608 **************************************************************************************** 609 * @brief Send an amount of data in blocking mode. 610 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 611 * information for the specified UART module. 612 * @param[in] p_data: Pointer to data buffer. 613 * @param[in] size: Amount of data to be sent. 614 * @param[in] timeout: Timeout duration. 615 * @retval ::HAL_OK: Operation is OK. 616 * @retval ::HAL_ERROR: Parameter error or operation not supported. 617 * @retval ::HAL_BUSY: Driver is busy. 618 * @retval ::HAL_TIMEOUT: Timeout occurred. 619 **************************************************************************************** 620 */ 621 hal_status_t hal_uart_transmit(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size, uint32_t timeout); 622 623 /** 624 **************************************************************************************** 625 * @brief Receive an amount of data in blocking mode. 626 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 627 * information for the specified UART module. 628 * @param[out] p_data: Pointer to data buffer. 629 * @param[in] size: Amount of data to be received. 630 * @param[in] timeout: Timeout duration. 631 * @retval ::HAL_OK: Operation is OK. 632 * @retval ::HAL_ERROR: Parameter error or operation not supported. 633 * @retval ::HAL_BUSY: Driver is busy. 634 * @retval ::HAL_TIMEOUT: Timeout occurred. 635 **************************************************************************************** 636 */ 637 hal_status_t hal_uart_receive(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size, uint32_t timeout); 638 639 /** 640 **************************************************************************************** 641 * @brief Send an amount of data in interrupt mode. 642 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 643 * information for the specified UART module. 644 * @param[in] p_data: Pointer to data buffer. 645 * @param[in] size: Amount of data to be sent. 646 * @retval ::HAL_OK: Operation is OK. 647 * @retval ::HAL_ERROR: Parameter error or operation not supported. 648 * @retval ::HAL_BUSY: Driver is busy. 649 * @retval ::HAL_TIMEOUT: Timeout occurred. 650 **************************************************************************************** 651 */ 652 hal_status_t hal_uart_transmit_it(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size); 653 654 /** 655 **************************************************************************************** 656 * @brief Receive an amount of data in interrupt mode. 657 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 658 * information for the specified UART module. 659 * @param[out] p_data: Pointer to data buffer. 660 * @param[in] size: Amount of data to be received. 661 * @retval ::HAL_OK: Operation is OK. 662 * @retval ::HAL_ERROR: Parameter error or operation not supported. 663 * @retval ::HAL_BUSY: Driver is busy. 664 * @retval ::HAL_TIMEOUT: Timeout occurred. 665 **************************************************************************************** 666 */ 667 hal_status_t hal_uart_receive_it(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size); 668 669 /** 670 **************************************************************************************** 671 * @brief Send an amount of data in DMA mode. 672 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 673 * information for the specified UART module. 674 * @param[in] p_data: Pointer to data buffer. 675 * @param[in] size: Amount of data to be sent, ranging between 0 ~ 4095. 676 * @note This function starts a DMA transfer in interrupt mode meaning that 677 * DMA half transfer complete, DMA transfer complete and DMA transfer 678 * error interrupts are enabled 679 * @retval ::HAL_OK: Operation is OK. 680 * @retval ::HAL_ERROR: Parameter error or operation not supported. 681 * @retval ::HAL_BUSY: Driver is busy. 682 * @retval ::HAL_TIMEOUT: Timeout occurred. 683 **************************************************************************************** 684 */ 685 hal_status_t hal_uart_transmit_dma(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size); 686 687 /** 688 **************************************************************************************** 689 * @brief Receive an amount of data in DMA mode. 690 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 691 * information for the specified UART module. 692 * @param[out] p_data: Pointer to data buffer. 693 * @param[in] size: Amount of data to be received, ranging between 0 and 4095. 694 * @note When the UART parity is enabled (PCE = 1), the received data contain 695 * the parity bit (MSB position). 696 * @note This function starts a DMA transfer in interrupt mode meaning that 697 * DMA half transfer complete, DMA transfer complete and DMA transfer 698 * error interrupts are enabled 699 * @retval ::HAL_OK: Operation is OK. 700 * @retval ::HAL_ERROR: Parameter error or operation not supported. 701 * @retval ::HAL_BUSY: Driver is busy. 702 * @retval ::HAL_TIMEOUT: Timeout occurred. 703 **************************************************************************************** 704 */ 705 hal_status_t hal_uart_receive_dma(uart_handle_t *p_uart, uint8_t *p_data, uint16_t size); 706 707 /** 708 **************************************************************************************** 709 * @brief Pause the DMA Transfer. 710 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 711 * information for the specified UART module. 712 * @retval ::HAL_OK: Operation is OK. 713 * @retval ::HAL_ERROR: Parameter error or operation not supported. 714 * @retval ::HAL_BUSY: Driver is busy. 715 * @retval ::HAL_TIMEOUT: Timeout occurred. 716 **************************************************************************************** 717 */ 718 hal_status_t hal_uart_dma_pause(uart_handle_t *p_uart); 719 720 /** 721 **************************************************************************************** 722 * @brief Resume the DMA Transfer. 723 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 724 * information for the specified UART module. 725 * @retval ::HAL_OK: Operation is OK. 726 * @retval ::HAL_ERROR: Parameter error or operation not supported. 727 * @retval ::HAL_BUSY: Driver is busy. 728 * @retval ::HAL_TIMEOUT: Timeout occurred. 729 **************************************************************************************** 730 */ 731 hal_status_t hal_uart_dma_resume(uart_handle_t *p_uart); 732 733 /** 734 **************************************************************************************** 735 * @brief Stop the DMA Transfer. 736 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 737 * information for the specified UART module. 738 * @retval ::HAL_OK: Operation is OK. 739 * @retval ::HAL_ERROR: Parameter error or operation not supported. 740 * @retval ::HAL_BUSY: Driver is busy. 741 * @retval ::HAL_TIMEOUT: Timeout occurred. 742 **************************************************************************************** 743 */ 744 hal_status_t hal_uart_dma_stop(uart_handle_t *p_uart); 745 746 /** 747 **************************************************************************************** 748 * @brief Abort ongoing transfers (blocking mode). 749 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 750 * information for the specified UART module. 751 * @note This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. 752 * This procedure performs following operations : 753 * - Disable UART Interrupts (Tx and Rx) 754 * - Disable the DMA transfer in the peripheral register (if enabled) 755 * - Abort DMA transfer by calling hal_dma_abort (in case of transfer in DMA mode) 756 * - Set handle State to READY 757 * @note This procedure is executed in blocking mode: when exiting function, Abort is considered as completed. 758 * @retval ::HAL_OK: Operation is OK. 759 * @retval ::HAL_ERROR: Parameter error or operation not supported. 760 * @retval ::HAL_BUSY: Driver is busy. 761 * @retval ::HAL_TIMEOUT: Timeout occurred. 762 **************************************************************************************** 763 */ 764 hal_status_t hal_uart_abort(uart_handle_t *p_uart); 765 766 /** 767 **************************************************************************************** 768 * @brief Abort ongoing Transmit transfer (blocking mode). 769 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 770 * information for the specified UART module. 771 * @note This procedure could be used for aborting any ongoing Tx transfer started in Interrupt or DMA mode. 772 * This procedure performs following operations : 773 * - Disable UART Interrupts (Tx) 774 * - Disable the DMA transfer in the peripheral register (if enabled) 775 * - Abort DMA transfer by calling hal_dma_abort (in case of transfer in DMA mode) 776 * - Set handle State to READY 777 * @note This procedure is executed in blocking mode: when exiting function, Abort is considered as completed. 778 * @retval ::HAL_OK: Operation is OK. 779 * @retval ::HAL_ERROR: Parameter error or operation not supported. 780 * @retval ::HAL_BUSY: Driver is busy. 781 * @retval ::HAL_TIMEOUT: Timeout occurred. 782 **************************************************************************************** 783 */ 784 hal_status_t hal_uart_abort_transmit(uart_handle_t *p_uart); 785 786 /** 787 **************************************************************************************** 788 * @brief Abort ongoing Receive transfer (blocking mode). 789 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 790 * information for the specified UART module. 791 * @note This procedure could be used for aborting any ongoing Rx transfer started in Interrupt or DMA mode. 792 * This procedure performs following operations : 793 * - Disable UART Interrupts (Rx) 794 * - Disable the DMA transfer in the peripheral register (if enabled) 795 * - Abort DMA transfer by calling hal_dma_abort (in case of transfer in DMA mode) 796 * - Set handle State to READY 797 * @note This procedure is executed in blocking mode: when exiting function, Abort is considered as completed. 798 * @retval ::HAL_OK: Operation is OK. 799 * @retval ::HAL_ERROR: Parameter error or operation not supported. 800 * @retval ::HAL_BUSY: Driver is busy. 801 * @retval ::HAL_TIMEOUT: Timeout occurred. 802 **************************************************************************************** 803 */ 804 hal_status_t hal_uart_abort_receive(uart_handle_t *p_uart); 805 806 /** 807 **************************************************************************************** 808 * @brief Abort ongoing transfers (Interrupt mode). 809 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 810 * information for the specified UART module. 811 * @note This procedure could be used for aborting any ongoing transfer started in Interrupt or DMA mode. 812 * This procedure performs following operations : 813 * - Disable UART Interrupts (Tx and Rx) 814 * - Disable the DMA transfer in the peripheral register (if enabled) 815 * - Abort DMA transfer by calling hal_dma_abort_it (in case of transfer in DMA mode) 816 * - Set handle State to READY 817 * - At abort completion, call user abort complete callback 818 * @note This procedure is executed in Interrupt mode, meaning that abort procedure could be 819 * considered as completed only when user abort complete callback is executed (not when exiting function). 820 * @retval ::HAL_OK: Operation is OK. 821 * @retval ::HAL_ERROR: Parameter error or operation not supported. 822 * @retval ::HAL_BUSY: Driver is busy. 823 * @retval ::HAL_TIMEOUT: Timeout occurred. 824 **************************************************************************************** 825 */ 826 hal_status_t hal_uart_abort_it(uart_handle_t *p_uart); 827 828 /** 829 **************************************************************************************** 830 * @brief Abort ongoing Transmit transfer (Interrupt mode). 831 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 832 * information for the specified UART module. 833 * @note This procedure could be used for aborting any ongoing Tx transfer started in Interrupt or DMA mode. 834 * This procedure performs following operations : 835 * - Disable UART Interrupts (Tx) 836 * - Disable the DMA transfer in the peripheral register (if enabled) 837 * - Abort DMA transfer by calling hal_dma_abort_it (in case of transfer in DMA mode) 838 * - Set handle State to READY 839 * - At abort completion, call user abort complete callback 840 * @note This procedure is executed in Interrupt mode, meaning that abort procedure could be 841 * considered as completed only when user abort complete callback is executed (not when exiting function). 842 * @retval ::HAL_OK: Operation is OK. 843 * @retval ::HAL_ERROR: Parameter error or operation not supported. 844 * @retval ::HAL_BUSY: Driver is busy. 845 * @retval ::HAL_TIMEOUT: Timeout occurred. 846 **************************************************************************************** 847 */ 848 hal_status_t hal_uart_abort_transmit_it(uart_handle_t *p_uart); 849 850 /** 851 **************************************************************************************** 852 * @brief Abort ongoing Receive transfer (Interrupt mode). 853 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 854 * information for the specified UART module. 855 * @note This procedure could be used for aborting any ongoing Rx transfer started in Interrupt or DMA mode. 856 * This procedure performs following operations : 857 * - Disable UART Interrupts (Rx) 858 * - Disable the DMA transfer in the peripheral register (if enabled) 859 * - Abort DMA transfer by calling hal_dma_abort_it (in case of transfer in DMA mode) 860 * - Set handle State to READY 861 * - At abort completion, call user abort complete callback 862 * @note This procedure is executed in Interrupt mode, meaning that abort procedure could be 863 * considered as completed only when user abort complete callback is executed (not when exiting function). 864 * @retval ::HAL_OK: Operation is OK. 865 * @retval ::HAL_ERROR: Parameter error or operation not supported. 866 * @retval ::HAL_BUSY: Driver is busy. 867 * @retval ::HAL_TIMEOUT: Timeout occurred. 868 **************************************************************************************** 869 */ 870 hal_status_t hal_uart_abort_receive_it(uart_handle_t *p_uart); 871 872 /** @} */ 873 874 /** @addtogroup UART_IRQ_Handler_and_Callbacks IRQ Handler and Callbacks 875 * @brief IRQ Handler and Callbacks functions 876 * @{ 877 */ 878 879 /** 880 **************************************************************************************** 881 * @brief Handle UART interrupt request. 882 * @param[in] p_uart: Pointer to a UART handle which contains the configuration information 883 * for the specified UART module. 884 **************************************************************************************** 885 */ 886 void hal_uart_irq_handler(uart_handle_t *p_uart); 887 888 /** 889 **************************************************************************************** 890 * @brief Tx Transfer completed callback. 891 * @note This function should not be modified. When the callback is needed, 892 * the hal_uart_tx_cplt_callback can be implemented in the user file. 893 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 894 * information for the specified UART module. 895 **************************************************************************************** 896 */ 897 void hal_uart_tx_cplt_callback(uart_handle_t *p_uart); 898 899 /** 900 **************************************************************************************** 901 * @brief Rx Transfer completed callback. 902 * @note This function should not be modified. When the callback is needed, 903 * the hal_uart_rx_cplt_callback can be implemented in the user file. 904 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 905 * information for the specified UART module. 906 **************************************************************************************** 907 */ 908 void hal_uart_rx_cplt_callback(uart_handle_t *p_uart); 909 910 /** 911 **************************************************************************************** 912 * @brief UART error callback. 913 * @note This function should not be modified. When the callback is needed, 914 * the hal_uart_error_callback can be implemented in the user file. 915 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 916 * information for the specified UART module. 917 **************************************************************************************** 918 */ 919 void hal_uart_error_callback(uart_handle_t *p_uart); 920 921 /** 922 **************************************************************************************** 923 * @brief UART Abort Complete callback. 924 * @note This function should not be modified. When the callback is needed, 925 * the hal_uart_abort_cplt_callback can be implemented in the user file. 926 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 927 * information for the specified UART module. 928 **************************************************************************************** 929 */ 930 void hal_uart_abort_cplt_callback (uart_handle_t *p_uart); 931 932 /** 933 **************************************************************************************** 934 * @brief UART Abort Tansmit Complete callback. 935 * @note This function should not be modified. When the callback is needed, 936 * the hal_uart_abort_tx_cplt_callback can be implemented in the user file. 937 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 938 * information for the specified UART module. 939 **************************************************************************************** 940 */ 941 void hal_uart_abort_tx_cplt_callback (uart_handle_t *p_uart); 942 943 /** 944 **************************************************************************************** 945 * @brief UART Abort Receive Complete callback. 946 * @note This function should not be modified. When the callback is needed, 947 * the hal_uart_abort_rx_cplt_callback can be implemented in the user file. 948 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 949 * information for the specified UART module. 950 **************************************************************************************** 951 */ 952 void hal_uart_abort_rx_cplt_callback (uart_handle_t *p_uart); 953 954 /** @} */ 955 956 957 /** @addtogroup UART_Exported_Functions_Group3 Peripheral Control and State functions 958 * @brief UART Peripheral State functions 959 * 960 @verbatim 961 ============================================================================== 962 ##### Peripheral Control and State functions ##### 963 ============================================================================== 964 [..] 965 This subsection provides functions allowing to : 966 (+) Return the UART handle state. 967 (+) Return the UART handle error code 968 969 @endverbatim 970 * @{ 971 */ 972 973 /** 974 **************************************************************************************** 975 * @brief Return the UART handle state. 976 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 977 * information for the specified UART module. 978 * @retval ::HAL_UART_STATE_RESET: Peripheral is not initialized. 979 * @retval ::HAL_UART_STATE_READY: Peripheral initialized and ready for use. 980 * @retval ::HAL_UART_STATE_BUSY: An internal process is ongoing. 981 * @retval ::HAL_UART_STATE_BUSY_TX: Data Transmission process is ongoing. 982 * @retval ::HAL_UART_STATE_BUSY_RX: Data Reception process is ongoing. 983 * @retval ::HAL_UART_STATE_TIMEOUT: Timeout state. 984 * @retval ::HAL_UART_STATE_ERROR: Error. 985 **************************************************************************************** 986 */ 987 hal_uart_state_t hal_uart_get_state(uart_handle_t *p_uart); 988 989 /** 990 **************************************************************************************** 991 * @brief Return the UART handle error code. 992 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 993 * information for the specified UART module. 994 * @return UART Error Code 995 **************************************************************************************** 996 */ 997 uint32_t hal_uart_get_error(uart_handle_t *p_uart); 998 999 /** 1000 **************************************************************************************** 1001 * @brief Suspend some registers related to UART configuration before sleep. 1002 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 1003 * information for the specified UART module. 1004 * @retval ::HAL_OK: Operation is OK. 1005 * @retval ::HAL_ERROR: Parameter error or operation not supported. 1006 * @retval ::HAL_BUSY: Driver is busy. 1007 * @retval ::HAL_TIMEOUT: Timeout occurred. 1008 **************************************************************************************** 1009 */ 1010 hal_status_t hal_uart_suspend_reg(uart_handle_t *p_uart); 1011 1012 /** 1013 **************************************************************************************** 1014 * @brief Restore some registers related to UART configuration after sleep. 1015 * This function must be used in conjunction with the hal_uart_suspend_reg(). 1016 * @param[in] p_uart: Pointer to a UART handle which contains the configuration 1017 * information for the specified UART module. 1018 * @retval ::HAL_OK: Operation is OK. 1019 * @retval ::HAL_ERROR: Parameter error or operation not supported. 1020 * @retval ::HAL_BUSY: Driver is busy. 1021 * @retval ::HAL_TIMEOUT: Timeout occurred. 1022 **************************************************************************************** 1023 */ 1024 hal_status_t hal_uart_resume_reg(uart_handle_t *p_uart); 1025 1026 1027 /** @} */ 1028 1029 /** @} */ 1030 1031 #ifdef __cplusplus 1032 } 1033 #endif 1034 1035 #endif /* __GR55xx_HAL_UART_H__ */ 1036 1037 /** @} */ 1038 1039 /** @} */ 1040 1041 /** @} */ 1042