39. How to read ST documentation

Sooner or later every handbook runs out, while the question remains. Then you open the manufacturer's documentation, and it is all in English, about a thousand and a half pages long, and split into a dozen documents with opaque names. This section is about how to find your way in them and how to read their language.

The good news: the language of ST documentation is extremely uniform. Once you learn some forty phrases, you will understand any of its sections, even without speaking English fluently.

Terms used in the documentation

Term	Meaning
datasheet (DS)	the chip description: pins, electrical data, packages
reference manual (RM)	the reference guide: peripherals and registers
errata sheet (ES)	the list of known silicon bugs and workarounds
application note (AN)	a note on use: how to solve a specific task
user manual (UM)	the user guide of a board or a program
programming manual (PM)	the guide to programming the core
reset value	the register value after reset
reserved, must be kept at reset value	reserved, keep the value it has after reset

39.1 What kinds of documents there are

The main distinction, which saves hours of searching:

• There is one reference manual for the whole family. RM0008 covers STM32F101, F102, F103 and F105/107 at once. RM0090 covers all of F405/407/415/417/427/437/429/439. Registers within a family mostly match, so the document is shared. The differences are stated right in the text. In RM0008 the RCC of the Connectivity line (F105/F107) has AHBRSTR and CFGR2, which the F103 does not have (section 37), and some bits are marked "available only in connectivity line devices". In RM0090 the chapter on the LTDC display controller "applies only to STM32F429xx/439xx devices", and the F42x/F43x have FMC instead of FSMC. When you meet such a note, check the datasheet of your chip: does it have this block or this bit.
• Each set of packages and memory sizes has its own datasheet. The STM32F103 has several: one for "medium density", another for "high density". That is exactly why the pinout is looked up in the datasheet, not in the reference manual: a shared document simply cannot contain it.

For our two platforms:

39.2 What to look for where

A practical trick. When you open a reference manual, do not leaf through it: use the PDF table of contents and search by register name. Search not for "GPIO output" but directly for GPIOx_ODR: register names are unique, and the search takes you straight to the bit description, to the register map, and to the places where it is mentioned.

39.3 How a register description is built

All register descriptions in a reference manual are built the same way. Once you work through one, you can read any. The example is from RM0008 (STM32F103):

GPIOx_ODR — Port output data register (x = A..G)

Address offset: 0x0C
Reset value: 0x0000 0000

31                            16 15                             0
├─────── Reserved ──────────────┤├──────── ODR15..ODR0 ─────────┤
                                        rw

Bits 31:16  Reserved, must be kept at reset value.
Bits 15:0   ODRy: Port output data (y = 0..15)
            These bits can be read and written by software.

What to read first:

• Address offset: the offset from the base address of the block. Full address = port base + offset. This is exactly how the register structures in the headers are built (section 3). On the F4, MODER, OTYPER, OSPEEDR, PUPDR and IDR come before ODR, so the offset of GPIOx_ODR there is 0x14. Offsets differ between families; always take them from the RM of your chip.
• Reset value: what the register holds after reset. Useful for understanding which bits are already set as needed and need not be touched.
• The access notation under the bit map is the most important and the most underrated place.

Access notation

This explains things that otherwise look inexplicable:

• EXTI_PR is marked rc_w1: that is why an interrupt flag is cleared by writing a one, not a zero (section 7). This is not a quirk of the EXTI block: writing a one clears flags in many ST blocks. But not in all of them: the timer flags in TIMx_SR are marked rc_w0 and are cleared by writing a zero, while the DMA flags in DMA_ISR are read-only (r); they are cleared by writing a one to a separate register DMA_IFCR (on the F4, DMA_LIFCR and DMA_HIFCR). How to clear a flag, you check each time in the notation under the bit.
• GPIOx_BSRR is marked w: that is why BSRR |= mask makes no sense: there is nothing to read (section 5, where this is confirmed by comparing the assembly).
• USART_SR on the F1 and F4 is marked rc_w0 and r, not rc_r: the error flags (PE, FE, ORE, the noise flag) and IDLE are cleared by a sequence: read SR, then DR. The debugger's peripheral window reads all registers of the block, including DR: the sequence is done, the flag is gone, and the received byte is lost. Hence the classic mistake: you looked at the register in the debugger, the flag vanished, and the program behaved differently than without the debugger. A real rc_r is rare in STM32: for example, the WFR and MPR flags in ETH_MACPMTCSR are cleared by reading the register itself.

39.4 The language of the documentation

About forty phrases cover almost all of the text. They repeat word for word from section to section.

About bits and registers

About behavior

⚠️ The difference between must, should and may in technical documentation is not a matter of style. must: violating it makes the thing not work; should: violating it is allowed but risky; may: simply a possibility. Translations often erase this difference, and a recommendation turns into a requirement or the other way round.

Words that are translated wrongly

The Russian term "skvazhnost" in the strict sense is the inverse quantity T/τ: at a 25 % fill factor it equals 4. In speech, and in this handbook too, "skvazhnost" often means the fill factor itself (section 82.2); keep them apart in calculations.

39.5 Errata: read before, not after

An errata sheet is the official list of what in the silicon works differently from what the reference manual says. The document is short, takes half an hour to read, and that half hour pays off many times over.

A typical entry looks like this:

2.1.5  I2C analog filter may provide wrong value, locking BUSY flag

Description: ...
Workaround:  ...

That is: what is broken, under which conditions it shows up, and how to work around it.

Classic examples that cost people days:

• the F1 has a known sticking BUSY flag in I²C, because of which the bus "hangs" after a glitch; the workaround requires toggling the lines by hand (the F405/F407 have no such item: read the list for your own chip, 39б);
• in some families the first ADC sample after power-up is unreliable;
• in individual silicon revisions the behavior on wake-up from Stop differs.

The list is split by silicon revision, and for many items it says in which revision they were fixed, so you first need to know yours. You find it from the revision letter in the package marking or from the REV_ID field, the upper 16 bits of DBGMCU_IDCODE at address 0xE0042000 (the address is the same on the F1 and the F4). Which code corresponds to which letter is given at the start of the list and in the description of DBGMCU_IDCODE in the reference manual: on the F405/F407 0x1000 is revision A, 0x1001 is Z. The F103 has a catch: without a debugger DBGMCU_IDCODE reads as zero, and the program cannot find out its own revision; this is also an item of the errata list (section 2а).

The symptom is always the same: the code is written strictly according to the documentation, but works differently. Before you spend a third hour looking for a bug of your own, open the errata.

39.6 Application notes

A genre of its own: not a description of the hardware but a complete solution of a task, with formulas, schematics and code. Often it is a ready answer to a question you would otherwise have to piece together from a dozen places.

If a task looks typical, there is almost certainly an application note about it. Search: STM32 <topic> application note or directly AN with the number on the ST site.

39.7 How to search

The right keywords save more time than fluent English.

The register table trick. At the end of every reference manual section there is a summary table <block> register map and reset values: on one page, all the registers of the block with their offsets and reset values. Usually this is the only thing you need when the mechanism is already clear and you just have to check a bit.

39.8 Pitfalls

Done strictly according to the documentation, but it works differently. First of all, the errata list of the silicon: it may contain exactly this case (39.5).

A recommendation read as a requirement, or the other way round. must, should and may differ in meaning, and translations erase this difference (39.4).

The pinout is not in the reference manual. It is in the datasheet of the specific chip; registers are in the reference manual, the core is in the core programming manual (39.1–39.2).

39.9 Summary

• There is one reference manual per family, and a datasheet for each package. The pinout lives in the datasheet, registers in the reference manual, the core in the programming manual.
• The access notation under the bit map explains what otherwise looks like arbitrariness: rc_w1 means clearing by writing a one, w means there is nothing to read, rc_r means the flag disappears from the read itself.
• The language of the documentation is uniform: some forty phrases cover almost all of the text. must, should and may differ in meaning, not in style.
• Errata are read before development. The symptom "done by the documentation, works differently" is a reason to open them first of all.
• For a typical task there is almost always an application note with a ready solution.
• Search a document by register name, not by description: the names are unique and lead straight to all the places you need.

Next: section 39а "Official documents: what to get and where".