Improve STM32 LL HAL usage

[gmarull]

Introduction

This RFC aims to improve the usage of STM32 LL HAL in both Zephyr drivers and for out-of-tree users.

Problem description

STM32 drivers using LL API need to include stm32xxx_ll_yyy.h headers in order to make use of the API. Nowadays this is done via the soc.h file, e.g. https://github.com/zephyrproject-rtos/zephyr/blob/master/soc/arm/st_stm32/stm32f4/soc.h. Inclusion of LL headers is dependent on active configuration, e.g.

...
#ifdef CONFIG_ADC_STM32
#include <stm32f4xx_ll_adc.h>
#endif

#ifdef CONFIG_DMA_STM32
#include <stm32f4xx_ll_dma.h>
#endif
...

This approach has some problems:

1. Every time a new driver or SoC is added soc.h needs to be adjusted accordingly (SoC headers depend on driver configuration)
2. When a driver includes soc.h, it will include all LL headers that are active. For example, if ADC and DMA are active, both will be included. STM32 LL API is mainly built upon static inline functions, so when we include all these headers we are pasting all of them in a driver that will, in most cases, just need one of the LL headers.
3. Out of tree applications using LL API can't rely on changing soc.h, so in case the application is designed for multiple series, it needs to include LL API based on the active SoC, e.g.

#ifdef CONFIG_SOC_SERIES_STM32F3XX
#include <stm32f3xx_ll_dma.h>
#elif CONFIG_SOC_SERIES_STM32F4XX
#include <stm32f4xx_ll_dma.h>
#endif

Note that the non-LL HAL is not affected, as it already provides a header gathering all APIs. It can remain part of soc.h.

Proposed change

My proposal is to provide SoC generic LL HAL headers, for example:

/* stm32_ll_tim.h */
#include <autoconf.h>

#ifdef CONFIG_SOC_SERIES_STM32F0XX
#include <stm32f0xx_ll_tim.h>
...
#elif CONFIG_SOC_SERIES_STM32F4XX
#include <stm32f4xx_ll_tim.h>
...
#endif

and then the driver would just include:

#include <stm32_ll_tim.h>

The advantages of this approach:

1. SoC dependency on drivers' configuration is removed
2. Only the necessary stuff gets included
3. Out of tree application will also have access to generic LL headers, making it easier to create multi-family applications.

Detailed RFC

Proposed change (Detailed)

The first step would be to have the generic LL headers. Their generation can be scripted and included in the stm32_hal repository. The second step would be to take a reference driver, remove soc.h entries and include LL API directly in the driver. It should be a small change and can be done gradually to all other drivers.

Dependencies

To be discussed.

Concerns and Unresolved Questions

To be discussed.

Alternatives

N/A

[gmarull]

cc: @erwango @ABOSTM, @FRASTM, @arnopo, @Mani-Sadhasivam, @ydamigos, @cybertale, @lowlander, @Nukersson, @lochej, @avisconti, @loicpoulain

[lowlander]

@gmarull is the generation of those files in the stm32_hal repo something "a zephyr developer" does and than checks in the results, or is that something that has to happen every time a user builds something?

[gmarull]

@lowlander The idea is to have a script that generates these headers in the stm32_hal repository. When a new family is added, CubeMX updated... it should be run to make sure these headers are up-to-date.

[KozhinovAlexander]

@lowlander The idea is to have a script that generates these headers in the stm32_hal repository. When a new family is added, CubeMX updated... it should be run to make sure these headers are up-to-date.

Good idea. For me it looks like you're building some kind of additional layer between Zephyr RTOS and stm32 (see MCAL for example).

My suggestion: Maybe we should define the needed functionality/architecture of this abstraction layer and give it a name (e.g.: 'stm32_ZAL' meaning stm32 Zephyr Abstraction Layer)?

[KozhinovAlexander]

@gmarull Sorry, I have previously occasionally edited your answer below (don't know, how it happened). Your comment is still in it's original form 😃

[gmarull]

@Nukersson The proposal is not an abstraction layer in itself, it's just an additional header that includes the right LL header based on the active SOC_FAMILY in Zephyr.

[KozhinovAlexander]

@Nukersson The proposal is not an abstraction layer in itself, it's just an additional header that includes the right LL header based on the active SOC_FAMILY in Zephyr.

Just skimmed over your approach more intensively. I like it anyway. And it brings more portability between STM32 and Zephyr! Good work!