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 apply:

  • 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 behaviour at runtime.

  • Structure Content: It is permissible to have different configuration structure content when the hardware differs. However, if a given structure field addresses the same configuration scope, the field naming must remain the same. The structure naming must also remain the same if applicable to the given series or be completely removed if not applicable.

  • Field Names: From one product to another, we must:

    • Keep the same configuration structure names (when the structure is applicable to the given series).

    • Maintain the same field names when these fields correspond to features available in the given series.

    • Remove the corresponding field when the feature is not available in the given series.

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

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

  • SetItem/GetItem APIs: These APIs must 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 must remain the same.

  • Parameters: It is permissible to have different parameter numbers if some are not applicable to the given series. For parameters that are still applicable, the parameter naming must remain the same. The same rule about the parameter’s possible values as the configuration structure 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, keep the same naming. Parameters’ number and list can change if the given series SoC features are different. If the features are the same, the API naming must remain 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 APIs and control APIs (APIs that can be called dynamically by the application) must not change. No API break is allowed in this case.