When will Reference manuals really be usable?

[EGi]

I write code and manuals for 36 years and I've learned that those are too often written by a person who fails to put himself in the readers position. A reader who's not familiar with the topic otherwise the material was not required in the first place. The easiest way to check a manual is to give it to somebody who doesn't know the topic and check where this person gets stuck. The STM32 reference manuals are full of gaps when a person wants to write bare metal code (or gives up on reverse engineer HAL / LL functions).

For instance: STM32L410 reference manual: RM0394 Rev 4: page 788 (and many others):

"the bit is cleared by software". What is missing here: HOW? By writing zero or writing '1'??? I would expect '0' based on my tests.

Any STM32 manual about timers: (L41x, L15x, F746, F767,..)

So far I found up to 6 channels per timer. Where is the info what channel uses what I/O pin??? The only way I can figure out is by assigning the pin in Cube and check what I/O pin changes. This is not a nice method to obtain the info. I can imagine in large companies where hardware design may be done by somebody else as the firmware engineer this becomes problematic.

STM32 advanced timer reference guides (same devices as above):

I've been trying to use the timer reload as a DMA trigger to write the Output compare, so I can output a PWM signal. I still haven't found what the DMA channel options are (I was in doubt TIM1_UP meant 1 count up, but so far seems more to be UPdate?). So far I failed to implement it using DMA triggers so I implemented in a different way.

Example code (just some info to consider in example programs):

a function called "io_init" or similar is expected to initialize the I/O, no need to write in comment virtually the same information if the function name explains everything (that type of comments just distracts without adding value). Better give a list of peripherals affected (anything else than "init the I/O" can be considered better). When one adds a comment, don't repeat what's obvious from function names / parameter names. For instance: provide parameter limits,.. all info not obvious from types or naming.

[Mike_ST]

>> For instance: STM32L410 reference manual: RM0394 Rev 4: page 788 (and many others):

>> "the bit is cleared by software". What is missing here: HOW? By writing zero or writing '1'??? I would expect '0' based on my tests.

The bits are defined as rc_w0.

If you go to page 60

1.2 List of abbreviations for registers you can see:

read/clear write0 (rc_w0) Software can read as well as clear this bit by writing 0. Writing 1 has no

effect on the bit value.

[waclawek.jan]

I agree that the manuals are badly written, and the fact that it's genuinely hard, takes a dedicated person or group, a well-designed process; and the fact that the competitors' manuals are worse - these are explanations, not excuses.

As for your particular questions:

• Mike_ST answered the first one
• mapping of peripherals to pins is always described in DS as it's considered product-specific. In ST's defense, this *is* documented, see GPIO chapter (Refer to the “Alternate function mapping�? table in the device datasheet for the detailed mapping of the alternate function I/O pins). Also, you are expected to read the DS anyway, and the AF tables can't be overlooked there. The partitioning of information between DS and RM may be matter of discussion. Btw. CH5 and CH6 in Advanced Timers usually don't have connection to GPIO (there are no related pins).
• TIM1_UP - yes, this means Update. In newer STM32 manuals (see 'G4) there's an attempt to unify description of signals names; unfortunately, it's not very consistent so this brings problems of its own, plus incompatibility with the older STM32.
• Example code - except for the aborted Snippets in 'L0/'F0 (and appendix in RM of these famiilies), there is no real example code for the STM32. Cube/HAL/LL contains example for those "libraries" but that's not example of the chip usage. https://community.st.com/s/ideazone#0873W000000KyjfQAC

JW

[gregstm]

Trying to get a peripheral up and running from the Reference manual can often be like a medieval quest. I felt this way when trying to get the DFSDM up and running with a digital (PDM) microphone. Just a simple code example of getting a microphone up and running via writing direct to registers would have saved me a lot of agony.