HAL UART migration: List of applicable concepts

This section provides information about the HAL UART applicable architecture concepts.

Concepts for UART

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: HAL_UART_Init(): Initializes the handle and links it to a UART instance. HAL_UART_SetConfig(): Sets the basic configuration to enable the use of the UART instance.
Removal and conversion of init structure to configuration structure	The init structure UART_InitTypeDef has been removed from the handle .
Renaming of the handle structure	The handle structure has been renamed to hal_uart_handle_t.
Renaming unitary init structures	The structure UART_InitTypeDef is no longer available and has been replaced by hal_uart_config_t.
Remove MspInit and MspDeInit callbacks	hal_uart_MspInit() and hal_uart_MspDeInit() are no longer available and have been replaced by a user-defined sequence to initialize and configure the UART.
Unitary configuration APIs	New APIs are available to get and set UART features
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	The __HAL_LINKDMA macro is no longer provided and new functions HAL_UART_SetTxDMA() and HAL_UART_SetRxDMA() are provided to link a UART HAL handle to a DMA HAL handle.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_UART_SetUserData() and HAL_UART_GetUserData().
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each UART event. These functions are used to register callback functions for different UART events.
HAL implementation with LL inline functions	HAL UART APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL UART define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL UART driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The UART is now managed by three state machines: Global state machine Transmission state machine Receiver state machine
Revised and optimized HAL API status returns	The HAL UART functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	Redesign the error handling mechanisms within the HAL to improve the detection, reporting, and handling of errors. This rework aims to provide more detailed and consistent error information such as HAL_UART_ERROR_PE and HAL_UART_ERROR_ORE.
New APIs for filtering optional asynchronous process interrupts	New HAL UART Transmit APIs with interrupt filtering capability are provided, such as HAL_UART_Transmit_IT_Opt() and HAL_UART_Transmit_DMA_Opt().
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL UART driver have been removed and replaced by _t.
Replaced multi-line macros with inline functions	For the HAL UART driver, large macros have been replaced by inline functions to maintain code consistency, improve readability, and benefit from compiler optimization. Inline functions also offer better support for debugging and strict type management, reducing the risk of errors.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL UART header file remains and all macros, define statements, and functions from hal_uart_ex.h have been moved to hal_uart.h.
Provide RTOS-compatible acquire/release bus services for communication peripheral drivers.	New functions, HAL_UART_AcquireBus() and HAL_UART_ReleaseBus(), are provided to allow the acquisition and release of a HAL UART handle, ensuring protection throughout a complete sequence.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	HAL UART Driver provides a new API to retrieve clock frequency: HAL_UART_GetClockFreq().
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including UART instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL UART functions start with HAL_UART.

Other HAL UART changes

Concept	Consideration
Introduce Reception until timeout API	Provide an API to manage reception flow until the expected data length is received or a reception timeout RTO occurs.
Introduce Reception until character match API	Provide an API to manage reception flow until the expected data length is received or a specific character value is detected.
Add DMA Pause/Resume API per process Rx/Tx	Provide new services to Pause/Resume/Stop only the Tx or Rx process, even if both are active simultaneously.
Remove HAL_UART_DMASTOP()	This function’s functionality is already covered by HAL_UART_Abort_IT().
Rework Advanced feature APIs	Advanced feature APIs are no more handled by the init function and structure. Instead dedicated advanced features APIs are provided individually for each feature.
Merge RxComplete callback with RxEvent callback	The RxComplete and RxEvent callbacks are now unified: HAL_UART_RxCpltCallback(hal_uart_handle_t *huart, uint32_t size_byte, hal_uart_rx_event_types_t rx_event)