Tento článek ukazuje, jak z té smyčky získat řádek zdrojového kódu, na dvou skutečných příkladech, které jsem spustil v QEMU (model desky se STM32F4) a prozkoumal pomocí GDB: volání ukazatele na funkci s hodnotou NULL a zápis na adresu, kde nic není. Všechny výstupy jsou skutečné.

Co jádro udělá, když nastane chyba​

Cortex-M nepadá tiše. Když procesor nemůže pokračovat (neplatná instrukce, chyba sběrnice, nepovolený přístup), vyvolá výjimku a udělá dvě věci důležité pro ladění:

1. Uloží osm registrů na zásobník: R0, R1, R2, R3, R12, LR, PC a xPSR. Uložený PC je instrukce, která chybu způsobila, a uložený LR říká, kdo chybující funkci zavolal.
2. Nastaví bity ve stavových registrech chyb, které říkají, o jaký druh chyby šlo: CFSR (configurable fault status, složený ze tří částí pro memory, bus a usage fault), HFSR (hard fault status) a adresní registry MMFAR a BFAR s adresou, ke které se přistupovalo.

Memory, bus a usage fault mají své vlastní handlery, ale po resetu jsou zakázané, takže každá chyba je eskalována na HardFault. Proto jediný handler vidí všechno a bit FORCED v HFSR říká, že k tomu došlo.

Handler, který čte registry​

Jediná potíž je dostat se na zásobník, kde registry leží. Jádro má dva ukazatele zásobníku (MSP pro výjimky a hlavní kód, PSP pro úlohy operačního systému) a bit 2 hodnoty v LR při vstupu do výjimky říká, který z nich byl použit. To je nutné udělat dříve, než překladač použije zásobník pro své účely, takže handler je krátká funkce v assembleru (naked: bez prologu), která předá ukazatel funkci v C:

/* ---- the fault report ---- */
#define SCB_CFSR  (*(volatile uint32_t *)0xE000ED28u)   /* configurable fault status */
#define SCB_HFSR  (*(volatile uint32_t *)0xE000ED2Cu)   /* hard fault status */
#define SCB_MMFAR (*(volatile uint32_t *)0xE000ED34u)
#define SCB_BFAR  (*(volatile uint32_t *)0xE000ED38u)

/* The registers that the core pushed on the stack when the fault happened. */
typedef struct
{
    uint32_t r0, r1, r2, r3, r12;
    uint32_t lr;     /* where the faulting code was called from */
    uint32_t pc;     /* the instruction that caused the fault   */
    uint32_t xpsr;
}   stackFrame_t;

volatile struct
{
    stackFrame_t frame;
    uint32_t     cfsr, hfsr, mmfar, bfar;
}   faultInfo;

void HardFault_Report(const stackFrame_t *frame) __attribute__((used));
void HardFault_Report(const stackFrame_t *frame)
{
    faultInfo.frame = *frame;
    faultInfo.cfsr  = SCB_CFSR;
    faultInfo.hfsr  = SCB_HFSR;
    faultInfo.mmfar = SCB_MMFAR;
    faultInfo.bfar  = SCB_BFAR;

    Print("*** HardFault ***\n");
    PrintHex("PC   ", frame->pc);
    PrintHex("LR   ", frame->lr);
    PrintHex("xPSR ", frame->xpsr);
    PrintHex("CFSR ", faultInfo.cfsr);
    PrintHex("HFSR ", faultInfo.hfsr);

    for (;;) { }          /* stay here, so that a debugger can look at the state */
}

/* The core uses the main or the process stack, depending on bit 2 of EXC_RETURN (in LR). */
__attribute__((naked)) void HardFault_Handler(void)
{
    __asm__ volatile (
        "tst   lr, #4        \n"
        "ite   eq            \n"
        "mrseq r0, msp       \n"
        "mrsne r0, psp       \n"
        "b     HardFault_Report \n"
    );
}

Podívejte se na tři části. Struktura stackFrame_t je rozložení osmi registrů v pořadí, v jakém je jádro ukládá. Funkce HardFault_Report() (spolu se stavovými registry) zkopíruje do globální proměnné faultInfo, vypíše krátkou zprávu a pak záměrně zůstane ve smyčce, aby se mohl připojit debugger a proměnnou si prohlédnout. Assemblerová vložka vybere správný zásobník a skočí do ní. V produktu by se zpráva zapsala do paměti, která přežije reset, a firmware by se sám resetoval, ale princip je stejný.

Příklad 1: volání ukazatele NULL​

Toto je aplikace s chybou. Callback se zaregistruje později, ale kód, který ho volá, běží dříve:

/* ---- the application with a bug ---- */
typedef void (*callback_t)(void);

static callback_t onButtonPressed;      /* will be registered later: it is NULL at the start */

void Button_Pressed(void)
{
    onButtonPressed();                  /* the bug: the callback is called before it is set */
}

int main(void)
{
    Print("start\n");
    Button_Pressed();
    Print("never printed\n");
    return 0;
}

Program vypíše start a potom zprávu:

start
*** HardFault ***
PC    0x00000000
LR    0x08000115
xPSR  0x60000000
CFSR  0x00020000
HFSR  0x40000000

Teď její čtení, hodnotu po hodnotě:

• PC = 0x00000000: procesor se pokusil provést instrukci na adrese nula. Téměř vždy to znamená skok přes ukazatel na funkci s hodnotou NULL nebo návrat na poškozenou adresu.
• CFSR = 0x00020000: bit 17 je INVSTATE, „invalid state". Procesor se pokusil vykonávat kód ve stavu ARM, který Cortex-M nemá. Důvod je v xPSR: jeho bit 24 je bit T (Thumb) a tady je nulový (0x60000000). Adresa funkce v Thumbu má nejnižší bit nastavený, NULL ho nemá, takže skok přes ukazatel bit T vynuloval. Nulový bit T je typický otisk prstu skoku na NULL.
• HFSR = 0x40000000: bit 30 je FORCED, chyba byla eskalována na HardFault z usage fault, který není povolen.
• LR = 0x08000115: návratová adresa s nastaveným nejnižším bitem (Thumb). Je to adresa volajícího, 0x08000114, a právě tam je chyba.

S debuggerem trvá poslední krok pár sekund. QEMU čeká na GDB (-S -gdb tcp::1234) a session vypadá takto:

(gdb) break fault.c:64
(gdb) continue
Breakpoint 1, HardFault_Report (frame=0x2001ffc0) at fault.c:64
(gdb) print/x faultInfo.frame
$1 = {r0 = 0xdeadbeef, r1 = 0x80001f4, r2 = 0x8000220, r3 = 0x0, r12 = 0x0,
      lr = 0x8000115, pc = 0x0, xpsr = 0x60000000}
(gdb) print/x faultInfo.cfsr
$2 = 0x20000
(gdb) info symbol faultInfo.frame.lr
Button_Pressed + 7 in section .text
(gdb) list *(faultInfo.frame.lr & ~1u)
0x8000114 is in Button_Pressed (fault.c:87).
82	static callback_t onButtonPressed;      /* will be registered later: it is NULL at the start */
84	void Button_Pressed(void)
85	{
86	    onButtonPressed();                  /* the bug: the callback is called before it is set */
87	}
(gdb) x/2i (faultInfo.frame.lr & ~1u) - 4
   0x8000110 <Button_Pressed+2>:	movs	r3, #0
   0x8000112 <Button_Pressed+4>:	blx	r3

info symbol vrátí funkci, list * řádek (ten za voláním, protože to je návratová adresa) a disassembly ukáže dvojici instrukcí, která je samotnou chybou: načtení nuly do r3 a blx r3, volání přes registr obsahující NULL. Všimněte si r3 = 0x0 v uložených registrech. Bez debuggeru je tatáž odpověď jedním příkazem toolchainu, který potřebuje jen adresu ze zprávy a soubor s ladicími informacemi (-g):

$ arm-none-eabi-addr2line -e fault.elf -f 0x08000114
Button_Pressed
fault.c:87

Příklad 2: zápis na adresu, kde nic není​

Změnil jsem jeden řádek aplikace: místo callbacku funkce zapisuje na adresu 0xA0000000, kde v modelu čipu není namapováno nic. Zpráva:

*** HardFault ***
PC    0x08000124
LR    0x08000199
xPSR  0x21000000
CFSR  0x00008200
HFSR  0x40000000

Tentokrát je PC platná adresa ve flash, bit T je nastaven (0x21000000) a CFSR je jiný: 0x8200 jsou dva bity, 9 (PRECISERR, přesná chyba datové sběrnice) a 15 (BFARVALID, registr BFAR obsahuje adresu). V GDB:

(gdb) print/x faultInfo.cfsr
$1 = 0x8200
(gdb) print/x faultInfo.bfar
$2 = 0xa0000000
(gdb) info symbol faultInfo.frame.pc
main + 12 in section .text

BFAR je adresa, na kterou se program pokusil zapisovat, PC je instrukce, která se o to pokusila. Dohromady říkají „tato instrukce zapsala na tuto adresu", což je úplný popis problému. Pokud je adresa malá (0x00000008), jde o ukazatel NULL na strukturu a vy přistupujete k jejímu členu. Pokud vypadá jako data (0x20000000 a kousek víc), jde o zásobník nebo buffer, který jste přetekli.

Bity CFSR, se kterými se setkáte​

Registr je kombinací tří registrů (každý má svůj bajt nebo dva bajty). Tohle jsou ty, které uvidíte nejčastěji (dva, které jsem pozoroval v příkladech, jsou zvýrazněny):

Co obvykle stojí za HardFaultem​

První řádek tabulky a princip druhého (chyba sběrnice s adresou v BFAR) jsem předvedl. Zbývající řádky jsou souhrnem obvyklých příčin, vyplývají z významu bitů v referenční příručce jádra.

Praxe​

1. Nikdy nenechávejte výchozí handler jako prázdnou smyčku. Handler výše má asi třicet řádků a promění chybu ve zprávu s místem v kódu. Vložte ho jednou do startup kódu projektu.
2. Uchovávejte ladicí informace v souboru, který archivujete s vydáním (-g a .elf), aby šla adresa ze zprávy z provozu převést na řádek, i když je firmware dodán bez symbolů. To je také další důvod pro reprodukovatelný build: adresa něco znamená jen pro přesně ten binární soubor, který ji vytvořil.
3. Povolte jemnější chyby (bity v SHCSR), když chcete mít handlery UsageFault, BusFault a MemManage zvlášť. Zpráva je pak bohatší, protože stavové registry nejsou sdílené.
4. Ukládejte zprávu do paměti, která přežije reset (sekce, kterou startup kód nemaže, viz článek o tom, co se děje před main()), proveďte reset a po restartu ji odešlete. Zpráva ze zařízení v provozu má větší cenu než sto dohadů.
5. Předcházejte tomu, co jde. Volání NULL v příkladu je vada, kterou by zachytila pravidla MISRA a unit test modulu (ukazatel musí být nastaven před prvním voláním), a přetečení zásobníku je věc, pro kterou je nutné znát využití zásobníku (pravidlo proti rekurzi).

Stejná session na desce​

Použil jsem QEMU, protože nepotřebuje desku, a jeho GDB server (-S -gdb tcp::1234) se chová stejně jako server debug probe: příkazy v příkladech jsou příkazy, které zadáváte i s probe. Platforma má artefakt pro sadu nástrojů probe-rs (ladicí sada pro cíle ARM přes debug probe, se serverem DAP), což je způsob, jak připojit GDB nebo IDE ke skutečné desce. Pro tento článek jsem ho nespouštěl, protože ve svém prostředí probe nemám.

Shrnutí​

1. HardFault není záhada: jádro uložilo registry a nastavilo stavové bity.
2. Handler musí najít správný zásobník (EXC_RETURN) a přečíst rámec, CFSR, HFSR a BFAR.
3. PC a LR dávají místo, CFSR druh chyby, BFAR adresu.
4. PC = 0 s INVSTATE je skok na NULL a bit T v xPSR to ukazuje.
5. Uchovejte .elf a adresa ze zprávy z provozu se promění v řádek kódu.

Ukážu dva experimenty, které jsem spustil: tentýž zdrojový kód testu, který na PC projde a na Cortex-M4 selže, a firmware, který zapisuje do registrů USART na skutečných adresách STM32F4 a jehož text se objeví v terminálu. Na konci je upřímný seznam toho, co vám simulátor neřekne.

Kam to zapadá​

Prostřední úroveň se vynechává nejčastěji a přitom je nejlevnější na přidání do CI, které už firmware sestavuje: simulátor je spustitelný soubor, který zavoláte se souborem, který váš build vytvořil.

Nástrojem v mých experimentech je QEMU 8.2.2 se strojem netduinoplus2, modelem desky se STM32F405 (Cortex-M4 s mapou paměti skutečného čipu: flash na 0x08000000, RAM na 0x20000000, periferie na svých skutečných adresách). Platforma má artefakt pro jiný simulátor, Renode, a k tomu se vrátím na konci.

Experiment 1: test, který projde na PC a selže na MCU​

Malý modul se dvěma funkcemi, které má každý firmware: převod času a kontrola přijatého bajtu.

#include "Conversions.h"

long Conversions_Get_Microseconds(uint32_t milliseconds)
{
    return (long)milliseconds * 1000L;
}

bool Conversions_Is_HighBitSet(char receivedByte)
{
    return (receivedByte < 0);
}

Obě funkce vypadají správně a obě jsou otestovány na PC. Zdrojový kód testu je pro oba cíle stejný: liší se jen výstup. Soubor Platform.h tiskne přes printf na PC a přes semihosting (požadavek na simulátor nebo debugger) na cíli a návratový kód testu říká, zda prošel:

#ifndef PLATFORM_H
#define PLATFORM_H

/* The same test source runs on the PC and on the target: only the output differs. */
#if defined(__arm__)
    #include <stdint.h>
    static inline int Semihost_Call(int operation, const void *argument)
    {
        register int   r0 __asm__("r0") = operation;
        register const void *r1 __asm__("r1") = argument;
        __asm__ volatile ("bkpt 0xAB" : "+r"(r0) : "r"(r1) : "memory");
        return r0;
    }
    static inline void Platform_Print(const char *text) { (void)Semihost_Call(0x04, text); }
    static inline void Platform_Exit(int failures)
    {
        /* 0x20026: the application exited normally, 0x20023: the application failed */
        (void)Semihost_Call(0x18, (const void *)(0 == failures ? 0x20026u : 0x20023u));
    }
#else
    #include <stdio.h>
    #include <stdlib.h>
    static inline void Platform_Print(const char *text) { fputs(text, stdout); }
    static inline void Platform_Exit(int failures)      { exit(0 == failures ? 0 : 1); }
#endif

#endif

#include <stdbool.h>
#include <stdint.h>
#include "Conversions.h"
#include "Platform.h"

static int failures;

#define CHECK(condition, name)                                          \
    do {                                                                \
        if (condition) { Platform_Print("PASS  " name "\n"); }          \
        else           { Platform_Print("FAIL  " name "\n"); failures++; } \
    } while (0)

int main(void)
{
    /* 3 000 000 ms = 50 minutes = 3 000 000 000 us */
    CHECK(3000000000L == Conversions_Get_Microseconds(3000000u), "50 minutes in microseconds");
    CHECK(5000L == Conversions_Get_Microseconds(5u),             "5 ms in microseconds");

    /* the byte 0xFF is received from the UART */
    CHECK(true == Conversions_Is_HighBitSet((char)0xFF),         "0xFF has the high bit set");
    CHECK(false == Conversions_Is_HighBitSet((char)0x41),        "'A' has not the high bit set");

    Platform_Exit(failures);
    return failures;
}

Na PC:

PASS  50 minutes in microseconds
PASS  5 ms in microseconds
PASS  0xFF has the high bit set
PASS  'A' has not the high bit set
exit code: 0

Tentýž zdroj, přeložený pomocí arm-none-eabi-gcc pro Cortex-M4 a spuštěný v QEMU:

FAIL  50 minutes in microseconds
PASS  5 ms in microseconds
FAIL  0xFF has the high bit set
PASS  'A' has not the high bit set
exit code: 1

Dvě chyby a obě jsou na PC neviditelné:

• long má jinou šířku. Na 64bitovém Linuxu má long 64 bitů, na Cortex-M 32. 3 000 000 ms * 1000 je 3 000 000 000, což se nevejde do znaménkového 32bitového čísla (největší je 2 147 483 647), takže výsledek je špatný a v C je to navíc nedefinované chování.
• char má jiné znaménko. Standard C nechává otevřené, zda je prosté char se znaménkem. Na x86 je, takže (char)0xFF je -1 a kontrola receivedByte < 0 funguje. Na ARM je bez znaménka, takže (char)0xFF je 255 a porovnání nikdy neplatí. Překladač ARM to dokonce říká, a jen tam:

Conversions.c:10:26: warning: comparison is always false due to limited range of data type [-Wtype-limits]

Obojí je otázka přenositelných typů, což je téma pravidla 4.6 v článku o MISRA: používejte typy s danou velikostí a znaménkem. Opravená verze používá uint64_t pro čas a uint8_t pro bajt:

uint64_t Conversions_Get_Microseconds_Fixed(uint32_t milliseconds)
{
    return (uint64_t)milliseconds * 1000u;
}

bool Conversions_Is_HighBitSet_Fixed(uint8_t receivedByte)
{
    return (0u != (receivedByte & 0x80u));
}

a stejné čtyři kontroly teď procházejí na obou cílech, s návratovým kódem 0 na obou. První verze nebyla chybou testu a test na PC nebyl špatně: prostě testoval jiný program.

Návratový kód je celá integrace s CI. Simulátor skončí s kódem, který firmware předá volání semihostingu, takže add_test v CMake (viz článek o CMake pro firmware) selže, když selže test na cíli:

add_test(NAME conversions_on_target
    COMMAND qemu-system-arm -M netduinoplus2 -nographic
            -semihosting-config enable=on,target=native -kernel conversions_test.elf)

Experiment 2: registry periferie​

Simulátor modeluje také periferie, takže může běžet i kód nejbližší hardwaru. Tohle je firmware, který posílá text přes USART1 čipu STM32F4, napsaný na úrovni registrů se skutečnými adresami (žádná knihovna, žádný startup kromě kódu z článku o tom, co se děje před main()):

#include <stdint.h>

/* STM32F4: RCC and USART1 registers, the same addresses as on the real chip */
#define RCC_APB2ENR  (*(volatile uint32_t *)0x40023844u)
#define USART1_SR    (*(volatile uint32_t *)0x40011000u)
#define USART1_DR    (*(volatile uint32_t *)0x40011004u)
#define USART1_CR1   (*(volatile uint32_t *)0x4001100Cu)

#define RCC_APB2ENR_USART1EN  ( 1u << 4 )
#define USART_CR1_UE          ( 1u << 13 )
#define USART_CR1_TE          ( 1u << 3 )
#define USART_SR_TXE          ( 1u << 7 )

static void Uart_Send(const char *text)
{
    while ('\0' != *text)
    {
        while (0u == (USART1_SR & USART_SR_TXE)) { }     /* wait until the data register is empty */
        USART1_DR = (uint32_t)(unsigned char)*text++;
    }
}

int main(void)
{
    RCC_APB2ENR |= RCC_APB2ENR_USART1EN;                  /* clock of the peripheral */
    USART1_CR1  |= USART_CR1_UE | USART_CR1_TE;           /* enable the USART and its transmitter */

    Uart_Send("hello from the register level\r\n");

    for (;;) { }
}

hello from the register level

Text je v terminálu simulátoru: firmware zapnul hodiny periferie v RCC, povolil USART a jeho vysílač, počkal na příznak TXE a zapsal datový registr, přesně jako by to udělal na desce, a model USART předal bajt na sériový port. Je to test ovladače proti modelu registrového rozhraní. Pokud ovladač čeká na příznak, který nikdy nepřijde, test to najde pomocí timeoutu, a ne u stolu s osciloskopem.

Co vám simulátor neřekne​

Simulátor je model a každý model má hranici. Několik, na které jsem narazil v experimentech této série:

• Časování není skutečné. QEMU provádí instrukce tak rychle, jak PC dovolí, a nepočítá cykly skutečného jádra. Test, který musí dokázat „přerušení je obslouženo do 5 mikrosekund", se v něm udělat nedá.
• Přerušení přicházejí na jiných místech než na MCU. V článku o přerušeních se ztracená aktualizace sdíleného čítače v QEMU neobjevila ani při 200 000 pokusech, protože QEMU doručuje přerušení mezi bloky přeloženého kódu. Skutečné MCU může přerušit po každé instrukci. Simulátor neprokazuje nepřítomnost race condition.
• Existují jen modelované periferie. Model STM32F405 má USART, ale jiný čip může mít periferii, kterou model nemá, nebo ji má zjednodušenou: registry tam jsou, analogová část ne.
• Chybí elektrický svět: zákmit kontaktu, šum na vstupu ADC, pokles napětí. Vše, co přichází zvenčí, je to, co do modelu vložíte.

Simulátor tedy nenahrazuje ani unit testy (jsou rychlejší a testují logiku izolovaně), ani hardwarové testy (testují realitu). Najde věci mezi nimi: překladač cíle, typy, startup, mapu paměti, ovladač proti modelu registrů, a dělá to během několika sekund při každém commitu.

Renode​

Platforma má artefakt pro Renode, open-source simulační a virtuální vývojový framework od Antmicro, dodávaný spolu s renode-test, svým testovacím runnerem založeným na Robot Framework, který se používá pro integrační testy simulovaného firmwaru. Pro tento článek jsem ho nespouštěl (vydání se v mém prostředí nepodařilo stáhnout), takže pouze opakuji, co říká jeho dokumentace, a neporovnávám ho s QEMU. Struktura takového testu je stejná jako výše: skutečný ELF, model hardwaru, verdikt a návratový kód pro CI.

Kontrolní seznam​

1. Sestavte test pro cíl, překladačem cíle, a spusťte ho v simulátoru, navíc k PC.
2. Používejte jeden zdroj testu pro obojí, s tenkou vrstvou (Platform.h) pro výstup a ukončení.
3. Návratový kód simulátoru je výsledek testu, takže CI nepotřebuje nic dalšího.
4. Používejte typy s danou velikostí a znaménkem (uint32_t, uint8_t) a varování překladače cíle: druhou chybu výše (char) by našlo -Wtype-limits, kdyby se někdo díval na výstup buildu pro ARM.
5. Zapište si, co simulátor dokázat nemůže (časování, race condition, analogový svět), a nechte to hardwarovým testům.

Reprodukovatelný build má jednoduchou definici: stejné vstupy dají stejné bajty. Tento článek ukazuje, jaké jsou vstupy buildu firmware, jak je platforma Embedbits připíná (Artifacts Handler) a experiment, který jsem udělal: dva buildy stejného zdroje, ve dvou složkách ve dvou různých časech, dají dvě různé binárky. Po třech změnách pak dají tu samou, co do posledního bitu.

Vstupy buildu​

Build je funkce. Co do ní vstupuje?

První, třetí a čtvrtý vstup jsou v Gitu, takže jsou připnuté už návrhem. Nástroje a prostředí jsou místa, kde se build obvykle rozbije, a každé z nich má vlastní odpověď.

Nástroje: Artifacts Handler​

„Nainstalujte GCC 13.2 a Ninja 1.12“ v README je věta, kterou nikdo nedodržuje doslova. Platforma to řeší tím, že z nástrojů dělá součást projektu. Artifacts Handler je skript CMake, který ze souboru ArtifactsConfig.txt přečte seznam nástrojů a jejich verzí a připraví je. Jeho dokumentace uvádí, že jediný software, který uživatel potřebuje, je Git a CMake, a že každou další komponentu buildu dodá handler. Po krocích:

1. Naklonuje kořenový repozitář artefaktů (bez submodulů, aby se ušetřil provoz).
2. Najde v něm artefakt (každý nástroj je submodul, názvy se porovnávají bez ohledu na velikost písmen).
3. Checkoutne požadovanou verzi (mělký klon, --depth=1). Vydání jsou označena tagem podle verze a operačního systému (Win, Unix, DarwinARM).
4. Nainstaluje ho: rozbalí archiv do složky cache.
5. Inicializuje ho: ve většině případů vloží složku nástroje na začátek PATH, takže nástroj projektu vyhraje nad jakýmkoli nástrojem nainstalovaným v systému.

Konfigurace má jeden řádek na nástroj, name;version;handler version, například řádky z dokumentace platformy:

ninja;1.12.1;1
gcc-arm-none-eabi;13.2.rel1;2

První číslo je verze samotného nástroje (binárky), druhé je verze skriptu handleru daného artefaktu (může se měnit nezávisle, například když se opraví způsob nastavení PATH). Cache má jednu složku na nástroj a verzi, takže několik verzí žije vedle sebe a projekt, který potřebuje starší, neruší projekt, který potřebuje novější.

Proč ne latest​

Handler také přijímá latest místo čísla. Je to pohodlné a rozbíjí to celou myšlenku. Spustil jsem handler s řádkem ninja;latest;latest a vypsal, na co to 5. října 2026 přeložil:

-- Processing artifact ninja with Bin version latest and Core version latest.
-- The version 1.0.0 of artifacts Core part will be used.
-- The version 1.13.2 of artifacts Bin part will be used.

(Běh se zastavil při stahování vydání, protože moje prostředí nedosáhne na GitHub API, ale vyřešení proběhlo.) latest je pohyblivý cíl: dokumentace říká, že seznam verzí se stahuje jednou denně, takže stejný soubor dnes dá 1.13.2 a po dalším vydání něco jiného. Build, který je dnes správný, může být zítra jiný build a nic ve vašem repozitáři to neříká. Pravidlo je proto jednoduché: latest je pro zkoušení nové verze a vydaný projekt připíná každé číslo.

Další nastavení, která pomáhají​

• Offline režim (-DOFFLINE_MODE=true): kontroluje se jen lokální cache a nic se nestahuje. Je to způsob, jak dokázat, že build nezávisí na síti, a způsob, jak stavět tam, kde síť není.
• Umístění cache (ARTIFACTS_HANDLER_CACHE_PATH) a kořenového repozitáře (ARTIFACTS_HANDLER_ROOT_REPO_URL) lze nastavit v konfiguračním souboru, v prostředí nebo na příkazové řádce. Firma může provozovat vlastní zrcadlo artefaktů, takže build nezávisí ani na veřejném serveru.
• Kontrolní součet. Každé vydání artefaktu je publikováno se souborem SHA-256 vedle archivu, takže poškozený nebo vyměněný soubor není tiše přijat.

Nástroje jsou první polovina odpovědi. Druhá polovina je něco, co si můžete ověřit sami, pomocí příkazu níže.

Prostředí: experiment​

Vzal jsem ukázkový projekt z článku o CMake a přidal soubor, který má většina firmware v nějaké podobě: informace o buildu. Ukládá čas buildu a cestu ke zdrojovému souboru, protože někdo kdysi chtěl v debuggeru vidět „kdy se to přeložilo“:

const char buildFile[] = __FILE__;
const char buildTime[] = __DATE__ " " __TIME__;

Pak jsem stejný zdroj přeložil dvakrát: ve dvou různých složkách (a a b), druhý o tři sekundy později. Příkaz strings použitý na obě binárky ukazuje, co je uvnitř:

Oct  5 2026 15:46:02
/tmp/.../repro/a/Application/BuildInfo.c
---
Oct  5 2026 15:46:05
/tmp/.../repro/b/Application/BuildInfo.c

a SHA-256 obou souborů firmware.bin se liší:

f2366319462b6fee...
d634c24c3c431799...

Dva buildy jednoho zdroje, dvě různé binárky. Čas je zřejmý, ale cesta je ta, na kterou lidé zapomínají: __FILE__ (a také assert() a ladicí informace) zapisuje do programu plnou cestu k souboru a cesta je jiná na PC každého vývojáře a v každé úloze CI. Binárka přeložená v /home/anna/project a ta samá přeložená v /builds/job-4711/project jsou dva různé soubory.

Tři změny​

1. Odstraňte hodiny. Makra __DATE__ a __TIME__ nemají místo ve firmware, který má být reprodukovatelný. Překladač to dokáže vynutit, takže je nikdo omylem nepřidá zpět:

BuildInfo.c:5:26: error: macro "__DATE__" might prevent reproducible builds [-Werror=date-time]
BuildInfo.c:5:39: error: macro "__TIME__" might prevent reproducible builds [-Werror=date-time]

2. Verze je vstup. Pokud chcete vědět, „co je to za firmware“, build dostane odpověď zvenku: verzi, tag nebo hash commitu, který build systém předá jako definici. Stejný zdroj má stejnou verzi, tedy stejné bajty:

#ifndef BUILD_VERSION
#define BUILD_VERSION "unknown"
#endif

const char buildVersion[] = BUILD_VERSION;

3. Odstraňte cesty. Volba -ffile-prefix-map=OLD=NEW nahradí prefix každé cesty, kterou GCC vloží do výstupu (__FILE__, ladicí informace, aserce). Zdrojová složka projektu se nahradí tečkou:

# The version of the firmware is an input of the build, not the time of the build.
set(FIRMWARE_VERSION "1.2.3" CACHE STRING "Version of the firmware")
add_compile_definitions(BUILD_VERSION="${FIRMWARE_VERSION}")

# No clock in the binary, and no path of this PC in it.
add_compile_options(${MCU_FLAGS} ${WARNING_FLAGS} ${BUILD_OPTIONS}
                    -Wdate-time -Werror=date-time
                    -ffile-prefix-map=${CMAKE_SOURCE_DIR}=.)

S těmito třemi změnami dá stejná kontrola:

first : 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
second: 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
REPRODUCIBLE

.bin je identický, stejně jako .elf, v release (-Os -g0) i v debug buildu (-Og -g3), jehož ladicí informace jsou plné cest. Díky -ffile-prefix-map ukazuje strings binárky ./Application/BuildInfo.c a verzi 1.2.3 a nic o PC, které ji přeložilo.

Test, který nezestárne​

Nestačí udělat build reprodukovatelným jednou, protože první __TIME__, který někdo přidá, ho zničí. Udělejte z něj proto test: přeložte zdroj dvakrát a porovnejte. Tohle je skript, kterým jsem získal čísla výše; zkopíruje projekt do dvou složek, přeloží oba s pauzou mezi nimi a porovná SHA-256:

#!/usr/bin/env bash
# Builds the same source twice, in two different folders, and compares the firmware.
set -euo pipefail

source_dir="$(cd "$1" && pwd)"
config="${2:-Release}"
work="$(mktemp -d)"

for copy in first second; do
    cp -r "$source_dir" "$work/$copy"
    rm -rf "$work/$copy/build"
    cmake -S "$work/$copy" -B "$work/$copy/build" -G Ninja \
          -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake -DCMAKE_BUILD_TYPE="$config" > /dev/null
    cmake --build "$work/$copy/build" > /dev/null
    sleep 2                                    # the second build is later and is in another folder
done

first="$(sha256sum "$work/first/build/firmware.bin" | cut -d' ' -f1)"
second="$(sha256sum "$work/second/build/firmware.bin" | cut -d' ' -f1)"

echo "first : $first"
echo "second: $second"
if [ "$first" = "$second" ]; then echo "REPRODUCIBLE"; else echo "NOT REPRODUCIBLE"; exit 1; fi

Spouštěný v CI při každém mergi je strážcem. Použil jsem ho i na rozbitou verzi informací o buildu, abych si byl jistý, že umí selhat, a selhal (NOT REPRODUCIBLE, návratový kód 1, dva různé hashe). Test, který nikdy neselhal, je test, který neznáte.

Co dalšího reprodukovatelný build rozbíjí​

Otestoval jsem tři věci výše. Následující jsou další dobře známé zdroje potíží, které byste měli mít na paměti (v příkladu jsem je nepotřeboval, takže je jen jmenuji):

• Pořadí souborů pocházející z file(GLOB ...) nebo z výpisu adresáře. Zdroje by měly být vypsané explicitně, jako v souborech CMake modulů platformy.
• Časové razítko v archivu (statická knihovna vytvořená ar). Moderní verze nástrojů mají deterministický režim, ale starý toolchain ho mít nemusí.
• Generovaný kód. Mocky a runnery unit testů nebo linker script generovaný pro MCU se musí generovat stejně ze stejných vstupů. Pravidla jsou řazení a žádná časová razítka na výstupu.
• Samotný překladač. Stejná verze stejného překladače ze dvou zdrojů (balíček distribuce a archiv výrobce) se může lišit v knihovnách, které linkuje. To je důvod, proč brát překladač z jednoho místa, což je smyslem artefaktů.
• Build s jiným počtem vláken. Správný build systém dá stejný výsledek s -j1 i -j16 a test toho je levným doplňkem k tomu výše.

Kontrolní seznam​

1. Každý nástroj je v ArtifactsConfig.txt připnutý na přesnou verzi. Žádné latest ve vydání.
2. Submoduly (BSP, platforma) jsou připnuté commity a aktualizace je viditelný commit.
3. Nic ve firmware nezávisí na čase ani cestě: -Werror=date-time, -ffile-prefix-map.
4. Verze je parametr buildu, odvozený z tagu, a je uložená ve firmware.
5. CI staví dvakrát a porovnává. Čas od času také staví offline, z cache.
6. Dodaná binárka je uložena spolu se svým SHA-256 a tagem, takže otázka „je to stejný soubor“ má odpověď bez nového buildu.

Odměnou je věta, kterou použijete do telefonu se zákazníkem: „Přeložil jsem přesně váš firmware a chyba v něm (ne)je.“

Kód z modulu je citován z větve STM32H5 repozitáře Bsp-Mcal-Gpio. Příklady, které ho používají, byly přeloženy a spuštěny proti skutečným Gpio_Port.h a Gpio_Types.h, s malou náhradní implementací, aby bylo možné API vyzkoušet na PC.

Celé rozhraní na jedné obrazovce​

gpio_ModuleVersion_t Gpio_Get_ModuleVersion  ( void );

gpio_RequestState_t  Gpio_Init               ( gpio_Config_t *gpioConfig );
void                 Gpio_Deinit             ( void );
void                 Gpio_Task               ( void );

gpio_RequestState_t  Gpio_Set_PortActive     ( gpio_PortId_t portId );
gpio_RequestState_t  Gpio_Set_PinMode        ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinMode_t pinType );
gpio_RequestState_t  Gpio_Get_PinMode        ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinMode_t * const pinType );
/* ... speed, output type, alternate function and pull in the same pairs ... */

gpio_RequestState_t  Gpio_Toggle_PinLevel    ( gpio_PortId_t portId, gpio_PinId_t pinId );
gpio_RequestState_t  Gpio_Set_PinLevel       ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinLevel_t pinLevel );
gpio_RequestState_t  Gpio_Get_PinLevel       ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinLevel_t * const pinLevel );

gpio_RequestState_t  Gpio_Set_PinStateActive   ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinLevel_t pinActiveLevel );
gpio_RequestState_t  Gpio_Set_PinStateInactive ( gpio_PortId_t portId, gpio_PinId_t pinId, gpio_PinLevel_t pinActiveLevel );

Každé rozhodnutí níže se dá vyčíst z tohoto seznamu.

1. Pin je dvojice identifikátorů, ne makro od výrobce​

Ovladače výrobce adresují pin ukazatelem na blok registrů a bitovou maskou: LL_GPIO_SetOutputPin(GPIOA, LL_GPIO_PIN_5). MCAL místo toho bere dva výčtové typy, gpio_PortId_t a gpio_PinId_t:

Gpio_Set_PinLevel( GPIO_PORT_A, GPIO_PIN_ID_5, GPIO_PIN_LEVEL_HIGH );

Proč: kód nad MCAL nepotřebuje žádnou hlavičku výrobce, neví, co je GPIOA (adresa bloku registrů výrobce), a identifikátor lze kontrolovat na rozsah, což u libovolného ukazatele nejde. Každý výčet končí čítačem (GPIO_PORT_CNT, GPIO_PIN_ID_CNT), který je horní mezí pro kontrolu na začátku funkce.

Cena: tabulka, která překládá identifikátor na blok registrů (v Gpio.c, jeden řádek na port), a jedna nepřímost navíc. Tabulka také řeší vlastní problém: MCU jedné rodiny mají různý počet portů, takže jsou položky obaleny v #if defined(GPIOK) (viz článek o rodinách).

2. Každá funkce, která může selhat, vrací stav, a výsledky vycházejí přes ukazatel​

Všechny funkce kromě Deinit, Task a getteru verze vracejí gpio_RequestState_t a gettery předávají hodnotu přes parametr typu ukazatel:

gpio_PinLevel_t level = GPIO_PIN_LEVEL_LOW;

if (GPIO_REQUEST_OK == Gpio_Get_PinLevel(GPIO_PORT_C, GPIO_PIN_ID_13, &level))
{
    /* level is valid here */
}

Proč: návratová hodnota getteru nemůže nést hodnotu a zároveň informaci, že hodnota není platná (GPIO_PIN_LEVEL_LOW je platná úroveň, takže vrácená 0 je nejednoznačná). Se stavem v návratové hodnotě a daty v parametru je neplatný port, neplatný pin nebo ukazatel NULL viditelnou chybou, a ne tiše špatnou úrovní. * const v signatuře říká, že funkce nemění ukazatel, jen data za ním.

Cena: dva řádky místo jednoho při každém použití. A stav má dvě hodnoty (GPIO_REQUEST_OK, GPIO_REQUEST_ERROR), takže volající ví, že to selhalo, ale ne proč. Pro GPIO to stačí, protože důvodů je jen několik (neplatný identifikátor, NULL) a všechny jsou programátorské chyby. U periferie se skutečným selháním (timeout I2C, chyba sběrnice) volající potřebuje víc a obvyklou odpovědí je bohatší výčet.

Pravidlo z článku o MISRA, které tu platí, je 17.7 (vrácená hodnota se používá): rozhraní zde usnadňuje jeho dodržení, protože každá funkce, která může selhat, to říká hodnotou, na kterou se musíte podívat.

3. Pin se konfiguruje daty, ne posloupností volání​

Existuje konfigurační struktura se vším, co pin popisuje, a jedna funkce, která ji aplikuje:

typedef struct
{
    gpio_PortId_t        PortId;         /**< GPIO port identification       */
    gpio_PinId_t         PinId;          /**< GPIO pin identification        */
    gpio_PinMode_t       PinMode;        /**< GPIO pin type                  */
    gpio_PinPullCfg_t    PinPull;        /**< GPIO pin pull configuration    */
    gpio_PinSpeed_t      PinSpeed;       /**< GPIO output speed              */
    gpio_PinOutputType_t PinOutType;     /**< GPIO output style              */
    gpio_AltFunction_t   PinAltFunction; /**< Alternate function used by pin */
    gpio_PinLevel_t      PinActiveLevel; /**< Pin level in active state      */
}   gpio_Config_t;

Proč: znalost o desce pak žije v tabulce a kód, který ji aplikuje, je pro každou desku stejný. Podívejte se na příklad, který jsem přeložil a spustil: deska jsou dvě položky a inicializace je smyčka.

#include <stdbool.h>
#include "Gpio_Port.h"

/* The board is data: which pin is what, and what "active" means for it. */
typedef enum { BOARD_IO_LED, BOARD_IO_BUTTON, BOARD_IO_CNT } boardIo_t;

static gpio_Config_t boardPins[BOARD_IO_CNT] =
{
    [BOARD_IO_LED] =
    {
        .PortId = GPIO_PORT_A, .PinId = GPIO_PIN_ID_5, .PinMode = GPIO_PIN_MODE_OUTPUT,
        .PinPull = GPIO_PIN_PULL_NONE, .PinSpeed = GPIO_PIN_SPEED_LOW,
        .PinOutType = GPIO_PIN_OUTPUT_PUSHPULL, .PinAltFunction = GPIO_ALT_FUNC_CNT,
        .PinActiveLevel = GPIO_PIN_LEVEL_LOW        /* this LED is connected to the supply: low = on */
    },
    [BOARD_IO_BUTTON] =
    {
        .PortId = GPIO_PORT_C, .PinId = GPIO_PIN_ID_13, .PinMode = GPIO_PIN_MODE_INPUT,
        .PinPull = GPIO_PIN_PULL_NONE, .PinSpeed = GPIO_PIN_SPEED_LOW,
        .PinOutType = GPIO_PIN_OUTPUT_PUSHPULL, .PinAltFunction = GPIO_ALT_FUNC_CNT,
        .PinActiveLevel = GPIO_PIN_LEVEL_HIGH
    },
};

bool Board_Init(void)
{
    bool isOk = true;

    for (uint32_t index = 0u; index < (uint32_t)BOARD_IO_CNT; index++)
    {
        if (GPIO_REQUEST_OK != Gpio_Init(&boardPins[index]))
        {
            isOk = false;
        }
    }
    return isOk;
}

bool Board_Set_Led(bool isOn)
{
    const gpio_Config_t *led = &boardPins[BOARD_IO_LED];

    return (GPIO_REQUEST_OK == (isOn
        ? Gpio_Set_PinStateActive  (led->PortId, led->PinId, led->PinActiveLevel)
        : Gpio_Set_PinStateInactive(led->PortId, led->PinId, led->PinActiveLevel)));
}

Protože je tabulka data, nová revize DPS změní řádek v tabulce a nic v kódu. V architektuře Embedbits je to úkol vrstvy HAL: drží tabulky a pomocí MCAL je aplikuje.

Cena: struktura má osm polí a každá položka musí vyplnit všechna (designated initializers to činí čitelným a vynechané pole je nula, což není vždy rozumná hodnota). Proto je užitečným společníkem funkce Get_DefaultConfig, kterou mají některé jiné moduly.

4. Polarita signálu je vlastnost pinu, ne kódu​

Struktura má pole PinActiveLevel a existují funkce Gpio_Set_PinStateActive() a Gpio_Set_PinStateInactive(), které berou polaritu jako parametr. Důvodem je prostý fakt z elektroniky: LED může být připojena na zem (svítí s úrovní high) nebo na napájení (svítí s úrovní low) a signál chip-select bývá obvykle active low. Pokud kód říká Gpio_Set_PinLevel(..., HIGH) pro „LED zapnout“, je to správně pro jednu desku a špatně pro další.

S polaritou v tabulce aplikace řekne „zapnout“ a tabulka řekne, co to znamená. Ve výše uvedeném příkladu je LED připojena na napájení, takže PinActiveLevel je GPIO_PIN_LEVEL_LOW a test potvrzuje, co pin dělá:

after Board_Init():      the pin is high (the LED is off)
after Board_Set_Led(1):  the pin is low  (the LED is on)

5. Výčty jsou konstanty výrobce​

Typy nevymýšlejí vlastní čísla, jsou to čísla ovladače výrobce:

typedef enum
{
    GPIO_PIN_MODE_INPUT     = LL_GPIO_MODE_INPUT,     /**< Select input mode              */
    GPIO_PIN_MODE_OUTPUT    = LL_GPIO_MODE_OUTPUT,    /**< Select output mode             */
    GPIO_PIN_MODE_ALTERNATE = LL_GPIO_MODE_ALTERNATE, /**< Select alternate function mode */
    GPIO_PIN_MODE_ANALOG    = LL_GPIO_MODE_ANALOG     /**< Select analog mode             */
}   gpio_PinMode_t;

Proč: převod z typu MCAL na hodnotu, kterou chce funkce LL, je zdarma: žádný switch, žádná tabulka a žádná možnost udělat v překladu překlep. Hodnoty konstant se mezi rodinami liší a to je skryto v jediném #include portu RAL (Stm32_gpio.h specifický pro rodinu).

Cena: Gpio_Types.h, veřejná hlavička, zahrnuje hlavičku RAL, takže konstanty výrobce prosakují do hlaviček, které uživatelé modulu vidí. Alternativou je typ s vlastními hodnotami a překladová tabulka v souboru .c, což stojí kód a místo pro chybu, ale udrží výrobce mimo veřejné hlavičky. Rozhodnutí je kompromis a je dobré vědět, že jím je.

6. Stejný životní cyklus jako každý jiný modul​

Gpio_Get_ModuleVersion(), Gpio_Init(), Gpio_Deinit() a Gpio_Task() pocházejí ze šablony, kterou začíná každý modul (viz článek o organizaci souborů). Rozdíl je na jednom místě, kde to dává smysl: Gpio_Init() není void, bere konfiguraci pinu. Modul GPIO nezná desku, takže „inicializovat modul“ nemá bez otázky „který pin?“ význam. Jednotný životní cyklus, který se ohne tam, kde to vyžaduje povaha modulu, je lepší než životní cyklus vnucený modulu, kam nepasuje.

7. Pořadí kroků je součástí rozhraní​

Podívejte se na komentář k Gpio_Init():

/**
 * Activates the port clock and configures the pin. Output level (inactive state),
 * output type, speed, pull and alternate function are configured before the pin
 * mode, so an output pin starts directly with its inactive level (no glitch).
 * Configuration stops at the first failed step.
 */

Režim pinu, tedy krok, který skutečně připojí výstupní budič k pádu, je poslední. Kdyby byl režim první, pin by na okamžik budil úroveň, kterou měl výstupní registr po resetu (obvykle low), a pak by skočil na správnou: puls na lince, která může být chip-select, reset jiného čipu nebo gate tranzistoru. Takový glitch není v debuggeru vidět, ale na osciloskopu ano. Je to dobrý příklad pravidla pro návrh API: když na pořadí kroků záleží hardwaru, má pořadí vlastnit funkce, která je provádí, aby ho uživatel nemohl pokazit.

Druhá věta komentáře, „stops at the first failed step“, je také návrhové rozhodnutí: funkce se nepokouší pokračovat po chybě a vrací stav selhavšího kroku.

8. Špatný argument je chyba, kterou volající vidí, ne pád​

Funkce kontrolují své argumenty a odpovědí je stav:

assert(GPIO_REQUEST_ERROR == Gpio_Init(GPIO_NULL_PTR));
assert(GPIO_REQUEST_ERROR == Gpio_Get_PinLevel(GPIO_PORT_CNT, GPIO_PIN_ID_0, &level));
assert(GPIO_REQUEST_ERROR == Gpio_Set_PinLevel(GPIO_PORT_A, GPIO_PIN_ID_CNT, GPIO_PIN_LEVEL_HIGH));

(Je to test mé náhradní implementace, ale skutečný Gpio_Init() dělá totéž pro NULL: celé tělo je uvnitř if( GPIO_NULL_PTR != gpioConfig ).) Konstanty _CNT mají zde druhý úkol: GPIO_PORT_CNT je první hodnota, která není platným portem, takže kontrola je jediné porovnání. Ve firmware není komu ukázat zprávu a assert, který zastaví program, je pro produkční build obvykle špatná odpověď. Lepší je chyba, která jde nahoru k volajícímu, jenž ví, co dělat (a k modulu nad MCAL, který ví, co je kritické).

Na co bych se podíval znovu​

Poctivé review návrhu má vždy seznam a tento má dvě položky, které pocházejí z článku o MISRA:

• Gpio_Init( gpio_Config_t *gpioConfig ) strukturu jen čte, takže parametr by mohl být const gpio_Config_t * (Rule 8.13). Signatura by říkala, že funkce konfiguraci nemění, a tabulka desky by mohla být const a žít ve flash místo v RAM.
• Dvouhodnotový gpio_RequestState_t je ve všech modulech stejný (generuje ho šablona). Je to jednoduché a jednotné rozhodnutí, které je pro GPIO správné, a moduly se skutečnými selháními budou dříve či později potřebovat víc.

Principy ve zkratce​

1. Skrývejte hardware, ne záměr. Uživatel říká který pin a jaká polarita, ne který registr.
2. Dělejte neplatný stav viditelným. Status pro všechno, co může selhat, a výstup jen při úspěchu.
3. Dejte znalost do dat. Deska je tabulka, kterou čte smyčka.
4. Nechte funkci vlastnit pořadí, když na něm hardwaru záleží.
5. Udržujte rozhraní stejné a říkejte poctivě, kde je ohnuté (Init s parametrem) a kde abstrakce prosakuje (konstanty výrobce v typech).

Rozhraní má dva čtenáře: uživatele dneška a správce příštího roku. Rozhodnutí výše jsou psána pro oba a komentáře v hlavičkách jsou důkazem, že někdo myslel na toho druhého.

Tento článek ukazuje, jak vypadá zdokumentovaný modul v mých projektech, jak se generuje a jak z dokumentace udělat součást CI, kterou nelze přeskočit. Příklady vznikly s Doxygen 1.9.8 a Graphviz a výstupy jsou skutečné.

Co dokumentovat a co ne​

Můj coding style o tom má jeden odstavec: komentáře ve stylu Doxygen pro všechny veřejné funkce, typy a makra, v angličtině, krátké a přesné, proč a ne co. Pár příkladů rozdílu:

První sloupec opakuje název funkce, který čtenář už vidí. Druhý sloupec říká to, co čtenář vidět nemůže: jednotku, platný rozsah, kdo vlastní paměť, zda se výstup zapisuje v případě chyby, odkud lze funkci volat, co je třeba udělat předtím. Pro embedded rozhraní je to také místo pro informace, které je nebezpečné hádat: je bezpečné volat to z přerušení, jak dlouho může blokovat, smí být ukazatel NULL.

Modul v souborech platformy​

Šablony EmBi_Platform, z nichž každý modul začíná, mají stejnou dokumentační kostru: hlavičku souboru s \author, \file, \ingroup a \brief a nad každou funkcí blok s \brief, popisem a \return. Šablona konečného automatu přidává \pre pro předpoklady a blok \par Used global variables se seznamem proměnných, které funkce čte (in), zapisuje (out) nebo obojí (in,out), což je překvapivě užitečný druh dokumentace: tok dat funkce na třech řádcích.

Celý modul je v Doxygenu jedna skupina. \ingroup Temperature v každém souboru říká, že soubor patří k modulu, a samotná skupina se definuje jednou, v port souboru:

/**
 * \author Mr.Nobody
 * \file Temperature_Port.h
 * \ingroup Temperature
 * \brief Temperature module public functionality
 *
 * The only header that other modules include.
 */

/**
 * \defgroup Temperature Temperature module
 * \brief Measures the temperature and provides a filtered value.
 *
 * The module has to be initialized by Temperature_Init() and its
 * Temperature_Task() has to be called periodically. The latest filtered value
 * is read by Temperature_Get_Value().
 */

#ifndef TEMPERATURE_TEMPERATURE_PORT_H
#define TEMPERATURE_TEMPERATURE_PORT_H

#ifdef __cplusplus
extern "C" {
#endif

/* ============================== INCLUDES ================================== */
#include "Temperature_Types.h"
/* ========================= EXPORTED FUNCTIONS ============================= */

/**
 * \brief Initializes the module.
 *
 * Clears the filter and marks the value as not valid. The module does not
 * report a value until Temperature_Task() has run at least once.
 *
 * \pre Called once, before the first Temperature_Task().
 */
void Temperature_Init( void );

/**
 * \brief Reads the sensor and updates the filtered value.
 *
 * Shall be called periodically from the main loop or from a scheduler, it
 * takes about the same time on every call.
 *
 * \note Not safe to be called from an interrupt: the function is not reentrant.
 */
void Temperature_Task( void );

/**
 * \brief Provides the latest filtered temperature.
 *
 * \param[out] value Filtered temperature in tenths of a degree Celsius. Must
 *                   not be NULL. It is written only if the function returns
 *                   \ref TEMPERATURE_REQUEST_OK.
 *
 * \return \ref TEMPERATURE_REQUEST_OK if a valid value is available,
 *         \ref TEMPERATURE_REQUEST_ERROR if the task has not run yet.
 */
temperature_RequestState_t Temperature_Get_Value( temperature_Value_t * const value );

#ifdef __cplusplus
}
#endif

#endif /* TEMPERATURE_TEMPERATURE_PORT_H */

Typy mají krátký popis typu a každé hodnoty (komentář /**< ... */ za členem dokumentuje člen na stejném řádku):

/**
 * \author Mr.Nobody
 * \file Temperature_Types.h
 * \ingroup Temperature
 * \brief Temperature module global types definition
 *
 * This file contains the types that are used across the module and are
 * available for other modules through the port file.
 */

#ifndef TEMPERATURE_TEMPERATURE_TYPES_H
#define TEMPERATURE_TEMPERATURE_TYPES_H
/* ============================== INCLUDES ================================== */
#include <stdint.h>
/* ============================== TYPEDEFS ================================== */

/** Temperature in tenths of a degree Celsius, e.g. 253 means 25.3 degC. */
typedef int16_t temperature_Value_t;

/** Enumeration used to signal the result of a request. */
typedef enum
{
    TEMPERATURE_REQUEST_ERROR = 0u, /**< The request failed, the output is not valid */
    TEMPERATURE_REQUEST_OK          /**< The request succeeded                       */
}   temperature_RequestState_t;

#endif /* TEMPERATURE_TEMPERATURE_TYPES_H */

Generování​

Doxygen se konfiguruje souborem s několika sty voleb. Psát ho ručně je chyba, které se snadno vyhnete: platforma má soubor jako šablonu (Doxyfile.in v artefaktu Doxygen) a plní ho z proměnných CMake a projekty nastavují jen ty, které se liší od výchozích. Totéž umožňuje modul samotného CMake a toto je celá konfigurace příkladu:

cmake_minimum_required(VERSION 3.19)
project(DoxDemo C)

find_package(Doxygen REQUIRED dot)

set(DOXYGEN_PROJECT_NAME        "Temperature module")
set(DOXYGEN_OUTPUT_DIRECTORY    ${CMAKE_BINARY_DIR}/docs)
set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
set(DOXYGEN_FULL_PATH_NAMES     NO)
set(DOXYGEN_GENERATE_LATEX      NO)
set(DOXYGEN_QUIET               YES)

# The documentation is a contract: a missing description is an error.
set(DOXYGEN_WARN_IF_UNDOCUMENTED     YES)
set(DOXYGEN_WARN_IF_DOC_ERROR        YES)
set(DOXYGEN_WARN_NO_PARAMDOC         YES)
set(DOXYGEN_WARN_AS_ERROR            FAIL_ON_WARNINGS)

# Graphs (the Graphviz artifact in the platform)
set(DOXYGEN_HAVE_DOT                 YES)
set(DOXYGEN_CALL_GRAPH               YES)
set(DOXYGEN_CALLER_GRAPH             YES)
set(DOXYGEN_DOT_IMAGE_FORMAT         svg)

doxygen_add_docs(docs Temperature COMMENT "Generating the documentation")

a build je jeden target:

cmake -S . -B build -G Ninja
cmake --build build --target docs

Výsledkem je složka s HTML stránkami. Skupina modulu se soubory, které k ní patří, a popisem z port souboru vypadá takto:

Doxygen také kreslí include graph každého souboru a call graph a caller graph každé zdokumentované funkce (HAVE_DOT, Graphviz: proto má platforma pro něj artefakt). Include grafy stojí za občasný pohled: šipka z aplikačního souboru do interní hlavičky modulu je tentýž problém, který popisuje článek o organizaci souborů, jen viděný shora.

Dokumentace jako test​

Tohle je část, která mění disciplínu. Čtyři volby změní chybějící dokumentaci z „měli bychom“ na „build je červený“:

set(DOXYGEN_WARN_IF_UNDOCUMENTED   YES)   # a public member without a description
set(DOXYGEN_WARN_IF_DOC_ERROR      YES)   # a wrong tag, a parameter that does not exist
set(DOXYGEN_WARN_NO_PARAMDOC       YES)   # a function whose parameters are not described
set(DOXYGEN_WARN_AS_ERROR          FAIL_ON_WARNINGS)

S FAIL_ON_WARNINGS Doxygen projde vše, vypíše všechna varování a teprve potom skončí chybou (prosté YES se zastaví u prvního). Vyzkoušel jsem to: z port souboru jsem smazal popis Temperature_Task() a \param u Temperature_Get_Value() a build ohlásil:

Temperature/Temperature_Port.h:40: error: Member Temperature_Task(void) (function) of file Temperature_Port.h is not documented.
Temperature/Temperature_Port.h:45: error: parameters of member Temperature_Get_Value are not documented
ninja: build stopped: subcommand failed.

(Návratový kód příkazu je 1, takže CI je červené.) Po vrácení popisů stejný build skončí bez jakéhokoli výstupu a s návratovým kódem 0. Nová funkce bez komentáře se tak už nemůže omylem dostat do hlavní větve a nikdo nemusí být tím, kdo si to při review pohlídá.

Co obsahuje dobrá dokumentace rozhraní​

U každé funkce veřejného rozhraní projděte seznam:

1. Co dělá, jednou větou, se slovesem (\brief).
2. Parametry: směr ([in], [out], [in,out]), jednotka, rozsah, zda je povoleno NULL.
3. Návratová hodnota: každá hodnota, která může být vrácena, a co znamená.
4. Předpoklady (\pre): co je třeba udělat předtím, například inicializaci.
5. Kontext: lze funkci volat z přerušení, blokuje, jak dlouho trvá.
6. Vedlejší efekty: co dalšího mění (globální stav, periferii).

Pokud funkce nemá odpověď na jednu z těchto otázek, odpověď je v kódu a čtenář si ji musí přečíst. To je znamení, že rozhraní není dokončené, a psaní komentáře je často okamžik, kdy to zjistíte.

Kam to v platformě zapadá​

Každý modul platformy má ve svém CMakeLists.txt volání, které registruje jeho složku pro dokumentaci (když je v projektu dostupný artefakt Doxygen), a kořenový build má volbu DOXYGEN_ENABLED. Dokumentace celého firmwaru se tedy generuje stejným buildem jako firmware: -DDOXYGEN_ENABLED=ON. Artefakty (Doxygen a Graphviz) se stahují ve verzi, kterou má projekt připnutou, takže stránky z dneška a z příštího roku vypadají stejně.

Kontrolní seznam​

1. Každá veřejná funkce, typ a makro má popis. Interní jen tam, kde to není zřejmé.
2. Popis říká to, co čtenář nevidí v signatuře: jednotky, rozsahy, kontext, chyby.
3. Jedna skupina na modul (\defgroup v port souboru, \ingroup v ostatních).
4. WARN_IF_UNDOCUMENTED, WARN_NO_PARAMDOC a FAIL_ON_WARNINGS v CI.
5. Grafy jsou zapnuté a někdo se čas od času podívá na include graph aplikace.
6. Dokumentace se generuje ze stejného buildu jako firmware, s připnutými nástroji.

Build systém platformy Embedbits (EmBi_Platform) je postaven na CMake a tento článek vysvětluje části, které potřebuje každý embedded build v CMake, na malém projektu, který jsem sestavil a spustil: toolchain file, pojmenované flagy, typy buildu, moduly jako knihovny, linker script, soubory po linkování a test, který spouští firmware v simulátoru. Všechna čísla a výstupy jsou skutečné.

Dvě vrstvy: projekt a platforma​

Platforma dělí build na dvě části a tento nápad stojí za okopírování i pro malý projekt. Kořenový CMakeLists.txt produktu je minimální vstupní bod a vše složité žije v samostatném skriptu, který je verzovaný a sdílený (Git submodul) a který kořen vkládá:

include(${CMAKE_CURRENT_LIST_DIR}/CMake/Build.cmake)

Skript platformy zná typy buildu (Debug, Release, UnitTest, IntegrationTest), kontroly parametrů, toolchain, include cesty a registraci modulů. Produkt doplní jen to, co je pro něj specifické. Oprava buildu je pak nová verze submodulu a ne úprava deseti produktů. Příklad níže má obě části v jednom projektu, aby byl krátký, ale zachovává stejné oddělení: cmake/ je „platforma“ a CMakeLists.txt je „produkt“.

Ukázkový projekt​

cmake/
  arm-none-eabi.cmake       toolchain file
  Flags.cmake               flags with names
Bsp/Startup/                startup code and the linker script (see the article about main())
Middlewares/Temperature/    a module as a library (see the article about file organization)
Application/                main.c
CMakeLists.txt

Toolchain file: kompilátor není PC​

CMake předpokládá, že sestavujete pro počítač, u kterého sedíte. Toolchain file říká něco jiného:

# Toolchain file: tells CMake that the target is a bare-metal ARM and not the PC.
set(CMAKE_SYSTEM_NAME      Generic)
set(CMAKE_SYSTEM_PROCESSOR arm)

set(CMAKE_C_COMPILER   arm-none-eabi-gcc)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)
set(CMAKE_OBJCOPY      arm-none-eabi-objcopy)
set(CMAKE_SIZE         arm-none-eabi-size)

# The compiler cannot link a PC executable: the check of the compiler builds a static library only.
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

# Search for programs on the PC, for libraries and headers only in the toolchain.
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

Řádek, na který lidé zapomínají, je CMAKE_TRY_COMPILE_TARGET_TYPE. CMake na začátku sestaví testovací program, aby ověřil, že kompilátor funguje, a bare-metal kompilátor nedokáže slinkovat program pro PC (neexistuje operační systém ani main, který by někdo volal). Když je cílem kontroly statická knihovna, test projde. Toolchain se zadává na příkazové řádce, jednou, při vytvoření složky buildu:

cmake -S . -B build-debug -G Ninja \
      -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug

Stejná složka se zdrojáky s jiným -B je jiný build: vedle ní build-release nebo build pro unit testy na PC, bez toolchain file.

Pojmenované flagy​

Řádek jako -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -ffunction-sections ... se špatně revidují, protože nikdo neví, která jeho část je důležitá. Platforma má soubor Flags.cmake s proměnnou pro každý flag a s komentářem (THUMB_MODE, ENABLE_ALL_WARNINGS, REMOVE_UNUSED_FUNCTIONS, ENABLE_GC_SECTIONS, PRINT_MEMORY_USAGE a tak dále, plus varianty CPU a FPU od Cortex-M0 po M85). Projekt se pak čte jako věta. Ten můj má jen to, co příklad potřebuje:

# Flags with names, so the CMakeLists.txt reads like a sentence.
set(MCU_FLAGS             -mcpu=cortex-m4 -mthumb -mfloat-abi=soft)
set(WARNING_FLAGS         -Wall -Wextra -Wshadow -Wconversion)
set(SECTION_FLAGS         -ffunction-sections -fdata-sections)       # one section per function and variable...
set(GC_FLAGS              -Wl,--gc-sections)                          # ...so the linker can drop the unused ones
set(STARTUP_LINK_FLAGS    -nostartfiles)

set(DEBUG_OPTIONS         -Og -g3)
set(RELEASE_OPTIONS       -Os -g0)

CMakeLists.txt​

Celý kořenový soubor příkladu, 80 řádků:

cmake_minimum_required(VERSION 3.19)

# The toolchain file has to be given before project(), see the command line.
project(CmakeDemo C)
enable_testing()

option(GC_SECTIONS "Let the linker remove the unused functions and data" ON)

include(cmake/Flags.cmake)

# CMake adds its own flags to every configuration (-O3 -DNDEBUG for Release, -g for Debug).
# The flags of the project are in Flags.cmake, so the defaults are cleared.
set(CMAKE_C_FLAGS_DEBUG   "")
set(CMAKE_C_FLAGS_RELEASE "")

# ---- build type: flags of the configuration ----
if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Debug)
endif()
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    set(BUILD_OPTIONS ${DEBUG_OPTIONS})
elseif(CMAKE_BUILD_TYPE STREQUAL "Release")
    set(BUILD_OPTIONS ${RELEASE_OPTIONS})
else()
    message(FATAL_ERROR "Unknown build type '${CMAKE_BUILD_TYPE}', use Debug or Release")
endif()

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# ---- flags for everything that is built here ----
add_compile_options(${MCU_FLAGS} ${WARNING_FLAGS} ${BUILD_OPTIONS})
if(GC_SECTIONS)
    add_compile_options(${SECTION_FLAGS})
endif()
add_link_options(${MCU_FLAGS})

# ---- modules ----
add_subdirectory(Middlewares/Temperature)

# The startup code is an OBJECT library: its objects always end up in the executable,
# without relying on the linker to pull them out of an archive.
add_library(Startup OBJECT Bsp/Startup/startup.c)
# GCC may turn the copy and zero loops of the startup code into calls of memcpy() and memset()
target_compile_options(Startup PRIVATE -fno-tree-loop-distribute-patterns)

# ---- the firmware ----
set(LINKER_SCRIPT ${CMAKE_SOURCE_DIR}/Bsp/Startup/link.ld)

add_executable(firmware.elf Application/main.c Application/Unused.c $<TARGET_OBJECTS:Startup>)
target_link_libraries(firmware.elf PRIVATE Temperature_Lib)
target_link_options(firmware.elf PRIVATE
    ${STARTUP_LINK_FLAGS}
    -T ${LINKER_SCRIPT}
    -Wl,-Map=firmware.map
    -Wl,--print-memory-usage
    -Wl,--no-warn-rwx-segments
)
if(GC_SECTIONS)
    target_link_options(firmware.elf PRIVATE ${GC_FLAGS})
endif()
set_target_properties(firmware.elf PROPERTIES LINK_DEPENDS ${LINKER_SCRIPT})

# ---- after the link: the files that you flash and a size report ----
add_custom_command(TARGET firmware.elf POST_BUILD
    COMMAND ${CMAKE_OBJCOPY} -O binary firmware.elf firmware.bin
    COMMAND ${CMAKE_OBJCOPY} -O ihex   firmware.elf firmware.hex
    COMMAND ${CMAKE_SIZE} firmware.elf
    COMMENT "Creating firmware.bin, firmware.hex and the size report"
)

# ---- run it in the simulator as a test ----
find_program(QEMU qemu-system-arm)
if(QEMU)
    add_test(NAME firmware_runs_in_qemu
        COMMAND ${QEMU} -M netduinoplus2 -nographic -semihosting-config enable=on,target=native -kernel firmware.elf)
    set_tests_properties(firmware_runs_in_qemu PROPERTIES
        PASS_REGULAR_EXPRESSION "temperature module works" TIMEOUT 10)
endif()

Vysvětlím několik řádků, které rozhodují o tom, zda bude firmware správný.

Typy buildu s explicitními flagy. Jsou jen dva, Debug (-Og -g3: dost rychlý a laditelný) a Release (-Os -g0: malý a bez ladicích informací) a cokoli jiného zastaví konfiguraci chybovou hláškou. Platforma má další dva, UnitTest a IntegrationTest: u prvního se TARGET_MCU ani nepotřebuje, protože se sestavuje pro PC.

Výchozí flagy CMake. To je past. CMake přidává ke každé konfiguraci vlastní flagy, -O3 -DNDEBUG pro Release a -g pro Debug, a to před vaše vlastní. V první verzi příkladu vypadal příkaz kompilace pro release takto:

-O3 -DNDEBUG -std=gnu11 -mcpu=cortex-m4 ... -Os -g0 -ffunction-sections ...

Vyhrává poslední -O, takže to bylo -Os, ale -DNDEBUG (které vypíná assert()) tam bylo, i když jsem o ně nikdy nežádal. Pokud chcete vědět, co sestavujete, vymažte výchozí hodnoty (set(CMAKE_C_FLAGS_RELEASE "")) a vše napište do vlastního souboru. Jak zjistit, co se skutečně předává kompilátoru, ukazuje compile_commands.json, který vytvoří volba CMAKE_EXPORT_COMPILE_COMMANDS: je to také soubor, který čtou editory a clang-tidy.

Startup kód je knihovna typu OBJECT. Objekty takové knihovny se vkládají přímo do spustitelného souboru, bez spoléhání na to, že je linker vytáhne z archivu.

Linker script je závislost (LINK_DEPENDS): když se změní, firmware se slinkuje znovu.

Moduly jsou knihovny​

Každý modul je statická knihovna se seznamem vlastních zdrojových souborů a veřejných hlaviček (článek o organizaci souborů vysvětluje proč). Aplikace knihovnu linkuje a získá s ní include cestu k veřejným hlavičkám a nic víc. V souboru CMake modulu není žádné file(GLOB ...): zdrojové soubory jsou vyjmenovány jeden po druhém, takže nový soubor je viditelná změna v pull requestu a soubor, který ve složce omylem zůstal, se do firmwaru nedostane.

TARGET_MCU: jedno jméno, několik definic​

Buildy platformy se spouštějí s -DTARGET_MCU=STM32G474xE. Skript jméno rozebere regulárním výrazem a z jednoho parametru vytvoří definice pro kód (STM32G474xx a STM32G4xx), které hlavičky výrobce používají k výběru správného zařízení. Stejná logika, spuštěná na čtyřech jménech:

STM32G474xE  ->  MCU_ID STM32G474xx, MCU_FAMILY_ID STM32G4xx
STM32U5A5xx  ->  MCU_ID STM32U5A5xx, MCU_FAMILY_ID STM32U5xx
STM32F407VG  ->  MCU_ID STM32F407xx, MCU_FAMILY_ID STM32F4xx
STM32H563ZI  ->  MCU_ID STM32H563xx, MCU_FAMILY_ID STM32H5xx

To je odkaz na článek o rodinách STM32 a větvích: rodina rozhoduje, která větev BSP je ve stromu, a jméno MCU rozhoduje o definicích a linker scriptu.

Co vám řekne linker​

-Wl,--print-memory-usage na konci každého linkování vypíše, kolik z každé paměti je využito, -Wl,-Map=firmware.map zapíše adresu všeho a post-build krok vypíše velikost:

Memory region         Used Size  Region Size  %age Used
           FLASH:         276 B         1 MB      0.03%
             RAM:           8 B       128 KB      0.01%
   text	   data	    bss	    dec	    hex	filename
    276	      0	      8	    284	    11c	firmware.elf

Dva experimenty, které jsem s těmito čísly provedl, ukazují, proč jsou flagy v buildu a ne v něčí hlavě.

Linker umí zahodit to, co nikdo nevolá. S -ffunction-sections -fdata-sections je každá funkce ve vlastní sekci a -Wl,--gc-sections dovolí linkeru odstranit ty, na které nikdo neodkazuje. Příklad obsahuje funkci Unused_Checksum(), kterou nikdo nevolá:

Rozdíl 48 bajtů je přesně funkce checksum. V reálném projektu s knihovnou výrobce, která má stovky funkcí, z nichž voláte deset, jsou rozdíly v kilobajtech.

Kompilátor umí přidat paměť za vašimi zády. První release build příkladu měl 772 B, téměř třikrát víc než debug build (288 B). Map soubor ukázal memcpy a memset ze standardní knihovny. Příčina: při zapnuté optimalizaci GCC rozpozná smyčky ve startup kódu (kopírování .data a nulování .bss) jako kopii a výplň a nahradí je voláním těchto dvou funkcí, které pak přinesou svůj kód z knihovny. Jeden flag na startup objektu to opraví a výsledek je 276 B:

target_compile_options(Startup PRIVATE -fno-tree-loop-distribute-patterns)

Kromě velikosti je tu druhý důvod, proč na tom záleží: startup kód běží před inicializací paměti a čím méně knihovního kódu používá, tím méně se může pokazit (viz článek o tom, co se děje před main()).

Po linkování: co nahrajete a co otestujete​

Příkaz POST_BUILD vytvoří z ELF souboru firmware.bin a firmware.hex (formáty, které čtou programátory) a vypíše velikost. Poslední částí příkladu je test: add_test spustí firmware v QEMU a ctest zkontroluje, že vypsal očekávaný text:

ctest --test-dir build-debug

1/1 Test #1: firmware_runs_in_qemu ............   Passed    0.05 sec

100% tests passed, 0 tests failed out of 1

Je to smoke test (nastartuje firmware a dojde do svého main()?) a běží zlomek vteřiny při každém commitu. Nenahrazuje test na hardwaru, ale build, který nenastartuje, se najde v CI a ne u stolu. Testy modulů na PC jsou jiný build téhož projektu CMake (ukazuje ho článek o Unity a CMock).

Kontrolní seznam​

1. Toolchain file a CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY.
2. Flagy v jednom souboru s názvy, výchozí hodnoty CMake pro konfigurace vymazané.
3. Každý modul je knihovna s explicitním seznamem zdrojů a veřejných hlaviček.
4. -ffunction-sections -fdata-sections a --gc-sections, vždy.
5. --print-memory-usage a map soubor při každém linkování, size po něm.
6. compile_commands.json pro editor a statickou analýzu.
7. Linker script je závislost firmwaru.
8. Smoke test v simulátoru v CI.
9. Čas od času se podívejte na velikost release buildu. Pokud roste bez důvodu, map soubor ví proč.

Tento článek prochází tři problémy sdílených dat, jeden po druhém, s kódem, který selhává, a potom ukazuje vzory, které fungují. Experimenty běží na Cortex-M4 (v QEMU, na modelu desky s STM32F4) nebo na PC a výstupy jsou skutečné.

Problém 1: překladač přerušení nevidí​

Nejjednodušší komunikace mezi přerušením a hlavní smyčkou je příznak (flag). Přerušení ho nastaví, hlavní smyčka na něj čeká:

#ifdef USE_VOLATILE
static volatile bool dataReady;
#else
static bool dataReady;
#endif

void SysTick_Handler(void)
{
    dataReady = true;
}

int main(void)
{
    SysTick_Start(1000u);

    while (!dataReady)
    {
        /* waiting for the interrupt */
    }

    Print("the interrupt was seen\n");
    Quit();
    return 0;
}

To je celý program a s optimalizací -O2 nikdy neskončí. Spustil jsem ho v QEMU s SysTick jako zdrojem přerušení (přerušení se spustí a nastaví příznak) a porovnal verzi s volatile a bez něj:

--- without volatile
(no output, the program was killed by the timeout after 5 s)
--- with volatile
the interrupt was seen

Proč? Podívejte se, co překladač vygeneroval pro smyčku v první verzi:

 8000062:  ldrb  r3, [r1, #0]       @ read the flag once
 8000064:  cbnz  r3, 8000068        @ non-zero: leave the loop
 8000066:  b.n   8000066            @ zero: jump to itself, forever

Překladač uvažuje jen o kódu main() a v tom kódu do dataReady nikdo nezapisuje. Hodnota se tedy nemůže změnit, stačí ji přečíst jednou a smyčka se stane nekonečnou. Přesně to, oč jste z jeho pohledu požádali. S volatile musí překladač číst proměnnou z paměti při každém průchodu:

 8000062:  ldrb  r3, [r2, #0]       @ read the flag in every pass
 8000064:  cmp   r3, #0
 8000066:  beq.n 8000062

Poučení: každá proměnná sdílená mezi přerušením a hlavním kódem musí být volatile. Totéž platí pro každý registr periferie, což je důvod, proč jsou definice registrů v hlavičkách CMSIS volatile. Mějte na paměti, že bez toho to v debug buildu (-O0) funguje a v release buildu selže, a proto se chyba najde pozdě.

Problém 2: volatile nezaručuje atomicitu​

volatile říká „čti a zapisuj paměť pokaždé“. Neříká „všechno najednou“. Nevinný řádek counter++ jsou tři instrukce:

Increment_Plain:
   ldr   r2, [pc, #8]       @ address of the counter
   ldr   r3, [r2, #0]       @ 1. load the value
   adds  r3, #1             @ 2. add one
   str   r3, [r2, #0]       @ 3. store it back

Pokud přerušení přijde mezi načtením a uložením a přerušení také inkrementuje čítač, jedna ze dvou inkrementací se ztratí: hlavní kód uloží starou hodnotu plus jedna přes hodnotu, kterou právě uložilo přerušení. Časová osa:

Chtěl jsem to ukázat i na Cortex-M4 a nevyšlo to: ve 200 000 inkrementacích s přerušením každých pár instrukcí QEMU nic neztratilo. Pravděpodobně proto, že QEMU kontroluje přerušení mezi bloky přeloženého kódu, takže žádné nikdy nepřistane mezi ldr a str. Je to užitečná připomínka, že simulátor neprokazuje nepřítomnost race condition: skutečné MCU může přerušit po každé instrukci. Stejný race, na místě, kde se snadno reprodukuje, jsou dvě vlákna na PC:

#include <pthread.h>
#include <stdint.h>
#include <stdio.h>

#define INCREMENTS  ( 2000000u )

static volatile uint32_t plainCounter;
static _Atomic uint32_t  atomicCounter;

static void *Worker(void *argument)
{
    (void)argument;
    for (uint32_t index = 0u; index < INCREMENTS; index++)
    {
        plainCounter++;                       /* load, add, store: not atomic */
        atomic_fetch_add(&atomicCounter, 1u); /* one indivisible operation    */
    }
    return NULL;
}

int main(void)
{
    pthread_t first, second;

    pthread_create(&first, NULL, Worker, NULL);
    pthread_create(&second, NULL, Worker, NULL);
    pthread_join(first, NULL);
    pthread_join(second, NULL);

    printf("expected        %u\n", 2u * INCREMENTS);
    printf("plain counter   %u (lost %u)\n", plainCounter, 2u * INCREMENTS - plainCounter);
    printf("atomic counter  %u (lost %u)\n", atomicCounter, 2u * INCREMENTS - atomicCounter);
    return 0;
}

expected        4000000
plain counter   2652421 (lost 1347579)
atomic counter  4000000 (lost 0)

Třetina všech inkrementací se ztratí a výsledky se běh od běhu liší. Vlákno na PC a přerušení na MCU jsou v tomto ohledu totéž: druhý tok řízení, který může udeřit mezi dvěma instrukcemi. Totéž platí pro všechno, co je větší než slovo CPU: 64bitové časové razítko nebo struktura se dvěma poli se může přečíst napůl staré a napůl nové (torn read).

Tři způsoby řešení​

1. Jeden zapisovatel pro každou proměnnou (nejlepší)​

Nejrobustnější řešení je navrhnout data tak, aby každou proměnnou zapisovala jen jedna strana. Přerušení zapisuje příznak, hlavní kód ho jen čte a nemaže (nebo naopak). Bez dvou zapisovatelů není co ztratit. Pokud obě strany potřebují měnit tutéž věc, neměly by ji sdílet: každá má vlastní proměnnou (čítač přerušení je isrCalls, čítač hlavního kódu je jiný) a součet vytvoří čtenář.

2. Kritická sekce​

Když se dvěma zapisovatelům nelze vyhnout, přerušení se na dobu operace zakážou. Správný způsob je uložit stav a obnovit ho, a ne na konci slepě přerušení povolit, protože funkce mohla být zavolána s již zakázanými přerušeními:

Increment_CriticalSection:
   mrs   r1, PRIMASK        @ save the state of the mask
   cpsid i                  @ disable the interrupts
   ldr   r3, [r2, #0]
   adds  r3, #1
   str   r3, [r2, #0]
   msr   PRIMASK, r1        @ restore the state, as it was

Cenou je latence: během sekce nemůže běžet žádné přerušení. Sekce proto musí být krátká jako pár instrukcí a bez volání funkce, smyčky nebo čekání uvnitř.

3. Atomická operace​

Pro jediné slovo (čítač, příznak s počtem) má procesor instrukce LDREX a STREX: uložení uspěje, jen pokud se adresy od načtení nic nedotklo, a když ne, smyčka se opakuje. Překladač je za vás vygeneruje ze standardní operace:

Increment_Atomic:
   ldrex r1, [r3]           @ load and mark the address
   adds  r1, #1
   strex r2, r1, [r3]       @ store only if nobody has touched it, r2 = 0 on success
   cmp   r2, #0
   bne.n Increment_Atomic   @ somebody did: try again

v C je to jeden řádek, __atomic_fetch_add(&counter, 1u, __ATOMIC_RELAXED) (nebo atomic_fetch_add() z <stdatomic.h>). Nezakazuje přerušení, takže nepřidává latenci. Funguje pro jedinou proměnnou; pro dvě proměnné, které patří k sobě, nepomůže.

Nejpoužívanější vzor: kruhový buffer​

Nejčastější věc, kterou přerušení předává hlavnímu kódu, je proud dat: bajty přijaté UARTem, vzorky ADC. Přerušení je nemůže zpracovat (musí být krátké), a tak je vloží do fronty a hlavní kód je vybere v klidné chvíli. Je to problém producent-konzument s jedním producentem (přerušení) a jedním konzumentem (hlavní kód) a právě pro tento případ kruhový buffer nepotřebuje žádný zámek:

#ifndef RING_H
#define RING_H

#include <stdatomic.h>
#include <stdbool.h>
#include <stdint.h>

#define RING_SIZE  ( 16u )                       /* has to be a power of two */
#define RING_MASK  ( RING_SIZE - 1u )

/*
 * Single producer, single consumer ring buffer without any lock.
 * head: written only by the producer, tail: written only by the consumer.
 * Both are free-running counters, the difference is the number of items.
 */
typedef struct
{
    uint32_t         items[RING_SIZE];
    atomic_uint_fast32_t head;
    atomic_uint_fast32_t tail;
}   ring_t;

static inline bool Ring_Push(ring_t *ring, uint32_t item)
{
    const uint_fast32_t head = atomic_load_explicit(&ring->head, memory_order_relaxed);
    const uint_fast32_t tail = atomic_load_explicit(&ring->tail, memory_order_acquire);

    if (RING_SIZE == (head - tail))
    {
        return false;                            /* full, the producer decides what to do */
    }

    ring->items[head & RING_MASK] = item;
    atomic_store_explicit(&ring->head, head + 1u, memory_order_release);   /* publish the item */
    return true;
}

static inline bool Ring_Pop(ring_t *ring, uint32_t *item)
{
    const uint_fast32_t tail = atomic_load_explicit(&ring->tail, memory_order_relaxed);
    const uint_fast32_t head = atomic_load_explicit(&ring->head, memory_order_acquire);

    if (head == tail)
    {
        return false;                            /* empty */
    }

    *item = ring->items[tail & RING_MASK];
    atomic_store_explicit(&ring->tail, tail + 1u, memory_order_release);   /* free the slot */
    return true;
}

#endif

Proč je správný?

• head zapisuje jen producent a tail jen konzument. Neexistuje proměnná se dvěma zapisovateli, takže se nemůže ztratit žádná aktualizace: je to první řešení výše, zabudované do struktury.
• Čítače jsou volně běžící (nikdy se neresetují). Počet položek je head - tail a díky aritmetice bez znaménka je správný i po přetečení čítačů. Při velikosti, která je mocninou dvou, je pozice jednoduchá maska místo dělení.
• Záleží na pořadí: producent zapíše položku a teprve potom ji zveřejní posunutím head (memory_order_release) a konzument čte nejprve head (memory_order_acquire) a až potom položku. Na jednom jádru Cortex-M záleží jen na pořadí, v jakém překladač zapisuje, a atomiky ho zachovávají. Na MCU se dvěma jádry (některé STM32H7 mají dvě) nebo s cache je stejný kód stále správný, a to je důvod, proč ho psát v této podobě a ne s volatile, které náhodou funguje.
• Producent nečeká. Plný buffer znamená „zahoď položku a započítej to“, protože přerušení nemůže na nikoho čekat. Čítač zahozených položek vám v testu řekne, že buffer je příliš malý.

Otestoval jsem ho dvěma způsoby. Na PC se dvěma vlákny, producentem a konzumentem, projde 20 milionů položek bufferem o 16 slotech:

items 20000000, order errors 0

a na Cortex-M4 v QEMU: přerušení SysTick je producent a main() konzument, s 5000 položkami:

items received  5000
order errors    0
full buffer hits 0

První test je těžší (obě vlákna skutečně běží paralelně na dvou jádrech), druhý je skutečná situace MCU. Je to také ideální kandidát na unit test na PC, jako v článku o unit testování s Unity a CMock: modul je nezávislý na hardwaru.

Pravidla pro obsluhu přerušení​

1. Krátká. Přečíst registr, uložit data, nastavit příznak, vymazat pending flag, vrátit se. Zpracování se dělá v hlavním kódu.
2. Žádné čekání, žádná alokace, žádný printf. Nic, co blokuje, trvá dlouho nebo volá funkci, která není bezpečná pro volání z přerušení (je non-reentrant, pokud uvnitř používá statický buffer).
3. Vše sdílené je volatile nebo atomické a každá proměnná má definovaného zapisovatele.
4. Nesdílejte víc, než musíte. Příznak nebo fronta mezi stranami, ne struktura o deseti polích.
5. Myslete na prioritu. Přerušení s vyšší prioritou může přerušit jiné přerušení. Proměnná sdílená mezi dvěma přerušeními má stejný problém jako ta sdílená s hlavním kódem.

V BSP Embedbits mají periferní moduly (např. USART) variantu zpracování dat s pollingem, s přerušením a s DMA a varianta s přerušením je přesně tohle: handler na úrovni MCAL, který vezme data z periferie a předá je aplikaci přes buffer, zatímco Task modulu běží v hlavní smyčce a provádí zpracování.

Shrnutí​

Tři druhy kódu v tomto článku měly jedno společné: všechny vypadaly správně.

Tlačítko vypadá triviálně: pin, high nebo low. Jenže mechanický kontakt zakmitává, takže pin udělá 1 0 1 1 0 1, než se ustálí, a produkt obvykle chce od stejného tlačítka dvě různé věci: krátký a dlouhý stisk. Napsané pomocí příznaků a čítačů v hlavní smyčce to skončí jako pár ifů, které na sobě závisejí způsobem, který po měsíci nikdo nevysvětlí. Konečný automat to vyřeší tak, že to vysvětlíte tabulkou.

Šablona v jednom odstavci​

Každý stav má čtyři rutiny a každá z nich má právě jeden úkol:

Jádro automatu spouští Execute a CheckLeave aktuálního stavu a když se stav změnil, spustí Leave starého a Entry nového. Rutiny se nikdy nevolají navzájem a kód automatu neobsahuje nic jiného než automat. Pokud chcete vědět, proč je zařízení v nějakém stavu, přečtete si CheckLeave předchozího.

Nejdřív návrh: stavy a přechody​

Úloha běží každých 10 ms a čte surový kontakt. Doba debounce je 50 ms a hranice dlouhého stisku je 1 sekunda. Stačí pět stavů:

Skutečná práce je napsat tabulku. Když je úplná, kód je jen cvičení v psaní. Když není (co se stane ve stavu LONG_PRESS, když kontakt při uvolnění zakmitne?), tabulka ukáže díru dřív, než napíšete řádek C.

Kód​

Vstup přichází z BSP, takže modul nemá žádnou závislost na hardwaru a dá se testovat na PC (stejné švy jako v článku o unit testování). Port modulu tvoří Init, Task a funkce, která vrátí událost jednou:

#ifndef BUTTON_BUTTON_PORT_H
#define BUTTON_BUTTON_PORT_H

typedef enum
{
    BUTTON_EVENT_NONE = 0u,
    BUTTON_EVENT_SHORT_PRESS,
    BUTTON_EVENT_LONG_PRESS
}   button_Event_t;

void           Button_Init(void);
void           Button_Task(void);          /* call it every 10 ms */
button_Event_t Button_Get_Event(void);     /* returns the event once and clears it */

#endif

Typy sledují šablonu. Jednu změnu jsem udělal záměrně: tabulka rutin je indexovaná stavem a nehledá se v ní, a výčet končí hodnotou BUTTON_STATE_COUNT, která má dvojí využití.

typedef enum
{
    BUTTON_STATE_RELEASED = 0u,    /**< Contact open, waiting for a press      */
    BUTTON_STATE_DEBOUNCE_PRESS,   /**< Contact closed, is it stable?          */
    BUTTON_STATE_PRESSED,          /**< Stable press, short or long?           */
    BUTTON_STATE_LONG_PRESS,       /**< Held longer than the limit             */
    BUTTON_STATE_DEBOUNCE_RELEASE, /**< Contact open again, is it stable?      */
    BUTTON_STATE_COUNT             /**< Number of the states, keep it the last */
}   button_SM_States_t;

typedef void (*button_SM_PtrToRoutine_t)(void);

typedef struct
{
    button_SM_PtrToRoutine_t entry;
    button_SM_PtrToRoutine_t execute;
    button_SM_PtrToRoutine_t checkLeave;
    button_SM_PtrToRoutine_t leave;
}   button_SM_Routines_t;

První využití je samotná tabulka. S designated initializers nezáleží na pozici řádku, takže stav nelze propojit se špatnými rutinami, když někdo přidá řádek doprostřed (šablona potřebuje komentář „toto pole musí mít stejné pořadí jako výčet stavů“):

/* The table is indexed by the state, so the order of the lines does not matter. */
static const button_SM_Routines_t stateRoutines[BUTTON_STATE_COUNT] =
{
    [BUTTON_STATE_RELEASED]         = { Button_Released_Entry,        Button_Released_Execute,
                                        Button_Released_CheckLeave,   Button_Released_Leave        },
    [BUTTON_STATE_DEBOUNCE_PRESS]   = { Button_DebouncePress_Entry,   Button_DebouncePress_Execute,
                                        Button_DebouncePress_CheckLeave, Button_DebouncePress_Leave },
    [BUTTON_STATE_PRESSED]          = { Button_Pressed_Entry,         Button_Pressed_Execute,
                                        Button_Pressed_CheckLeave,    Button_Pressed_Leave         },
    [BUTTON_STATE_LONG_PRESS]       = { Button_LongPress_Entry,       Button_LongPress_Execute,
                                        Button_LongPress_CheckLeave,  Button_LongPress_Leave       },
    [BUTTON_STATE_DEBOUNCE_RELEASE] = { Button_DebounceRelease_Entry, Button_DebounceRelease_Execute,
                                        Button_DebounceRelease_CheckLeave, Button_DebounceRelease_Leave },
};

Druhé využití je jádro automatu, ve kterém stejná konstanta nahrazuje napevno zapsaný „poslední stav“ při kontrole rozsahu:

static void Button_HandleStateTransition(void)
{
    if (BUTTON_STATE_COUNT <= newState)
    {
        newState = BUTTON_STATE_RELEASED;      /* invalid request: go to the safe state */
    }

    stateRoutines[actualState].execute();
    stateRoutines[actualState].checkLeave();

    if (actualState != newState)
    {
        stateRoutines[actualState].leave();
        actualState = newState;
        stateRoutines[actualState].entry();
    }
}