Tento článok ukazuje, ako z tej slučky získať riadok zdrojového kódu, na dvoch reálnych príkladoch, ktoré som spustil v QEMU (model dosky s STM32F4) a preskúmal pomocou GDB: volanie NULL ukazovateľa na funkciu a zápis na adresu, kde nie je nič. Všetky výstupy sú skutočné.

Čo robí jadro, keď nastane porucha​

Procesor Cortex-M sa nezrúti potichu. Keď nemôže pokračovať (neplatná inštrukcia, chyba zbernice, nepovolený prístup), spracuje výnimku a urobí dve veci, ktoré sú pre ladenie dôležité:

1. Uloží osem registrov na zásobník: R0, R1, R2, R3, R12, LR, PC a xPSR. Uložený PC je inštrukcia, ktorá spôsobila poruchu, a uložený LR hovorí, kto zavolal funkciu, v ktorej porucha nastala.
2. Nastaví bity v stavových registroch porúch, ktoré hovoria, o aký druh poruchy išlo: CFSR (konfigurovateľný stav porúch, zložený z troch častí pre poruchy pamäte, zbernice a použitia), HFSR (stav hard fault) a adresové registre MMFAR a BFAR s adresou, ku ktorej sa pristupovalo.

Poruchy pamäte, zbernice a použitia (usage fault) majú vlastné handlery, ale po resete sú vypnuté, takže každá porucha je eskalovaná na HardFault. Preto jeden handler vidí všetko a bit FORCED v HFSR hovorí, že sa tak stalo.

Handler, ktorý číta registre​

Jediná ťažkosť je dostať sa k zásobníku, kde registre sú. Jadro má dva ukazovatele zásobníka (MSP pre výnimky a hlavný kód, PSP pre úlohy operačného systému) a bit 2 hodnoty v LR pri vstupe do výnimky hovorí, ktorý z nich bol použitý. Musí sa to urobiť predtým, než kompilátor použije zásobník na vlastné účely, takže handler je krátka funkcia v assembleri (naked: bez prológu), ktorá odovzdá ukazovateľ funkcii 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"
    );
}

Pozrite sa na tri časti. Štruktúra stackFrame_t je rozloženie ôsmich registrov v poradí, v akom ich jadro ukladá. Funkcia HardFault_Report() ich (spolu so stavovými registrami) skopíruje do globálnej premennej faultInfo, vypíše krátku správu a potom zámerne zostane v slučke, aby sa mohol pripojiť debugger a pozrieť sa na túto premennú. Assemblerový stub vyberie správny zásobník a skočí na ňu. V produkte by sa správa zapísala do pamäte, ktorá prežije reset, a firmvér by sa sám resetoval, ale princíp je rovnaký.

Príklad 1: volanie NULL ukazovateľa​

Toto je aplikácia s chybou. Callback sa zaregistruje neskôr, ale kód, ktorý ho volá, sa spustí skôr:

/* ---- 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 správu:

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

A teraz jej čítanie, hodnotu po hodnote:

• PC = 0x00000000: procesor sa pokúsil vykonať inštrukciu na adrese nula. Takmer vždy to znamená skok cez NULL ukazovateľ na funkciu alebo návrat na poškodenú adresu.
• CFSR = 0x00020000: bit 17 je INVSTATE, „neplatný stav". Procesor sa pokúsil vykonávať kód v stave ARM, ktorý Cortex-M nemá. Dôvod je v xPSR: jeho bit 24 je bit T (Thumb) a tu je nulový (0x60000000). Adresa funkcie v Thumb móde má najnižší bit nastavený, NULL nie, takže skok cez ukazovateľ vynuloval bit T. Nulový bit T je typický odtlačok skoku na NULL.
• HFSR = 0x40000000: bit 30 je FORCED, porucha bola eskalovaná na HardFault z usage fault, ktorý nie je povolený.
• LR = 0x08000115: návratová adresa s nastaveným najnižším bitom (Thumb). Je to adresa volajúceho, 0x08000114, a práve tam je chyba.

S debuggerom trvá posledný krok pár sekúnd. QEMU čaká na GDB (-S -gdb tcp::1234) a session vyzerá 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 dá funkciu, list * dá riadok (ten za volaním, pretože to je návratová adresa) a disassembler ukáže dvojicu inštrukcií, ktorá je samotnou chybou: načítanie nuly do r3 a blx r3, volanie cez register, ktorý obsahuje NULL. Všimnite si r3 = 0x0 v uložených registroch. Bez debuggera je rovnaká odpoveď jedným príkazom toolchainu, ktorý potrebuje len adresu zo správy a súbor s ladiacimi informáciami (-g):

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

Príklad 2: zápis na adresu, kde nie je nič​

Zmenil som jeden riadok aplikácie: namiesto callbacku funkcia zapisuje na adresu 0xA0000000, kde v modeli čipu nie je namapované nič. Správa:

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

Tentoraz je PC platná adresa vo flash, bit T je nastavený (0x21000000) a CFSR je iný: 0x8200 sú dva bity, 9 (PRECISERR, presná chyba dátovej zbernice) a 15 (BFARVALID, register 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 ktorú sa program pokúsil zapisovať, PC je inštrukcia, ktorá to skúsila. Spolu hovoria „táto inštrukcia zapisovala na túto adresu", čo je úplný popis problému. Ak je adresa malá (0x00000008), ide o NULL ukazovateľ na štruktúru a pristupujete k jej členu. Ak vyzerá ako dáta (0x20000000 a o niečo viac), ide o zásobník alebo buffer, ktorý ste pretiahli.

Bity CFSR, s ktorými sa stretnete​

Register je kombináciou troch registrov (každý z nich má vlastný bajt alebo dva bajty). Toto sú tie, ktoré uvidíte najčastejšie (dva, ktoré som pozoroval v príkladoch, sú zvýraznené):

Čo zvyčajne stojí za HardFaultom​

Prvý riadok tabuľky a princíp druhého (chyba zbernice s adresou v BFAR) som predviedol. Zvyšné riadky sú zhrnutím obvyklých príčin, vyplývajú z významu bitov v referenčnej príručke jadra.

V praxi​

1. Nikdy nenechávajte predvolený handler ako prázdnu slučku. Handler vyššie má asi tridsať riadkov a mení poruchu na správu s miestom v kóde. Vložte ho raz do startup kódu projektu.
2. Uchovávajte ladiace informácie v súbore, ktorý archivujete s vydaním (-g a .elf), aby sa adresa zo správy z terénu dala premeniť na riadok, aj keď sa firmvér dodáva stripnutý. Je to ďalší dôvod pre reprodukovateľný build: adresa niečo znamená len pre presný binárny súbor, ktorý ju vytvoril.
3. Povoľte jemnejšie poruchy (bity v SHCSR), keď chcete samostatné handlery UsageFault, BusFault a MemManage. Správa je bohatšia, pretože stavové registre sa nezdieľajú.
4. Uložte správu do pamäte, ktorá prežije reset (sekcia, ktorú startup kód nemaže, pozrite článok o tom, čo sa stane pred main()), resetujte a odošlite ju po reštarte. Správa zo zariadenia v teréne má väčšiu hodnotu než sto dohadov.
5. Predchádzajte tomu, čomu sa dá. Volanie NULL v príklade je chyba, ktorú by zachytili pravidlá MISRA a unit test modulu (ukazovateľ musí byť nastavený pred prvým volaním), a pretečenie zásobníka je vec, pri ktorej treba poznať využitie zásobníka (pravidlo proti rekurzii).

Rovnaká session na doske​

Použil som QEMU, pretože nepotrebuje dosku, a jeho server GDB (-S -gdb tcp::1234) sa správa rovnako ako ten, ktorý poskytuje debug probe: príkazy v príkladoch sú príkazy, ktoré zadáte s probe. Platforma má artefakt pre sadu nástrojov probe-rs (ladiaca sada pre ARM ciele cez debug probe, so serverom DAP), čo je spôsob, ako pripojiť GDB alebo IDE ku skutočnej doske. Pre tento článok som ho nespúšťal, keďže vo svojom prostredí nemám probe.

Zhrnutie​

1. HardFault nie je záhada: jadro uložilo registre a nastavilo stavové bity.
2. Handler musí nájsť správny zásobník (EXC_RETURN) a prečítať rámec, CFSR, HFSR a BFAR.
3. PC a LR dávajú miesto, CFSR dáva druh, BFAR dáva adresu.
4. PC = 0 s INVSTATE je skok na NULL a bit T v xPSR to ukazuje.
5. Uchovajte si .elf a adresa z hlásenia z terénu sa zmení na riadok kódu.

Ukážem dva experimenty, ktoré som spustil: ten istý zdrojový kód testu, ktorý prejde na PC a zlyhá na Cortex-M4, a firmvér, ktorý zapisuje do registrov USART na skutočných adresách STM32F4 a ktorého text sa objaví v termináli. Na konci je úprimný zoznam toho, čo vám simulátor nepovie.

Kde to zapadá​

Stredná úroveň je tá, ktorá sa vynecháva najčastejšie, a pritom je najlacnejšia na pridanie do CI, ktoré už firmvér zostavuje: simulátor je spustiteľný súbor, ktorému odovzdáte súbor, ktorý vyprodukoval váš build.

Nástrojom v mojich experimentoch je QEMU 8.2.2 so strojom netduinoplus2, modelom dosky s STM32F405 (Cortex-M4 s pamäťovou mapou skutočného čipu: flash na 0x08000000, RAM na 0x20000000, periférie na ich skutočných adresách). Platforma má artefakt pre iný simulátor, Renode, a vrátim sa k nemu na konci.

Experiment 1: test, ktorý prejde na PC a zlyhá na MCU​

Malý modul s dvoma funkciami, ktoré má každý firmvér: prevod času a kontrola prijaté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);
}

Obe funkcie vyzerajú správne a obe sú otestované na PC. Zdrojový kód testu je pre oba ciele rovnaký: líši sa len výstup. Súbor Platform.h tlačí cez printf na PC a cez semihosting (požiadavku na simulátor alebo debugger) na cieľovom zariadení a návratový kód testu hovorí, či prešiel:

#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

Ten istý zdrojový kód, skompilovaný pomocou arm-none-eabi-gcc pre Cortex-M4 a spustený 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

Dve chyby, obe na PC neviditeľné:

• long má inú šírku. Na 64-bitovom Linuxe na PC má long 64 bitov, na Cortex-M má 32. 3 000 000 ms * 1000 je 3 000 000 000, čo sa nezmestí do 32-bitového čísla so znamienkom (najväčšie je 2 147 483 647), takže výsledok je nesprávny a v C ide navyše o nedefinované správanie.
• char má iné znamienko. Norma C necháva otvorené, či je obyčajný char so znamienkom. Na x86 je, takže (char)0xFF je -1 a kontrola receivedByte < 0 funguje. Na ARM je bez znamienka, takže (char)0xFF je 255 a porovnanie nikdy nie je pravdivé. Kompilátor ARM to dokonca povie, a len tam:

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

Obe sú otázkou prenosných typov, čo je téma pravidla 4.6 v článku o MISRA: používajte typy s veľkosťou a znamienkom. Opravená verzia používa uint64_t pre čas a uint8_t pre 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 tie isté štyri kontroly teraz prejdú na oboch cieľoch, s návratovým kódom 0 na oboch. Prvá verzia nebola chybou testu a test na PC nebol nesprávny: jednoducho testoval iný program.

Návratový kód je celá integrácia s CI. Simulátor skončí s kódom, ktorý firmvér odovzdá volaniu semihostingu, takže add_test v CMake (pozrite článok o CMake pre firmvér) zlyhá, keď zlyhá test na cieľovom zariadení:

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: registre periférie​

Simulátor modeluje aj periférie, a tak môže bežať aj kód najbližší k hardvéru. Toto je firmvér, ktorý posiela text cez USART1 na STM32F4, napísaný na úrovni registrov so skutočnými adresami (žiadna knižnica, žiadny startup nad rámec kódu z článku o tom, čo sa stane pred 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áli simulátora: firmvér zapol hodiny periférie v RCC, povolil USART a jeho vysielač, počkal na príznak TXE a zapísal do dátového registra, presne tak, ako by to urobil na doske, a model USART odovzdal bajt sériovému portu. Je to test ovládača voči modelu registrového rozhrania. Ak ovládač čaká na príznak, ktorý nikdy nepríde, test to nájde pomocou timeoutu, a nie pri stole s osciloskopom.

Čo vám simulátor nepovie​

Simulátor je model a každý model má hranicu. Niekoľko, na ktoré som narazil v experimentoch tejto série:

• Časovanie nie je skutočné. QEMU vykonáva inštrukcie tak rýchlo, ako dovolí PC, a nepočíta cykly skutočného jadra. Test, ktorý má dokázať „prerušenie sa obslúži do 5 mikrosekúnd", sa v ňom urobiť nedá.
• Prerušenia prichádzajú na iných miestach než na MCU. V článku o prerušeniach sa stratená aktualizácia zdieľaného počítadla v QEMU neobjavila ani v 200 000 pokusoch, pretože QEMU doručuje prerušenie medzi blokmi preloženého kódu. Skutočné MCU môže prerušiť po každej inštrukcii. Simulátor nedokazuje neprítomnosť race condition.
• Existujú len namodelované periférie. Model STM32F405 má USART, ale iný čip môže mať perifériu, ktorú model nemá, alebo ju má v zjednodušenej podobe: registre tam sú, analógová časť nie.
• Chýba elektrický svet: zákmity kontaktu, šum na vstupe ADC, pokles napätia. Všetko, čo prichádza zvonku, je to, čo do modelu vložíte.

Simulátor teda nenahrádza ani unit testy (sú rýchlejšie a testujú logiku izolovane), ani hardvérové testy (testujú realitu). Nájde veci medzi nimi: kompilátor cieľového zariadenia, typy, startup, pamäťovú mapu, ovládač voči modelu registrov, a robí to za pár sekúnd pri každom commite.

Renode​

Platforma má artefakt pre Renode, open-source simulačný a virtuálny vývojový framework od Antmicro, dodávaný spolu s renode-test, jeho testovacím runnerom založeným na Robot Framework, ktorý sa používa na integračné testy simulovaného firmvéru. Pre tento článok som ho nespúšťal (vydanie sa v mojom prostredí nedalo stiahnuť), takže iba opakujem, čo hovorí jeho dokumentácia, a neporovnávam ho s QEMU. Štruktúra takéhoto testu je rovnaká ako vyššie: skutočný ELF, model hardvéru, verdikt a návratový kód pre CI.

Kontrolný zoznam​

1. Zostavte test pre cieľové zariadenie, kompilátorom cieľového zariadenia, a spustite ho v simulátore, popri PC.
2. Použite jeden zdrojový kód testu pre oba, s tenkou vrstvou (Platform.h) pre výstup a ukončenie.
3. Návratový kód simulátora je výsledok testu, takže CI nepotrebuje nič viac.
4. Používajte typy s veľkosťou a znamienkom (uint32_t, uint8_t) a varovania kompilátora cieľového zariadenia: druhú chybu vyššie (char) by našlo -Wtype-limits, keby sa niekto pozrel na výstup buildu pre ARM.
5. Zapíšte si, čo simulátor nevie dokázať (časovanie, race condition, analógový svet), a nechajte to na hardvérové testy.

Reprodukovateľný build má jednoduchú definíciu: rovnaké vstupy dajú rovnaké bajty. Tento článok ukazuje, aké sú vstupy buildu firmvéru, ako ich platforma Embedbits pripína (Artifacts Handler) a experiment, ktorý som urobil: dva buildy toho istého zdrojáka v dvoch priečinkoch v dvoch rôznych časoch dajú dve rôzne binárky. Potom o tri zmeny neskôr dajú tú istú, až na posledný bit.

Vstupy buildu​

Build je funkcia. Čo do nej vstupuje?

Prvý, tretí a štvrtý sú v Gite, takže sú pripnuté už návrhom. Nástroje a prostredie sú miesta, kde sa build zvyčajne rozpadne, a každé z nich má vlastnú odpoveď.

Nástroje: Artifacts Handler​

„Nainštalujte GCC 13.2 a Ninja 1.12“ v README je veta, ktorú nikto nedodrží do písmena. Platforma to rieši tak, že z nástrojov urobí súčasť projektu. Artifacts Handler je skript CMake, ktorý zo súboru ArtifactsConfig.txt číta zoznam nástrojov a ich verzií a pripravuje ich. Jeho dokumentácia hovorí, že jediný softvér, ktorý používateľ potrebuje, je Git a CMake a každú ďalšiu súčasť buildu dodá handler. V krokoch:

1. Naklonuje koreňový repozitár artefaktov (bez submodulov, aby sa ušetrila prevádzka).
2. Nájde v ňom artefakt (každý nástroj je submodul, názvy sa porovnávajú bez ohľadu na veľkosť písmen).
3. Checkoutne požadovanú verziu (plytký klon, --depth=1). Vydania sú označené verziou a operačným systémom (Win, Unix, DarwinARM).
4. Nainštaluje ho: rozbalí archív do priečinka cache.
5. Inicializuje ho: vo väčšine prípadov dá priečinok nástroja na začiatok PATH, takže projektový nástroj vyhrá nad akýmkoľvek nástrojom nainštalovaným v systéme.

Konfigurácia má jeden riadok pre každý nástroj, name;version;handler version, napríklad riadky z dokumentácie platformy:

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

Prvé číslo je verzia samotného nástroja (binárky), druhé je verzia handler skriptu daného artefaktu (môže sa meniť nezávisle, napríklad keď sa opraví spôsob nastavenia PATH). Cache má jeden priečinok na nástroj a verziu, takže viaceré verzie žijú vedľa seba a projekt, ktorý potrebuje staršiu, neruší projekt, ktorý potrebuje novšiu.

Prečo nie latest​

Handler akceptuje aj latest namiesto čísla. Je to pohodlné a rozbíja to celú myšlienku. Spustil som handler s riadkom ninja;latest;latest a vypísal, na čo to 5. októbra 2026 rozlíš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.

(Beh sa zastavil pri sťahovaní vydania, pretože moje prostredie sa nedokáže dostať k GitHub API, ale rozlíšenie prebehlo.) latest je pohyblivý cieľ: podľa dokumentácie sa zoznam verzií sťahuje raz za deň, takže ten istý súbor dá dnes 1.13.2 a po ďalšom vydaní niečo iné. Build, ktorý je dnes správny, môže byť zajtra iný build a nič vo vašom repozitári to nepovie. Pravidlo je preto jednoduché: latest je na vyskúšanie novej verzie a vydaný projekt pripína každé číslo.

Ďalšie nastavenia, ktoré pomáhajú​

• Offline režim (-DOFFLINE_MODE=true): kontroluje sa len lokálna cache a nič sa nesťahuje. Je to spôsob, ako dokázať, že build nezávisí od siete, a spôsob, ako zostavovať na mieste, kde sieť nie je.
• Umiestnenie cache (ARTIFACTS_HANDLER_CACHE_PATH) a koreňového repozitára (ARTIFACTS_HANDLER_ROOT_REPO_URL) sa dajú nastaviť v konfiguračnom súbore, v prostredí alebo na príkazovom riadku. Firma môže prevádzkovať vlastné zrkadlo artefaktov, takže build nezávisí ani od verejného servera.
• Kontrolný súčet. Každé vydanie artefaktu sa publikuje so súborom SHA-256 vedľa archívu, takže poškodený alebo vymenený súbor sa neprijme potichu.

Nástroje sú prvá polovica odpovede. Druhá polovica je niečo, čo si môžete overiť sami, príkazom nižšie.

Prostredie: experiment​

Vzal som príkladový projekt z článku o CMake a pridal súbor, ktorý má väčšina firmvérov v nejakej podobe: informácie o builde. Ukladá čas buildu a cestu zdrojového súboru, pretože niekto kedysi chcel v debuggeri vidieť „kedy sa to zostavilo“:

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

Potom som ten istý zdroják zostavil dvakrát: v dvoch rôznych priečinkoch (a a b), druhý o tri sekundy neskôr. Príkaz strings aplikovaný na obe binárky ukazuje, čo je vnútri:

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 oboch súborov firmware.bin sa líši:

f2366319462b6fee...
d634c24c3c431799...

Dva buildy jedného zdrojáka, dve rôzne binárky. Čas je zrejmý, ale cesta je tá, na ktorú ľudia zabúdajú: __FILE__ (a tiež assert() a ladiace informácie) zapisuje do programu plnú cestu k súboru a cesta je iná na PC každého vývojára a v každej úlohe CI. Binárka zostavená v /home/anna/project a tá istá zostavená v /builds/job-4711/project sú dva rôzne súbory.

Tri zmeny​

1. Odstráňte hodiny. Makrá __DATE__ a __TIME__ nemajú miesto vo firmvéri, ktorý má byť reprodukovateľný. Kompilátor to dokáže vynútiť, takže ich nikto omylom nepridá späť:

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. Verzia je vstup. Ak chcete vedieť „čo je tento firmvér“, build dostane odpoveď zvonka: verziu, tag alebo hash commitu, ktoré build systém odovzdá ako definíciu. Ten istý zdroják má rovnakú verziu, teda rovnaké bajty:

#ifndef BUILD_VERSION
#define BUILD_VERSION "unknown"
#endif

const char buildVersion[] = BUILD_VERSION;

3. Odstráňte cesty. Voľba -ffile-prefix-map=OLD=NEW nahradí prefix každej cesty, ktorú GCC vkladá do výstupu (__FILE__, ladiace informácie, aserty). Zdrojový priečinok projektu sa nahradí bodkou:

# 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 tromi zmenami dá rovnaká kontrola:

first : 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
second: 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
REPRODUCIBLE

.bin je identický a rovnako aj .elf, vo vydaní (-Os -g0) aj v debug builde (-Og -g3), ktorého ladiace informácie sú plné ciest. S -ffile-prefix-map ukáže strings binárky ./Application/BuildInfo.c a verziu 1.2.3 a nič o PC, ktoré ju zostavilo.

Test, ktorý nikdy nezostarne​

Nestačí urobiť build reprodukovateľným raz, pretože prvé __TIME__, ktoré niekto pridá, ho zničí. Urobte z toho preto test: zostavte zdroják dvakrát a porovnajte. Toto je skript, ktorý som použil na čísla vyššie; skopíruje projekt do dvoch priečinkov, oba zostaví s pauzou medzi 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

Spúšťaný v CI pri každom merge je strážcom. Použil som ho aj na pokazenú verziu informácií o builde, aby som si bol istý, že dokáže zlyhať, a zlyhal (NOT REPRODUCIBLE, návratový kód 1, dva rôzne hashe). Test, ktorý nikdy nezlyhal, je test, ktorý nepoznáte.

Čo ešte rozbíja reprodukovateľný build​

Otestoval som tri veci vyššie. Nasledujúce sú ďalšie známe zdroje problémov, na ktoré treba pamätať (v príklade som ich nepotreboval, takže ich len pomenúvam):

• Poradie súborov, ktoré pochádza z file(GLOB ...) alebo z výpisu adresára. Zdroje by sa mali uvádzať explicitne, ako v súboroch CMake modulov platformy.
• Časová pečiatka v archíve (statická knižnica vytvorená cez ar). Moderné verzie nástrojov majú deterministický režim, ale starý toolchain ho mať nemusí.
• Generovaný kód. Mocky a runnery unit testov alebo linker script generovaný pre MCU sa musia generovať rovnako z rovnakých vstupov. Pravidlami sú triedenie a žiadne časové pečiatky vo výstupe.
• Samotný kompilátor. Tá istá verzia toho istého kompilátora z dvoch zdrojov (balík distribúcie a archív od výrobcu) sa môže líšiť v knižniciach, ktoré linkuje. To je dôvod, prečo brať kompilátor z jedného miesta, čo je celý zmysel artefaktov.
• Build s iným počtom vlákien. Správny build systém dá rovnaký výsledok s -j1 aj -j16 a test na to je lacným doplnkom k tomu vyššie.

Kontrolný zoznam​

1. Každý nástroj je v ArtifactsConfig.txt pripnutý na presnú verziu. Žiadne latest vo vydaní.
2. Submoduly (BSP, platforma) sú pripnuté commitmi a aktualizácia je viditeľný commit.
3. Nič vo firmvéri nezávisí od času ani cesty: -Werror=date-time, -ffile-prefix-map.
4. Verzia je parametrom buildu, odvodená z tagu, a je uložená vo firmvéri.
5. CI zostavuje dvakrát a porovnáva. Občas tiež zostavuje offline, z cache.
6. Dodaná binárka sa ukladá spolu so svojím SHA-256 a tagom, takže „je to ten istý súbor“ má odpoveď bez nového buildu.

Odmenou je veta, ktorú použijete do telefónu so zákazníkom: „Zostavil som presne váš firmvér a chyba v ňom (nie) je.“

Kód z modulu je citovaný z vetvy STM32H5 repozitára Bsp-Mcal-Gpio. Príklady, ktoré ho používajú, som skompiloval a spustil proti skutočným Gpio_Port.h a Gpio_Types.h, s malým fake implementácie, aby sa API dalo vyskúšať na PC.

Celé rozhranie na jednej obrazovke​

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é rozhodnutie nižšie sa dá vyčítať z tohto zoznamu.

1. Pin je dvojica identifikátorov, nie makro výrobcu​

Ovládače výrobcu adresujú pin ukazovateľom na blok registrov a bitovou maskou: LL_GPIO_SetOutputPin(GPIOA, LL_GPIO_PIN_5). MCAL namiesto toho berie dve enumerácie, gpio_PortId_t a gpio_PinId_t:

Gpio_Set_PinLevel( GPIO_PORT_A, GPIO_PIN_ID_5, GPIO_PIN_LEVEL_HIGH );

Prečo: kód nad MCAL nepotrebuje žiadnu hlavičku výrobcu, nevie, čo je GPIOA (adresa bloku registrov výrobcu) a identifikátor sa dá kontrolovať na rozsah, čo pri ľubovoľnom ukazovateli nejde. Každá enumerácia končí počítadlom (GPIO_PORT_CNT, GPIO_PIN_ID_CNT), ktoré je hornou hranicou pre kontrolu na začiatku funkcie.

Cena: tabuľka, ktorá prekladá identifikátor na blok registrov (v Gpio.c, jeden riadok na port) a jedna nepriama úroveň navyše. Tabuľka zároveň rieši vlastný problém: MCU jednej rodiny majú rôzny počet portov, takže záznamy sú obalené v #if defined(GPIOK) (pozri článok o rodinách).

2. Každá funkcia, ktorá môže zlyhať, vracia stav a výsledky idú von cez ukazovateľ​

Všetky funkcie okrem Deinit, Task a getteru verzie vracajú gpio_RequestState_t a gettery odovzdávajú hodnotu cez parameter-ukazovateľ:

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 */
}

Prečo: návratová hodnota getteru nemôže niesť hodnotu aj informáciu, že hodnota nie je platná (GPIO_PIN_LEVEL_LOW je platná úroveň, takže vrátená 0 je nejednoznačná). So stavom v návratovej hodnote a dátami v parametri je neplatný port, neplatný pin alebo NULL ukazovateľ viditeľná chyba a nie potichu zlá úroveň. * const v signatúre hovorí, že funkcia nemení ukazovateľ, iba dáta za ním.

Cena: dva riadky namiesto jedného pri každom použití. A stav má dve hodnoty (GPIO_REQUEST_OK, GPIO_REQUEST_ERROR), takže volajúci vie, že zlyhalo, a nie prečo. Pre GPIO to stačí, lebo dôvodov je len niekoľko (neplatný identifikátor, NULL) a všetky sú programátorské chyby. Pri periférii so skutočným zlyhaním (timeout I2C, chyba zbernice) volajúci potrebuje viac a obvyklou odpoveďou je bohatšia enumerácia.

Pravidlo z článku o MISRA, ktoré sa tu uplatňuje, je 17.7 (vrátená hodnota sa používa): rozhranie tu uľahčuje jeho dodržanie, pretože každá funkcia, ktorá môže zlyhať, to oznamuje hodnotou, na ktorú sa musíte pozrieť.

3. Pin sa konfiguruje dátami, nie sledom volaní​

Existuje konfiguračná štruktúra so všetkým, čo pin popisuje, a jedna funkcia, ktorá ju 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;

Prečo: znalosť o doske potom žije v tabuľke a kód, ktorý ju aplikuje, je pre každú dosku rovnaký. Pozrite sa na príklad, ktorý som skompiloval a spustil: doska sú dva záznamy a inicializácia je sluč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)));
}

Keďže tabuľka sú dáta, nová revízia DPS zmení riadok v tabuľke a nič v kóde. V architektúre Embedbits je to úloha vrstvy HAL: drží tabuľky a pomocou MCAL ich aplikuje.

Cena: štruktúra má osem polí a každý záznam musí vyplniť všetky (designated initializers to robia čitateľným a vynechané pole je nula, čo nie je vždy rozumná hodnota). Preto je užitočným spoločníkom funkcia Get_DefaultConfig, ktorú majú niektoré iné moduly.

4. Polarita signálu je vlastnosťou pinu, nie kódu​

Štruktúra má pole PinActiveLevel a existujú funkcie Gpio_Set_PinStateActive() a Gpio_Set_PinStateInactive(), ktoré berú polaritu ako parameter. Dôvodom je obyčajný fakt z elektroniky: LED môže byť pripojená k zemi (svieti s úrovňou high) alebo k napájaniu (svieti s úrovňou low) a signál chip-select je zvyčajne active low. Ak kód hovorí Gpio_Set_PinLevel(..., HIGH) pre „LED zapnutá“, je to správne pre jednu dosku a zlé pre ďalšiu.

S polaritou v tabuľke aplikácia povie „zapni“ a tabuľka povie, čo to znamená. V príklade vyššie je LED pripojená k napájaniu, takže PinActiveLevel je GPIO_PIN_LEVEL_LOW a test potvrdzuje, čo pin robí:

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. Enumerácie sú konštanty výrobcu​

Typy si nevymýšľajú vlastné čísla, sú to čísla ovládača výrobcu:

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;

Prečo: konverzia z typu MCAL na hodnotu, ktorú chce funkcia LL, je zadarmo: žiadny switch, žiadna tabuľka a žiadna možnosť urobiť v preklade preklep. Hodnoty konštánt sa líšia rodinu od rodiny a to je skryté v jedinom #include portu RAL (Stm32_gpio.h špecifický pre rodinu).

Cena: Gpio_Types.h, verejná hlavička, includuje hlavičku RAL, takže konštanty výrobcu presakujú do hlavičiek, ktoré vidia používatelia modulu. Alternatívou je typ s vlastnými hodnotami a prekladová tabuľka v súbore .c, čo stojí kód a miesto pre chybu, ale drží výrobcu mimo verejných hlavičiek. Rozhodnutie je kompromis a je dobré vedieť, že ním je.

6. Rovnaký životný cyklus ako v každom inom module​

Gpio_Get_ModuleVersion(), Gpio_Init(), Gpio_Deinit() a Gpio_Task() pochádzajú zo šablóny, s ktorou začína každý modul (pozri článok o organizácii súborov). Rozdiel je na jedinom mieste, kde to dáva zmysel: Gpio_Init() nie je void, berie konfiguráciu pinu. Modul GPIO nepozná dosku, takže „inicializuj modul“ nemá zmysel bez otázky „ktorý pin?“. Jednotný životný cyklus, ktorý sa ohne tam, kde to povaha modulu vyžaduje, je lepší než životný cyklus vnútený modulu, kam nepasuje.

7. Poradie krokov je súčasťou rozhrania​

Pozrite sa na komentár 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, čo je krok, ktorý skutočne pripája výstupný budič na pad, je posledný. Keby bol režim prvý, pin by na okamih budil úroveň, akú mal výstupný register po resete (zvyčajne low), a potom by preskočil na správnu: impulz na vedení, ktoré môže byť chip-select, reset iného čipu alebo gate tranzistora. Takýto glitch je v debuggeri neviditeľný a na osciloskope viditeľný. Je to dobrý príklad pravidla pre návrh API: keď na poradí krokov záleží hardvéru, funkcia, ktorá ich vykonáva, by mala poradie vlastniť, aby ho používateľ nemohol pokaziť.

Druhá veta komentára, „stops at the first failed step“, je tiež dizajnové rozhodnutie: funkcia sa nepokúša pokračovať po chybe a vráti stav zlyhaného kroku.

8. Zlý argument je chyba, ktorú volajúci vidí, nie pád​

Funkcie kontrolujú svoje argumenty a odpoveďou 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));

(Toto je test môjho fake, ale skutočný Gpio_Init() robí to isté pre NULL: celé telo je vo vnútri if( GPIO_NULL_PTR != gpioConfig ).) Konštanty _CNT tu majú druhú úlohu: GPIO_PORT_CNT je prvá hodnota, ktorá nie je platným portom, takže kontrola je jediné porovnanie. Vo firmvéri nie je komu ukázať správu a assert, ktorý zastaví program, je pre produkčný build zvyčajne zlá odpoveď. Lepšia je chyba, ktorá ide hore k volajúcemu, ktorý vie, čo robiť (a k modulu nad MCAL, ktorý vie, čo je kritické).

Na čo by som sa pozrel znova​

Úprimná revízia návrhu má vždy zoznam a tento má dve položky, ktoré pochádzajú z článku o MISRA:

• Gpio_Init( gpio_Config_t *gpioConfig ) štruktúru iba číta, takže parameter by mohol byť const gpio_Config_t * (Rule 8.13). Signatúra by hovorila, že funkcia konfiguráciu nemení, a tabuľka dosky by mohla byť const a žiť vo flash namiesto v RAM.
• Dvojhodnotový gpio_RequestState_t je v každom module rovnaký (generuje ho šablóna). Je to jednoduché a jednotné rozhodnutie, ktoré je pre GPIO správne, a moduly so skutočnými zlyhaniami budú skôr či neskôr potrebovať viac.

Princípy stručne​

1. Skrývajte hardvér, nie zámer. Používateľ povie ktorý pin a akú polaritu, nie ktorý register.
2. Urobte neplatný stav viditeľným. Stav pre všetko, čo môže zlyhať, a výstup len pri úspechu.
3. Dajte znalosť do dát. Doska je tabuľka, ktorú číta slučka.
4. Nechajte funkciu vlastniť poradie, keď na ňom hardvéru záleží.
5. Držte rozhranie rovnaké a povedzte úprimne, kde je ohnuté (Init s parametrom) a kde abstrakcia presakuje (konštanty výrobcu v typoch).

Rozhranie má dvoch čitateľov: používateľa dneška a správcu budúceho roka. Rozhodnutia vyššie sú napísané pre oboch a komentáre v hlavičkách sú dôkazom, že niekto myslel na toho druhého.

Tento článok ukazuje, ako vyzerá zdokumentovaný modul v mojich projektoch, ako sa generuje a ako z dokumentácie urobiť súčasť CI, ktorú nemožno preskočiť. Príklady boli zostavené s Doxygen 1.9.8 a Graphviz a výstupy sú skutočné.

Čo dokumentovať a čo nie​

Môj coding style má o tom jeden odsek: komentáre v štýle Doxygen pre všetky verejné funkcie, typy a makrá, v angličtine, krátke a presné, prečo a nie čo. Pár príkladov rozdielu:

Prvý stĺpec opakuje názov funkcie, ktorý čitateľ už vidí. Druhý stĺpec hovorí to, čo čitateľ vidieť nemôže: jednotku, platný rozsah, kto vlastní pamäť, či sa výstup zapíše v prípade chyby, odkiaľ sa funkcia môže volať, čo treba urobiť predtým. Pre embedded rozhranie je to aj miesto pre informácie, ktoré je nebezpečné hádať: je bezpečné volať ju z prerušenia, ako dlho môže blokovať, smie byť ukazovateľ NULL.

Modul v súboroch platformy​

Šablóny EmBi_Platform, z ktorých každý modul vychádza, majú rovnakú kostru dokumentácie: hlavičku súboru s \author, \file, \ingroup a \brief a nad každou funkciou blok s \brief, popisom a \return. Šablóna konečného automatu pridáva \pre pre predpoklady a blok \par Used global variables so zoznamom premenných, ktoré funkcia číta (in), zapisuje (out) alebo oboje (in,out), čo je prekvapivo užitočný druh dokumentácie: tok dát funkcie v troch riadkoch.

Celý modul je v Doxygene jedna skupina. \ingroup Temperature v každom súbore hovorí, že súbor patrí do modulu, a samotná skupina je definovaná raz, v súbore port:

/**
 * \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átky popis typu a každej hodnoty (komentár /**< ... */ za členom dokumentuje člen na tom istom riadku):

/**
 * \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 */

Generovanie​

Doxygen sa konfiguruje súborom s pár stovkami volieb. Písať ho ručne je chyba, ktorej sa dá ľahko vyhnúť: platforma má súbor ako šablónu (Doxyfile.in v artefakte Doxygen) a napĺňa ho z premenných CMake a projekty nastavujú len tie, ktoré sa líšia od predvolených. To isté umožňuje aj samotný modul CMake a toto je celá konfigurácia prí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 cieľ:

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

Výsledkom je priečinok so stránkami HTML. Skupina modulu so súbormi, ktoré do nej patria, a s popisom zo súboru port vyzerá takto:

Doxygen tiež kreslí include graf každého súboru a call graf a caller graf každej zdokumentovanej funkcie (HAVE_DOT, Graphviz: preto má platforma na to artefakt). Include grafy stojí za to občas pozrieť: šípka z aplikačného súboru do internej hlavičky modulu je ten istý problém, ktorý opisuje článok o organizácii súborov, len videný zhora.

Dokumentácia ako test​

Toto je časť, ktorá mení disciplínu. Štyri voľby menia chýbajúcu dokumentáciu z „mali by sme“ 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 prejde všetko, vypíše všetky varovania a až potom zlyhá (obyčajné YES sa zastaví pri prvom). Vyskúšal som to: zo súboru port som zmazal popis Temperature_Task() a \param funkcie Temperature_Get_Value() a build vypísal:

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 príkazu je 1, takže CI je červené.) Keď sa popisy vrátia, ten istý build skončí bez akéhokoľvek výstupu a s návratovým kódom 0. Nová funkcia bez komentára sa teraz nemôže omylom dostať do hlavnej vetvy a nikto nemusí byť ten, kto si to pri review pamätá.

Čo obsahuje dobrá dokumentácia rozhrania​

Pri každej funkcii verejného rozhrania skontrolujte zoznam:

1. Čo robí, v jednej vete, so slovesom (\brief).
2. Parametre: smer ([in], [out], [in,out]), jednotku, rozsah, či je NULL povolené.
3. Návratová hodnota: každá hodnota, ktorá sa môže vrátiť, a čo znamená.
4. Predpoklady (\pre): čo sa musí urobiť predtým, napríklad inicializácia.
5. Kontext: dá sa volať z prerušenia, blokuje, ako dlho trvá.
6. Vedľajšie účinky: čo ešte mení (globálny stav, periféria).

Ak funkcia nemá odpoveď na jednu z týchto otázok, odpoveď je v kóde a čitateľ si ju musí prečítať. To je znamenie, že rozhranie nie je dokončené, a písanie komentára je často moment, keď to zistíte.

Kde to zapadá v platforme​

Každý modul platformy má vo svojom CMakeLists.txt volanie, ktoré zaregistruje jeho priečinok pre dokumentáciu (keď je artefakt Doxygen v projekte dostupný), a koreňový build má voľbu DOXYGEN_ENABLED. Dokumentácia celého firmvéru sa teda generuje tým istým buildom ako firmvér: -DDOXYGEN_ENABLED=ON. Artefakty (Doxygen a Graphviz) sa sťahujú vo verzii, ktorú má projekt pripnutú, takže stránky dnes a o rok vyzerajú rovnako.

Checklist​

1. Každá verejná funkcia, typ a makro má popis. Interné len tam, kde to nie je zrejmé.
2. Popis hovorí to, čo čitateľ nevidí v signatúre: jednotky, rozsahy, kontext, chyby.
3. Jedna skupina na modul (\defgroup v súbore port, \ingroup v ostatných).
4. WARN_IF_UNDOCUMENTED, WARN_NO_PARAMDOC a FAIL_ON_WARNINGS v CI.
5. Grafy sú zapnuté a niekto sa občas pozrie na include graf aplikácie.
6. Dokumentácia sa generuje z toho istého buildu ako firmvér, s pripnutými nástrojmi.

Build systém platformy Embedbits (EmBi_Platform) je postavený na CMake a tento článok vysvetľuje súčasti, ktoré potrebuje každý embedded build v CMake, na malom projekte, ktorý som zostavil a spustil: toolchain file, flagy s menami, typy buildu, moduly ako knižnice, linker script, súbory po linkovaní a test, ktorý spustí firmware v simulátore. Všetky čísla a výstupy sú skutočné.

Dve vrstvy: projekt a platforma​

Platforma delí build na dve časti a túto myšlienku stojí za to ukradnúť aj pre malý projekt. Koreňový CMakeLists.txt produktu je minimálny vstupný bod a všetko komplikované žije v samostatnom skripte, ktorý je verzovaný a zdieľaný (submodul Gitu) a ktorý koreň includuje:

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

Skript platformy pozná typy buildu (Debug, Release, UnitTest, IntegrationTest), kontroly parametrov, toolchain, include cesty a registráciu modulov. Produkt dopĺňa iba to, čo je preň špecifické. Oprava buildu je potom nová verzia submodulu, nie úprava desiatich produktov. Príklad nižšie má obe časti v jednom projekte, aby bol krátky, ale zachováva rovnaké oddelenie: cmake/ je „platforma“ a CMakeLists.txt je „produkt“.

Ukážkový 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 nie je PC​

CMake predpokladá, že zostavujete pre počítač, pri ktorom sedíte. Toolchain file hovorí niečo iné:

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

Riadok, na ktorý ľudia zabúdajú, je CMAKE_TRY_COMPILE_TARGET_TYPE. Na začiatku CMake zostaví testovací program, aby overil, že kompilátor funguje, a bare-metal kompilátor nevie zlinkovať program pre PC (nie je operačný systém, nie je main, ktorý by niekto volal). Ak je cieľom kontroly statická knižnica, test prejde. Toolchain sa zadáva na príkazovom riadku, raz, pri vytvorení build priečinka:

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

Rovnaký zdrojový priečinok s iným -B je iný build: build-release vedľa neho alebo build pre unit testy na PC, bez toolchain file.

Flagy s menami​

Riadok ako -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -ffunction-sections ... sa ťažko kontroluje, pretože nikto nevie, ktorá jeho časť je dôležitá. Platforma má súbor Flags.cmake s premennou pre každý flag a s komentárom (THUMB_MODE, ENABLE_ALL_WARNINGS, REMOVE_UNUSED_FUNCTIONS, ENABLE_GC_SECTIONS, PRINT_MEMORY_USAGE a tak ďalej, plus varianty CPU a FPU od Cortex-M0 po M85). Projekt sa potom číta ako veta. Môj obsahuje len to, čo príklad potrebuje:

# 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ý koreňový súbor príkladu, 80 riadkov:

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

Vysvetlím niekoľko riadkov, od ktorých závisí, či bude firmware správny.

Typy buildu s explicitnými flagmi. Sú len dva, Debug (-Og -g3: dosť rýchly a laditeľný) a Release (-Os -g0: malý a bez ladiacich informácií) a čokoľvek iné zastaví konfiguráciu s chybovou hláškou. Platforma má ďalšie dva, UnitTest a IntegrationTest: v prvom z nich sa TARGET_MCU ani nevyžaduje, pretože sa zostavuje pre PC.

Predvolené flagy CMake. Toto je pasca. CMake pridáva do každej konfigurácie vlastné flagy, -O3 -DNDEBUG pre Release a -g pre Debug, pred vaše vlastné. V prvej verzii príkladu vyzeral kompilačný príkaz release takto:

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

Posledné -O vyhráva, takže to bolo -Os, ale -DNDEBUG (ktoré vypína assert()) tam bolo, hoci som oň nikdy nepožiadal. Ak chcete vedieť, čo zostavujete, vymažte predvolené hodnoty (set(CMAKE_C_FLAGS_RELEASE "")) a všetko napíšte do vlastného súboru. Spôsob, ako vidieť, čo skutočne ide do kompilátora, je compile_commands.json, ktorý vytvorí voľba CMAKE_EXPORT_COMPILE_COMMANDS: je to aj súbor, ktorý čítajú editory a clang-tidy.

Startup kód je knižnica OBJECT. Objekty takej knižnice sa dostanú do spustiteľného súboru priamo, bez spoliehania sa na to, že ich linker vytiahne z archívu.

Linker script je závislosť (LINK_DEPENDS): keď sa zmení, firmware sa zlinkuje znova.

Moduly sú knižnice​

Každý modul je statická knižnica so zoznamom svojich vlastných zdrojákov a verejných hlavičiek (článok o organizácii súborov vysvetľuje prečo). Aplikácia knižnicu zlinkuje a dostane s ňou include cestu k verejným hlavičkám a nič iné. V súbore CMake modulu nie je file(GLOB ...): zdrojáky sú vymenované jeden po druhom, takže nový súbor je viditeľná zmena v pull requeste a súbor, ktorý v priečinku zostal omylom, sa do firmvéru nedostane.

TARGET_MCU: jeden názov, viac definícií​

Buildy platformy sa spúšťajú s -DTARGET_MCU=STM32G474xE. Skript rozloží názov regulárnym výrazom a z jedného parametra vytvorí definície pre kód (STM32G474xx a STM32G4xx), ktoré hlavičky výrobcu používajú na výber správneho zariadenia. Rovnaká logika spustená na štyroch názvoch:

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 spojenie s článkom o rodinách STM32 a vetvách: rodina rozhoduje, ktorá vetva BSP je v strome, a názov MCU rozhoduje o definíciách a linker scripte.

Čo vám povie linker​

-Wl,--print-memory-usage na konci každého linkovania vypíše, koľko z ktorej pamäte je využité, -Wl,-Map=firmware.map zapíše adresu všetkého a krok po builde vypíše veľkosť:

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, ktoré som s týmito číslami urobil, ukazujú, prečo sú flagy v builde a nie v niekoho hlave.

Linker vie zahodiť to, čo nikto nevolá. S -ffunction-sections -fdata-sections je každá funkcia vo vlastnej sekcii a -Wl,--gc-sections dovolí linkeru odstrániť nereferencované. Príklad má funkciu Unused_Checksum(), ktorú nikto nevolá:

Rozdiel 48 bajtov je presne funkcia kontrolného súčtu. V reálnom projekte s knižnicou od výrobcu, ktorá má stovky funkcií a vy volíte desať, je rozdiel v kilobajtoch.

Kompilátor vie pridať pamäť za vaším chrbtom. Prvý release build príkladu mal 772 B, takmer trikrát viac než debug build (288 B). Map súbor ukázal memcpy a memset zo štandardnej knižnice. Príčina: keď je optimalizácia zapnutá, GCC rozpozná cykly v startup kóde (kopírovanie .data a nulovanie .bss) ako kopírovanie a vyplnenie a nahradí ich volaniami týchto dvoch funkcií, ktoré potom prinesú svoj kód z knižnice. Opraví to jeden flag na startup objekte a výsledok je 276 B:

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

Okrem veľkosti je tu druhý dôvod, prečo sa o to starať: startup kód beží skôr, než je pamäť inicializovaná, a čím menej knižničného kódu používa, tým menej sa môže pokaziť (pozrite si článok o tom, čo sa deje pred main()).

Po linkovaní: čo flashujete a čo testujete​

Príkaz POST_BUILD vytvorí z ELF súboru firmware.bin a firmware.hex (formáty, ktoré čítajú programátory) a vypíše veľkosť. Posledná časť príkladu je test: add_test spustí firmware v QEMU a ctest skontroluje, že vypísal očaká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 (naštartuje firmware a dostane sa do svojho main()?) a beží zlomok sekundy pri každom commite. Nenahrádza test na hardvéri, ale build, ktorý nenaštartuje, sa nájde v CI a nie pri stole. Testy modulov na PC sú iný build toho istého projektu CMake (ukazuje ho článok o Unity a CMock).

Checklist​

1. Toolchain file a CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY.
2. Flagy v jednom súbore s menami, predvolené hodnoty konfigurácií CMake vymazané.
3. Každý modul je knižnica s explicitným zoznamom zdrojákov a verejných hlavičiek.
4. -ffunction-sections -fdata-sections a --gc-sections, vždy.
5. --print-memory-usage a map súbor pri každom linkovaní, po ňom size.
6. compile_commands.json pre editor a statickú analýzu.
7. Linker script je závislosť firmvéru.
8. Smoke test v simulátore v CI.
9. Občas sa pozrite na veľkosť release buildu. Ak rastie bez dôvodu, map súbor vie prečo.

Tento článok prejde tri problémy zdieľaných dát jeden po druhom s kódom, ktorý zlyháva, a potom ukáže vzory, ktoré fungujú. Experimenty bežia na Cortex-M4 (v QEMU, na modeli dosky STM32F4) alebo na PC a výstupy sú skutočné.

Problém 1: kompilátor nevidí prerušenie​

Najjednoduchšia komunikácia medzi prerušením a hlavnou slučkou je flag. Prerušenie ho nastaví, hlavná slučka naň čaká:

#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;
}

Toto je celý program a s optimalizáciou -O2 sa nikdy neskončí. Spustil som ho v QEMU so SysTick ako zdrojom prerušenia (prerušenie sa spustí a nastaví flag) a porovnal verziu s volatile a bez neho:

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

Prečo? Pozrite sa, čo kompilátor vygeneroval pre slučku v prvej verzii:

 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

Kompilátor uvažuje iba o kóde main() a v tom kóde do dataReady nikto nezapisuje. Hodnota sa teda nemôže zmeniť, stačí ju prečítať raz a slučka sa zmení na nekonečnú. Presne to, o čo ste z jeho pohľadu požiadali. S volatile musí kompilátor premennú čítať z pamäte pri každom prechode:

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

Poučenie: každá premenná zdieľaná medzi prerušením a hlavným kódom musí byť volatile. To isté platí pre každý register periférie, a preto sú definície registrov v hlavičkách CMSIS volatile. Pamätajte, že v debug builde (-O0) to bez neho funguje a v release builde zlyhá, a preto sa chyba nájde neskoro.

Problém 2: volatile neznamená atomické​

volatile hovorí „čítaj a zapisuj pamäť zakaždým“. Nehovorí „naraz“. Nevinný riadok counter++ sú tri inštrukcie:

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

Ak prerušenie príde medzi načítaním a uložením a prerušenie tiež inkrementuje čítač, jedna z dvoch inkrementácií sa stratí: hlavný kód uloží starú hodnotu plus jedna cez hodnotu, ktorú práve uložilo prerušenie. Časová os:

Chcel som to ukázať aj na Cortex-M4 a nevyšlo to: pri 200 000 inkrementáciách s prerušením každých pár inštrukcií QEMU nestratilo nič. Pravdepodobne preto, že QEMU kontroluje prerušenia medzi blokmi preloženého kódu, takže žiadne nepristane medzi ldr a str. Je to užitočná pripomienka, že simulátor nedokazuje neprítomnosť race condition: skutočné MCU môže prerušiť po každej inštrukcii. Ten istý race na mieste, kde sa dá ľahko reprodukovať, sú dve 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)

Tretina všetkých inkrementácií sa stratí a výsledky sa líšia beh od behu. Vlákno na PC a prerušenie na MCU sú v tomto ohľade to isté: druhý tok riadenia, ktorý môže udrieť medzi dve inštrukcie. To isté platí pre všetko, čo je väčšie ako slovo CPU: 64-bitová časová pečiatka alebo štruktúra s dvoma poľami sa môže prečítať napoly stará a napoly nová (torn read).

Tri spôsoby riešenia​

1. Jeden zapisovateľ pre každú premennú (najlepší)​

Najrobustnejšie riešenie je navrhnúť dáta tak, aby každú premennú zapisovala len jedna strana. Prerušenie zapíše flag, hlavný kód ho iba číta a nemaže (alebo naopak). Bez dvoch zapisovateľov niet čo stratiť. Ak obe strany potrebujú meniť to isté, nemali by to zdieľať: každá má vlastnú premennú (čítač prerušení je isrCalls, čítač hlavného kódu je iný) a súčet urobí čitateľ.

2. Kritická sekcia​

Keď sa dvom zapisovateľom nedá vyhnúť, prerušenia sa na čas operácie zakážu. Správny spôsob je uložiť stav a obnoviť ho, a nie na konci slepo povoliť prerušenia, pretože funkcia mohla byť zavolaná s už zakázanými prerušeniami:

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 latencia: počas sekcie nemôže bežať žiadne prerušenie. Sekcia teda musí byť krátka, na pár inštrukcií, a bez volania funkcie, cyklu alebo čakania vo vnútri.

3. Atomická operácia​

Pre jedno slovo (čítač, flag s počtom) má procesor inštrukcie LDREX a STREX: uloženie uspeje len vtedy, ak sa adresy od načítania nikto nedotkol, a ak sa dotkol, cyklus sa zopakuje. Kompilátor ich za vás vygeneruje zo štandardnej operácie:

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 riadok, __atomic_fetch_add(&counter, 1u, __ATOMIC_RELAXED) (alebo atomic_fetch_add() z <stdatomic.h>). Neblokuje prerušenia, takže nepridáva latenciu. Funguje pre jednu premennú; pre dve premenné, ktoré patria k sebe, nepomôže.

Najpoužívanejší vzor: kruhový buffer​

Najčastejšia vec, ktorú prerušenie odovzdáva hlavnému kódu, je tok dát: bajty prijaté cez UART, vzorky z ADC. Prerušenie ich nemôže spracovať (musí byť krátke), a tak ich vloží do fronty a hlavný kód ich vyberie v pokojnej chvíli. Je to problém producent-konzument s jedným producentom (prerušenie) a jedným konzumentom (hlavný kód) a pre tento konkrétny prípad kruhový buffer nepotrebuje žiadny zámok:

#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

Prečo je to správne?

• head zapisuje iba producent a tail iba konzument. Nie je tu premenná s dvoma zapisovateľmi, takže sa nemôže stratiť žiadna aktualizácia: je to prvé riešenie vyššie, zabudované do štruktúry.
• Čítače sú voľne bežiace (nikdy sa neresetujú). Počet položiek je head - tail a vďaka aritmetike bez znamienka je správny aj po pretečení čítačov. Pri veľkosti, ktorá je mocninou dvojky, je pozícia jednoduchá maska namiesto delenia.
• Záleží na poradí: producent zapíše položku a potom ju zverejní posunutím head (memory_order_release) a konzument číta najprv head (memory_order_acquire) a až potom položku. Na jedinom jadre Cortex-M je jediné, na čom záleží, poradie, v akom kompilátor zapisuje, a atomiky ho zachovávajú. Na MCU s dvoma jadrami (niektoré STM32H7 majú dve) alebo s cache je ten istý kód stále správny, čo je dôvod písať ho v tejto forme a nie s volatile, ktoré náhodou funguje.
• Producent nečaká. Plný buffer znamená „zahoď položku a spočítaj ju“, pretože prerušenie nemôže na nikoho čakať. Počítadlo zahodených vám v teste povie, že buffer je primalý.

Otestoval som to dvoma spôsobmi. Na PC s dvoma vláknami, producentom a konzumentom, prejde bufferom s 16 slotmi 20 miliónov položiek:

items 20000000, order errors 0

a na Cortex-M4 v QEMU: prerušenie SysTick je producent a main() konzument, s 5000 položkami:

items received  5000
order errors    0
full buffer hits 0

Prvý test je ťažší (dve vlákna naozaj bežia paralelne na dvoch jadrách), druhý je skutočná situácia MCU. Je to tiež perfektný kandidát na unit test na PC, ako v článku o unit testovaní s Unity a CMock: modul je nezávislý od hardvéru.

Pravidlá pre obsluhy prerušení​

1. Krátke. Prečítajte register, uložte dáta, nastavte flag, zrušte pending flag, vráťte sa. Spracovanie sa robí v hlavnom kóde.
2. Žiadne čakanie, žiadna alokácia, žiadny printf. Nič, čo blokuje, trvá dlho alebo volá funkciu, ktorú nie je bezpečné volať z prerušenia (je non-reentrant, ak vo vnútri používa statický buffer).
3. Všetko zdieľané je volatile alebo atomické a každá premenná má definovaného zapisovateľa.
4. Nezdieľajte viac, než musíte. Flag alebo fronta medzi stranami, nie štruktúra s desiatimi poliami.
5. Myslite na prioritu. Prerušenie vyššej priority môže prerušiť iné prerušenie. Premenná zdieľaná medzi dvoma prerušeniami má rovnaký problém ako zdieľaná s hlavným kódom.

V Embedbits BSP majú periférne moduly (napr. USART) variant spracovania dát s pollingom, s prerušením a s DMA a variant s prerušením je presne toto: obsluha na úrovni MCAL, ktorá berie dáta z periférie a odovzdáva ich aplikácii cez buffer, kým Task modulu beží v hlavnej slučke a robí spracovanie.

Zhrnutie​

Tri druhy kódu v tomto článku mali jedno spoločné: všetky vyzerali správne.

Tlačidlo vyzerá triviálne: pin, high alebo low. Lenže mechanický kontakt poskakuje, takže pin robí 1 0 1 1 0 1, kým sa ustáli, a produkt od jedného tlačidla zvyčajne chce dve rôzne veci: krátke a dlhé stlačenie. Napísané s príznakmi a počítadlami v hlavnej slučke to skončí ako zopár ifov, ktoré od seba závisia spôsobom, ktorý po mesiaci nikto nevie vysvetliť. Konečný automat to rieši spôsobom, ktorý viete vysvetliť tabuľkou.

Šablóna v jednom odseku​

Každý stav má štyri rutiny a každá z nich má presne jednu úlohu:

Jadro automatu spúšťa Execute a CheckLeave aktuálneho stavu a keď sa stav zmenil, spustí Leave starého a Entry nového. Rutiny sa navzájom nikdy nevolajú a kód automatu neobsahuje nič iné než automat. Ak chcete vedieť, prečo je zariadenie v nejakom stave, prečítate CheckLeave predchádzajúceho.

Najprv návrh: stavy a prechody​

Úloha beží každých 10 ms a číta surový kontakt. Čas debounce je 50 ms a hranica dlhého stlačenia je 1 sekunda. Stačí päť stavov:

Písanie tabuľky je skutočná práca. Keď je kompletná, kód je len písanie na stroji. Keď nie je (čo sa stane v LONG_PRESS, keď kontakt poskakuje pri uvoľnení?), tabuľka ukáže dieru ešte predtým, než napíšete riadok v C.

Kód​

Vstup prichádza z BSP, takže modul nemá závislosť na hardvéri a dá sa testovať na PC (rovnaký seam ako v článku o unit testovaní). Port modulu tvorí Init, Task a funkcia, ktorá vráti udalosť jednorazovo:

#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ú šablónu. Je tu jedna zmena, ktorú som urobil zámerne: tabuľka rutín je indexovaná stavom a nehľadá sa v nej a enumerácia končí BUTTON_STATE_COUNT, ktorá má dve použitia.

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;

Prvým použitím je samotná tabuľka. S designated initializers nezáleží na polohe riadku, takže stav sa nedá prepojiť so zlými rutinami, keď niekto pridá riadok do stredu (šablóna potrebuje komentár „toto pole musí mať rovnaké poradie ako enum stavov“):

/* 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ým použitím je jadro automatu, v ktorom tá istá konštanta nahrádza natvrdo zapísaný „posledný stav“ pri 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();
    }
}