Why is HAL documentation lacking?

[Kristof Mulier]

Posted on February 02, 2017 at 11:40

The ST HAL should make programming STM32 microcontrollers easier. After all, it is a 'Hardware Abstraction Layer'. It provides an interface to the user, so he doesn't need to manipulate the hardware registers directly.

An abstraction layer is called 'leaky' when its interface isn't sufficient, such that the user needs to dig deeper into the low-level stuff. The failure of an abstraction layer generally has two causes:

(1) Bugs

I didn't bumb into bugs in the ST HAL. It looks like the code is of good quality and well-maintained.

(2) Lacking documentation

This is definitely the weakest point of the ST HAL. The documentation is so brief that I end up doing this:

>> Study the whole (related) chapters in the 'Reference Manual' of the chip

>> Open the functions of the ST HAL and read their code, study how the actual registers are manipulated

The lacking documentation forces the user to dig into the low-level stuff. This makes the abstraction very 'leaky', up to the point that I start to question its benefits.

Dear STMicro - please consider more investments into the HAL docs.

#hal #hal-driver #cubemx-stm32-hal

[Mohamed eleuche]

Posted on February 09, 2017 at 10:58

I am trying to add a simple ADC to an existent example using BSP (for LCD and TS) and there are no helpfull document! The IDE give me always error relating to the HAL and the only way to investigate is a single example (ADC_RegularConversion_DMA) without good explanation! 

[AvaTar]

Posted on February 09, 2017 at 11:23

Well, in my vocabulary, 'hardware abstraction' usually means to provide the same interface (API) for different implementations. And this might include very different MCU architectures, like Cortex M + C167 + <some proprietary japanese architecture>.

It is useful for specific application or a limited set of applications running on those platforms. And in any real-world scenario, a fairly good understanding of the hardware is required. And this is where I view the Cube advertisements counter-productive - the 'monkey klick button'attitude will fade quickly.

That's exactly it. Understanding requires time - 'quick results' precludes understanding.

Reminds me of the old saying about SW developers answering to project management requests:

'Cheap, quick and good. Pick any two you like.'

[Christophe Duparquet]

Posted on February 24, 2018 at 22:54

This is an old post, but I've worked for a few years on an original approach to ease hardware programming and I think you could be interested. The project is not stabilized yet and I'm just at the beginning regarding the support of STM32, but there are examples for Atmel devices that show what I think the usage of a good abstraction layer should look like. I'm almost sure that you've never seen something like this before! Any comment will be appreciated.

https://github.com/duparq/hwa

 

[waclawek.jan]

Posted on February 25, 2018 at 14:21

I might not subscribe to the idea, but it's interesting nevertheless.

Can you please start a new thread - best perhaps as a Blog, in the 'STM32 Community' rather than in the 'STM32 Forum' (as in the latter, ST's design decision was to not allow  Blogs for mere users), so that this could stand out in the crowd, and be discussed further?

JW

[henry.dick]

Posted on February 25, 2018 at 15:28

'

The reference manual is very well written.'

spot on.

I think after you have gone through the documentation for hal/spl/ll/whatever, in order to understand them and to save time, you have spent more time than you would have on the reference manual.

that's an irony for a framework designed to make it easier on the users.

[Christophe Duparquet]

Posted on February 26, 2018 at 18:28

Jan, following your suggestion, I've written this document :

https://community.st.com/0D50X00009bMM7tSAG

.