Breaking changes in concepts

STM32Cube HAL2 introduces several breaking changes in the concepts and principles underlying the library. Understanding these changes is essential for a successful migration of the application to the new version.

The key improvements include:

• Separation of initialization and configuration APIs, with optimized handle management.

• Division of processes, such as clock management for all sources and IRQ handling for all modes.

• Addition of unitary configuration methods to provide greater granularity in dynamic peripheral setup alongside global configuration.

• HAL2 services now exclusively call LL functions instead of direct register access, improving driver maintenance and upgrades (Knowing that on HAL1 the LL was introduced after the HAL).

• Enhanced lock, state, and error management within drivers to reinforce thread safety and prevent race conditions in certain scenarios.

• Enhanced control services to improve portability, particularly for clock management, providing unitary APIs per peripheral clocks, and for interrupt filtering, allowing dynamic disabling of specific process events.

• Implementation of new coding rules and naming conventions.

Note

Throughout this document, stm32tnxx denotes a generic STM32 device family reference. Here, tn stands for the specific series name. For example, u5 in stm32u5xx refers to the STM32U5 series.

The breaking changes have been organized into the following categories, each addressing specific improvements and modifications in the HAL2 migration:

• Optimized initialization and configuration APIs
• Unitary configuration methods
• Specialized clock and IRQ management in HAL2
• HAL implementation built upon LL services
• Improved driver mechanisms
• Enhanced control services
• New coding rules
• Optimized input checks
• HAL refactoring
• Enhanced asserts
• Flash driver refactoring
• RTOS-aware HAL
• Misc. updates