Skip to main content
Kristof Mulier
Kristof Mulier
Associate III
February 2, 2017
Question

Why is HAL documentation lacking?

  • February 2, 2017
  • 4 replies
  • 2853 views
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
This topic has been closed for replies.

4 replies

Nesrine M_O
Nesrine M_O
Associate
February 2, 2017
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 .

0690X00000606DeQAI.png

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-

MASSIMO MANCA
MASSIMO MANCA
Visitor II
February 3, 2017
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.

Christophe Duparquet
Christophe Duparquet
Associate
February 24, 2018
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

 
Kristof Mulier
Kristof MulierAuthor
Associate III
February 2, 2017
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?

henry.dick
henry.dick
Associate II
February 25, 2018
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.

Tesla DeLorean
Tesla DeLorean
Guru
February 2, 2017
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.

Tips, Buy me a coffee, or three.. PayPal VenmoUp vote any posts that you find helpful, it shows what's working..
Kristof Mulier
Kristof MulierAuthor
Associate III
February 2, 2017
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
waclawek.jan
Super User
February 2, 2017
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

parsec
parsec
Associate III
February 9, 2017
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

 
Terms & ConditionsAccessibility statement