AnsweredAssumed Answered

Why is HAL documentation lacking?

Question asked by Kristof Mulier on Feb 2, 2017
Latest reply on Feb 26, 2018 by Christophe Duparquet

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.

Outcomes