HAL and LL layered drivers

The HAL (Hardware Abstraction Layer) drivers are built on top of the Low-Layer (LL) drivers when available and applicable for the given peripherals. For example, the HAL TIM driver is built on top of the LL TIM driver. However, due to the complexity of certain peripherals and protocols, such as FDCAN, there are no corresponding Low Layer drivers. In these cases, only a HAL driver is provided, such as the HAL FDCAN driver.

Inclusion model

HAL Inter-series APIs Compatibility Rules

The compatibility of HAL APIs is crucial to ensure the portability of the HAL across different STM32 series. The API compatibility applies to all “C” elements in the stm32tnxx_hal_ppp.h header files, including defines, enumerations, structures, and functions.

Configuration Structures Compatibility

By configuration structures, we mean global configuration structures, sub-block or sub-instance configuration structures, and feature configuration structures.

The following rules are applied:

  • API Break Authorization: API breaks are only allowed for configurations that are called during the peripheral initialization phase. This does not apply to APIs that can be called dynamically by the user to change the PPP behavior at runtime.

  • Structure Content: It can have different configuration structure contents depending on the hardware variations. However, if a given structure field corresponds to the same configuration scope, its field name remains the same. The structure name also remains the same if applicable to the given series, or it is completely removed if not applicable.

  • Field Names: From one product to another:

    • Configuration structure names remain the same when the structure is applicable to the given series.

    • Field names remain the same when these fields correspond to features available in the given series.

    • Fields are removed if the corresponding feature is not available in the given series.

    • New fields are added when new features are available in the given series.

  • Field Values: The possible values for fields (enumerations or defines) have the same naming when applicable to the given series or are removed when not applicable. It is also possible to add additional possible values when they are new for the given series.

  • SetItem/GetItem APIs: These APIs follow the corresponding configuration elements (naming and possible values).

HAL_PPP_SetFeature APIs Compatibility

  • Naming: If it concerns the same feature scope, the API naming remains the same.

  • Parameters: It is permissible to have a different number of parameters if some are not applicable to the given series. For parameters that are applicable, the parameter naming remains the same. The same rule about the parameter’s possible values as for configuration structures applies here.

HAL System APIs

  • Different APIs: All the system/SoC-related IPs can have different APIs if the features are different (e.g., Cortex, PWR, SYSCFG, RCC).

  • Same Features: If the feature or a parameter is the same, the same naming is kept. The number and list of parameters can change if the SoC features differ between series. If the features are the same, the API naming remains the same.

Example 

HAL_RCC_LSI_Enable(void);             /* on Series X */
HAL_RCC_LSI_Enable(uint32_t divider); /* on Series Y */

In the above, both APIs have the same scope (enabling the LSI), but there are differences based on the series:

  • On series X, there is no divider, so no parameter is needed.

  • On series Y, the LSI requires a divider, so a parameter is included.

Processing APIs

The processing and control APIs (APIs that can be called dynamically by the application) remain unchanged.