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

[Nesrine M_O]

Posted on February 02, 2017 at 13:54

Hi

Mulier.Kristof

,

Thank you very much for yourfeedbackand interest on HAL solution

'Lacking documentation': with any HAL firmware package a set of user manuals isprovided

to give adetailed description of each peripheral driver .

Could you please give to us example of missing information on HAL documentation, this may help usto understand well your expectation ?

Itis always required to review errata sheet, datasheet and reference manual in order touse efficiently your device.

-Nesrine-

[Kristof Mulier]

Posted on February 02, 2017 at 15:51

Hi

ELMHIRI.Syrine

‌ ,

Thank you very much for your quick reply :)

My latest problem relates to setting up the Timer peripheral on my STM32F767ZI device. I wanted to use the HAL, so I downloaded the following HAL documentation for the STM32F7xx family:

http://www.st.com/content/ccc/resource/technical/document/user_manual/45/27/9c/32/76/57/48/b9/DM001897pdf/files/DM001897pdf/jcr:content/translations/en.DM001897pdf

Chapter 60 is about the 'HAL TIM Generic Driver'. It basically lists out all the HAL functions and structures, but it doesn't explain how the Timer peripheral works. There is only one page (p 890) explaining very short 'How to use this driver'. But that is definitely not enough to start using it.

So I fall back on the STM32f7xx Reference Manual:

http://www.st.com/content/ccc/resource/technical/document/reference_manual/group0/96/8b/0d/ec/16/22/43/71/DM00224583/files/DM002245pdf/jcr:content/translations/en.DM002245pdf

The reference manual is very well written. It explains the timer module in very deep detail. After reading the reference manual, I can dig into the HAL code myself and reverse-engineer how it works.I have no issue with this personally - I like understanding how things work down to the bottom.

However, my employer hoped that the ST HAL would enable me to put the big Reference Manual aside and get things done quicker thanks to the HAL abstractions. But I miss the docs..

After reading your answer, I realized I didn't check all the application notes. I just found out the existence of the following document:

http://www.st.com/content/ccc/resource/technical/document/application_note/group0/91/01/84/3f/7c/67/41/3f/DM00236305/files/DM00236pdf/jcr:content/translations/en.DM00236pdf

This application note is quite big - 73 pages. I scroll through it now to get a feeling of what sort of information it contains. It refers indeed to the HAL, but most of its explanations are also on the register-level (see page 30, 31, 36, 37, ...). Perhaps it can be compared somewhat to the Reference Manual?

[Tesla DeLorean]

Posted on February 02, 2017 at 15:57

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

I'm not sure this is a deficiency. It's the type of thing you need to do otherwise you get a generation of coders that think watering plants with electrolytes is a good thing.

[Kristof Mulier]

Posted on February 02, 2017 at 16:06

Thank you

Turvey.Clive.002

‌

I agree with you. Call me crazy, but I like reading datasheets and reference manuals. It comforts me to understand how things work down to the bottom.

My employer tends to disagree, because thecompany - in fact our clients - want quick results. You know, long-term vs short-term interests ... ;)

[waclawek.jan]

Posted on February 02, 2017 at 16:39

Isn't the main idea in clicking-up the bulk of application in CubeMX? That's what I though is the promise of 'quick results' IMO.

Of course, this limits you to a few cathegories of applications, but that's what 'quick results' is all about, anyway.

You may quote me.

JW

[Kristof Mulier]

Posted on February 02, 2017 at 16:53

I'm not sure

Waclawek.Jan

‌ ,

With CubeMX you can get some HAL code, but this doesn't mean you understand what's going on. So you're stuck when you want to change things...

[waclawek.jan]

Posted on February 02, 2017 at 19:02

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

In my vocabulary, 'hardware abstraction' sounds just like  'I don't want to know what's happening in the hardware, just give me a simple uniform API'. Doesn't that sound as the exact opposite of understanding?

Unless your application fits into the categories which can be clicked in CubeMX, or which can be tweaked from the existing examples, or which can be generated using mbed (ST incarnation of which is built upon Cube), there's no 'quick solution'.

My personal view, arguable.

JW

[MASSIMO MANCA]

Posted on February 03, 2017 at 04:25

The problem is that when you need to read a huge manual to be able to use an API... means that something went wrong designing the API.

Also, the approach using structs as containers for the parameters of a function is questionable, it doesn't add more clarity and is just waste of memory. It may be helpful if the programmer writes the struct in ROM but anyway that is not a functionality devoted to an HAL API.

In particular, the situation of Cortex-M microcontrollers it is becoming paradoxical.

On one side ARM updates, upgrades and complicates CMSIS adding much more 'standard API' (as RTOS API) in a bottom-up fashion and on the other side ST and the other silicon vendors write the 'silicon vendor part' of CMSIS. The result is that this (wrong) interface prevents the use of a common API that may be usable with the same interface by any Cortex-Mx MCU.

Seems that ARM did a good job about instruction set scalability but not so much about CMSIS API scalability.

Think what means changing an HAL API in this context as happened with the last ST libraries (after Cube-MX).

The result is that to write SW we need to learn CMSIS and the libraries APIs and to debug at the lowest level the MCU datasheet. At the end, the situation now is worse than without the 'standard' CMSIS and APIs.

[parsec]

Posted on February 09, 2017 at 11:09

I agree it is lacking while perhaps not so much in content, even though there are improvements to be made there as well. Having to search 3 or 4 different PDF docs to find complete information for doing one task is unnecessarily involved. Much of this industry seems to be stuck in 1990, publishing data and notes in PDF documents which IMO is the wrong way forward. I also expressed this opinion in the 2017

https://community.st.com/community/stm32-community/stm32-forum/blog/2016/12/30/2017-stm32-wish-list?messageTarget=all&start=75&mode=comments

post (page 4, only 1 Like!?!?) about ST making an online, indexed help file/reference manual available. One with embedded links in the text that will let me access related information effortlessly. This would make the vast amount of available information much more easy to navigate.

As an example, look at ARM's online documentation. This is a good example how it should be done:

http://infocenter.arm.com/help/index.jsp