Ця стаття показує, як перетворити цей цикл на рядок вихідного коду, на двох реальних прикладах, які я запускав у QEMU (моделі плати з STM32F4) і досліджував за допомогою GDB: виклик NULL-вказівника на функцію та запис за адресою, де нічого немає. Усі виводи справжні.

Що робить ядро, коли стається збій​

На Cortex-M процесор не падає мовчки. Коли він не може продовжувати (недійсна інструкція, помилка шини, недозволений доступ), він переходить до винятку (exception) і робить дві речі, важливі для налагодження:

1. Заштовхує вісім регістрів на стек: R0, R1, R2, R3, R12, LR, PC і xPSR. Збережений PC — це інструкція, що спричинила збій, а збережений LR вказує, хто викликав функцію, у якій стався збій.
2. Встановлює біти в регістрах стану збоїв, які показують, який це був збій: CFSR (configurable fault status, що складається з трьох частин для збоїв пам'яті, шини та використання), HFSR (hard fault status) і регістри адрес MMFAR та BFAR з адресою, до якої було звернення.

Збої пам'яті, шини та використання мають власні обробники, але після скидання вони вимкнені, тому кожен збій ескалується до HardFault. Ось чому один обробник бачить усе, а біт FORCED в HFSR повідомляє, що це сталося.

Обробник, який читає регістри​

Єдина складність — дістатися до стека, де лежать регістри. У ядра є два вказівники стека (MSP для винятків і основного коду, PSP для задач операційної системи), і біт 2 значення в LR на вході у виняток показує, який із них використовувався. Це потрібно зробити до того, як компілятор використає стек для власних потреб, тому обробник — це коротка функція на асемблері (naked: без пролога), яка передає вказівник у функцію на 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"
    );
}

Погляньте на три частини. Структура stackFrame_t — це розташування восьми регістрів у порядку, в якому їх заштовхує ядро. Функція HardFault_Report() копіює їх (разом з регістрами стану) у глобальну змінну faultInfo, друкує короткий звіт, а потім навмисно залишається в циклі, щоб налагоджувач міг підключитися й подивитися на змінну. Асемблерна заглушка вибирає правильний стек і переходить до функції. У продукті звіт записувався б у пам'ять, що переживає скидання, а прошивка самостійно перезавантажувалася б, але принцип той самий.

Приклад 1: виклик NULL-вказівника​

Ось застосунок із помилкою. Callback реєструється пізніше, а код, який його викликає, виконується раніше:

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

Програма друкує start, а потім звіт:

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

Тепер його розбір, значення за значенням:

• PC = 0x00000000: процесор спробував виконати інструкцію за нульовою адресою. Майже завжди це означає перехід через NULL-вказівник на функцію або повернення за пошкодженою адресою.
• CFSR = 0x00020000: біт 17 — це INVSTATE, «недійсний стан». Процесор спробував виконувати код у стані ARM, якого в Cortex-M немає. Причина — в xPSR: його біт 24 — це біт T (Thumb), і тут він нульовий (0x60000000). Адреса Thumb-функції має встановлений наймолодший біт, а NULL його не має, тож перехід через вказівник скинув біт T. Нульовий біт T — типовий відбиток переходу на NULL.
• HFSR = 0x40000000: біт 30 — це FORCED, збій було ескальовано до HardFault зі збою використання (usage fault), який не ввімкнено.
• LR = 0x08000115: адреса повернення з встановленим наймолодшим бітом (Thumb). Це адреса викликача, 0x08000114, і саме там помилка.

З налагоджувачем останній крок займає лічені секунди. QEMU чекає на GDB (-S -gdb tcp::1234), і сесія виглядає так:

(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 дає функцію, list * дає рядок (той, що після виклику, бо це адреса повернення), а дизасемблер показує пару інструкцій, яка і є самою помилкою: завантаження нуля в r3 та blx r3, виклик через регістр, що містить NULL. Зверніть увагу на r3 = 0x0 у збережених регістрах. Без налагоджувача ту саму відповідь дає одна команда toolchain, якій потрібні лише адреса зі звіту та файл з налагоджувальною інформацією (-g):

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

Приклад 2: запис за адресою, де нічого немає​

Я змінив один рядок застосунку: замість callback функція пише за адресою 0xA0000000, де в моделі чипа нічого не відображено. Звіт:

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

Цього разу PC — це дійсна адреса у flash, біт T встановлено (0x21000000), а CFSR інший: 0x8200 — це два біти, 9 (PRECISERR, точна помилка шини даних) і 15 (BFARVALID, регістр BFAR містить адресу). У 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 — це адреса, за якою програма намагалася писати, PC — інструкція, що намагалася це зробити. Разом вони кажуть: «ця інструкція писала за цією адресою», і це повний опис проблеми. Якщо адреса мала (0x00000008), це NULL-вказівник на структуру, і ви звертаєтеся до її поля. Якщо вона схожа на дані (0x20000000 і трохи більше), то це стек або буфер, який ви переповнили.

Біти CFSR, які ви зустрінете​

Регістр є комбінацією трьох регістрів (кожен має власний байт або два байти). Ось ті, які ви бачитимете найчастіше (два, які я спостерігав у прикладах, виділено):

Що зазвичай стоїть за HardFault​

Я продемонстрував перший рядок таблиці та принцип другого (помилка шини з адресою в BFAR). Решта рядків — це підсумок типових причин, вони випливають зі значення бітів у reference manual ядра.

Практика​

1. Ніколи не залишайте типовий обробник порожнім циклом. Обробник вище займає близько тридцяти рядків і перетворює збій на звіт із місцем у коді. Додайте його до startup-коду проєкту один раз.
2. Зберігайте налагоджувальну інформацію у файлі, який архівуєте разом з релізом (-g і .elf), щоб адресу зі звіту з поля можна було перетворити на рядок, навіть якщо прошивка постачається зі stripped-символами. Це ще одна причина для відтворюваної збірки: адреса має сенс лише для точного бінарного файлу, який її створив.
3. Вмикайте тонші збої (біти в SHCSR), коли хочете окремі обробники UsageFault, BusFault і MemManage. Звіт буде багатшим, бо регістри стану не спільні.
4. Зберігайте звіт у пам'яті, що переживає скидання (секція, яку startup-код не очищує, див. статтю про те, що відбувається перед main()), перезавантажуйтеся й надсилайте його після перезапуску. Звіт з пристрою в полі вартий більше за сотню здогадок.
5. Запобігайте тому, чому можете. NULL-виклик у прикладі — це дефект, який виявили б правила MISRA та unit-тест модуля (вказівник має бути встановлений до першого виклику), а переповнення стека — це те, для чого потрібно знати використання стека (правило проти рекурсії).

Та сама сесія на платі​

Я користувався QEMU, бо йому не потрібна плата, а його GDB-сервер (-S -gdb tcp::1234) поводиться так само, як сервер налагоджувального зонда: команди в прикладах — це команди, які ви вводите із зондом. Платформа має артефакт для набору інструментів probe-rs (набір інструментів налагодження для ARM-цілей через налагоджувальний зонд, із DAP-сервером), який є способом підключити GDB або IDE до справжньої плати. Я не запускав його для цієї статті, бо в моєму середовищі немає зонда.

Підсумок​

1. HardFault — не загадка: ядро заштовхнуло регістри та встановило біти стану.
2. Обробнику потрібно знайти правильний стек (EXC_RETURN) і прочитати фрейм, CFSR, HFSR та BFAR.
3. PC і LR дають місце, CFSR — вид збою, BFAR — адресу.
4. PC = 0 з INVSTATE — це перехід на NULL, і це показує біт T в xPSR.
5. Зберігайте .elf, і адреса зі звіту з поля стане рядком коду.

Я покажу два експерименти, які провів: той самий вихідний код тесту, що проходить на ПК і падає на Cortex-M4, та прошивку, яка пише в регістри USART за справжніми адресами STM32F4, а її текст з'являється в терміналі. Наприкінці — чесний перелік того, чого симулятор вам не скаже.

Де це вписується​

Середній рівень пропускають найчастіше, хоча його додати найдешевше до CI, який уже збирає прошивку: симулятор — це виконуваний файл, який ви запускаєте з файлом, створеним вашою збіркою.

Інструмент у моїх експериментах — QEMU 8.2.2 з машиною netduinoplus2, моделлю плати з STM32F405 (Cortex-M4 з картою пам'яті справжнього чипа: flash за адресою 0x08000000, RAM за 0x20000000, периферія за своїми справжніми адресами). Платформа має артефакт для іншого симулятора, Renode, і я повернуся до нього наприкінці.

Експеримент 1: тест, що проходить на ПК і падає на MCU​

Невеликий модуль із двома функціями, які є в кожній прошивці: перетворення часу та перевірка отриманого байта.

#include "Conversions.h"

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

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

Обидві функції виглядають правильно, і обидві протестовані на ПК. Вихідний код тесту однаковий для обох платформ: відрізняється лише вивід. Файл Platform.h друкує через printf на ПК і через semihosting (запит до симулятора або налагоджувача) на цільовій платформі, а код завершення тесту показує, чи він пройшов:

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

На ПК:

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

Той самий код, зібраний arm-none-eabi-gcc для Cortex-M4 і запущений у 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

Дві помилки, і обидві невидимі на ПК:

• long має іншу ширину. На 64-бітному Linux-ПК long має 64 біти, на Cortex-M — 32. 3 000 000 ms * 1000 дорівнює 3 000 000 000, що не вміщується в знакове 32-бітне число (найбільше — 2 147 483 647), тож результат неправильний, а в C це ще й undefined behavior.
• char має іншу знаковість. Стандарт C залишає відкритим питання, чи є звичайний char знаковим. На x86 є, тож (char)0xFF дорівнює -1, і перевірка receivedByte < 0 працює. На ARM він беззнаковий, тож (char)0xFF дорівнює 255, і порівняння ніколи не буває істинним. ARM-компілятор навіть про це повідомляє, і лише там:

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

Обидві проблеми стосуються переносимих типів, що є темою правила 4.6 у статті про MISRA: використовуйте типи із заданими розміром і знаковістю. Виправлена версія використовує uint64_t для часу та uint8_t для байта:

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

і ті самі чотири перевірки тепер проходять на обох платформах, з кодом завершення 0 на обох. Перша версія не була помилкою тесту, і тест на ПК не був хибним: він просто тестував іншу програму.

Код завершення — це вся інтеграція з CI. Симулятор завершується з кодом, який прошивка передає у виклик semihosting, тож add_test у CMake (див. статтю про CMake для прошивок) падає, коли падає тест на цільовій платформі:

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

Експеримент 2: регістри периферії​

Симулятор також моделює периферію, а отже, може виконуватися й код, найближчий до апаратної частини. Ось прошивка, яка надсилає текст через USART1 мікроконтролера STM32F4, написана на рівні регістрів зі справжніми адресами (без бібліотек, без startup, окрім коду зі статті про те, що відбувається перед 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

Текст з'явився в терміналі симулятора: прошивка ввімкнула тактування периферії в RCC, увімкнула USART та його передавач, дочекалася прапорця TXE і записала в регістр даних — точно так, як зробила б на платі, а модель USART передала байт на послідовний порт. Це тест драйвера проти моделі інтерфейсу регістрів. Якщо драйвер чекає на прапорець, який ніколи не приходить, тест знайде це за таймаутом, а не за столом з осцилографом.

Чого симулятор вам не скаже​

Симулятор — це модель, і кожна модель має межі. Кілька з них я зустрів в експериментах цієї серії:

• Таймінги не справжні. QEMU виконує інструкції так швидко, як дозволяє ПК, і не рахує такти справжнього ядра. Тест, який має довести, що «переривання обслуговується за 5 мікросекунд», у ньому неможливий.
• Переривання приходять в інших місцях, ніж на MCU. У статті про переривання втрачене оновлення спільного лічильника не з'явилося в QEMU за 200 000 спроб, бо QEMU доставляє переривання між блоками транслюваного коду. Справжній MCU може перервати після кожної інструкції. Симулятор не доводить відсутності гонки.
• Існує лише змодельована периферія. Модель STM32F405 має USART, але інший чип може мати периферію, якої в моделі немає або вона спрощена: регістри є, аналогової частини немає.
• Електричного світу бракує: брязкіт контактів, шум на вході ADC, просадка напруги. Усе, що приходить ззовні, — це те, що ви самі вкладаєте в модель.

Тож симулятор не замінює ні unit-тести (вони швидші й тестують логіку в ізоляції), ні апаратні тести (вони тестують реальність). Він знаходить те, що між ними: компілятор цільової платформи, типи, startup, карту пам'яті, драйвер проти моделі регістрів — і робить це за кілька секунд на кожен коміт.

Renode​

Платформа має артефакт для Renode, open-source фреймворку симуляції та віртуальної розробки від Antmicro, який постачається разом із renode-test, його тестовим раннером на основі Robot Framework, що використовується для інтеграційних тестів симульованої прошивки. Я не запускав його для цієї статті (реліз не вдалося завантажити в моєму середовищі), тому лише переказую те, що сказано в його документації, і не порівнюю його з QEMU. Структура такого тесту та сама, що й вище: справжній ELF, модель апаратної частини, вердикт і код завершення для CI.

Чек-лист​

1. Збирайте тест для цільової платформи компілятором цільової платформи й запускайте його в симуляторі, на додачу до ПК.
2. Використовуйте один вихідний код тесту для обох, з тонким шаром (Platform.h) для виводу та завершення.
3. Код завершення симулятора — це результат тесту, тож CI більше нічого не потрібно.
4. Використовуйте типи із заданими розміром і знаковістю (uint32_t, uint8_t) та попередження компілятора цільової платформи: другу помилку вище (char) знайшов би -Wtype-limits, якби хтось дивився на вивід ARM-збірки.
5. Запишіть, що симулятор довести не може (таймінги, гонки, аналоговий світ), і залиште це апаратним тестам.

Відтворювана збірка має просте визначення: ті самі вхідні дані дають ті самі байти. Ця стаття показує, які вхідні дані має збірка firmware, як платформа Embedbits їх фіксує (Artifacts Handler), і експеримент, який я провів: дві збірки того самого коду в двох теках у два різні моменти дають два різні бінарні файли. А потім, після трьох змін, вони дають той самий — до останнього біта.

Вхідні дані збірки​

Збірка — це функція. Що в неї входить?

Перше, третє й четверте лежать у Git, тож зафіксовані за дизайном. Інструменти та середовище — це місця, де збірка зазвичай ламається, і кожне має власну відповідь.

Інструменти: Artifacts Handler​

«Встановіть GCC 13.2 і Ninja 1.12» у README — це речення, якого ніхто не виконує буквально. Платформа розв'язує це, роблячи інструменти частиною проєкту. Artifacts Handler — це скрипт CMake, який читає перелік інструментів та їхніх версій із файлу ArtifactsConfig.txt і готує їх. Його документація каже, що єдине програмне забезпечення, потрібне користувачеві, — це Git і CMake, а кожен інший компонент збірки постачає handler. По кроках:

1. Клонувати кореневий репозиторій артефактів (без підмодулів, щоб заощадити трафік).
2. Знайти в ньому артефакт (кожен інструмент — підмодуль, назви порівнюються без урахування регістру).
3. Перейти на запитану версію (shallow clone, --depth=1). Релізи позначені версією та операційною системою (Win, Unix, DarwinARM).
4. Встановити його: розпакувати архів у теку кешу.
5. Ініціалізувати його: здебільшого він ставить теку інструмента на початок PATH, тож інструмент проєкту перемагає будь-який інструмент, встановлений у системі.

Конфігурація має один рядок на інструмент, name;version;handler version, наприклад рядки з документації платформи:

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

Перше число — версія самого інструмента (бінарного файлу), друге — версія скрипта handler цього артефакту (вона може змінюватися незалежно, наприклад, коли виправляють спосіб встановлення PATH). Кеш має одну теку на інструмент і на версію, тож кілька версій співіснують поруч, а проєкт, якому потрібна старіша, не заважає проєкту, якому потрібна новіша.

Чому не latest​

Handler також приймає latest замість числа. Це зручно й руйнує всю ідею. Я запустив handler з рядком ninja;latest;latest, і він надрукував, у що це перетворилося 5 жовтня 2026 року:

-- 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.

(Запуск зупинився на завантаженні релізу, бо моє середовище не може дістатися GitHub API, але визначення версії відбулося.) latest — це рухома ціль: за документацією, перелік версій завантажується раз на добу, тож той самий файл сьогодні дає 1.13.2, а після наступного релізу — щось інше. Збірка, правильна сьогодні, завтра може бути іншою збіркою, і ніщо у вашому репозиторії про це не скаже. Тому правило просте: latest — для спроби нової версії, а випущений проєкт фіксує кожне число.

Інші налаштування, що допомагають​

• Офлайн-режим (-DOFFLINE_MODE=true): перевіряється лише локальний кеш, нічого не завантажується. Це спосіб довести, що збірка не залежить від мережі, і спосіб збирати там, де мережі немає.
• Розташування кешу (ARTIFACTS_HANDLER_CACHE_PATH) і кореневого репозиторію (ARTIFACTS_HANDLER_ROOT_REPO_URL) можна задати у файлі конфігурації, в середовищі або в командному рядку. Компанія може тримати власне дзеркало артефактів, тож збірка не залежить і від публічного сервера.
• Контрольна сума. Кожен реліз артефакту публікується з файлом SHA-256 поруч з архівом, тож пошкоджений або підмінений файл не приймається мовчки.

Інструменти — перша половина відповіді. Друга половина — те, що ви можете перевірити самі, наведеною нижче командою.

Середовище: експеримент​

Я взяв приклад проєкту зі статті про CMake і додав файл, який більшість firmware мають у тій чи іншій формі: інформацію про збірку. Він зберігає час збірки та шлях до вихідного файлу, бо колись комусь захотілося бачити у відлагоднику «коли це зібрано»:

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

Потім я зібрав той самий код двічі: у двох різних теках (a і b), другу — на три секунди пізніше. Команда strings, застосована до двох бінарних файлів, показує, що всередині:

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

і SHA-256 двох файлів firmware.bin відрізняються:

f2366319462b6fee...
d634c24c3c431799...

Дві збірки одного коду, два різні бінарні файли. Час очевидний, але шлях — це те, що люди забувають: __FILE__ (а також assert() і налагоджувальна інформація) записує в програму повний шлях до файлу, а шлях різний на ПК кожного розробника і в кожному завданні CI. Бінарний файл, зібраний у /home/anna/project, і той самий, зібраний у /builds/job-4711/project, — це два різні файли.

Три зміни​

1. Приберіть годинник. Макросам __DATE__ і __TIME__ немає місця у firmware, яке має бути відтворюваним. Компілятор може це забезпечити, щоб ніхто не додав їх назад випадково:

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. Версія — це вхід. Якщо ви хочете знати «що це за firmware», збірка отримує відповідь ззовні: версію, тег або хеш коміту, який система збірки передає як визначення. Той самий код має ту саму версію, отже, ті самі байти:

#ifndef BUILD_VERSION
#define BUILD_VERSION "unknown"
#endif

const char buildVersion[] = BUILD_VERSION;

3. Приберіть шляхи. Опція -ffile-prefix-map=OLD=NEW замінює префікс кожного шляху, який GCC записує у вивід (__FILE__, налагоджувальна інформація, assertions). Тека з вихідним кодом проєкту замінюється крапкою:

# 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}=.)

З цими трьома змінами та сама перевірка дає:

first : 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
second: 1bedc9d2b1d78452a77fa3440851d5ed3d9f6568d96edd4c4a18be3b828dc313
REPRODUCIBLE

.bin ідентичний, як і .elf, у release (-Os -g0) і також у debug-збірці (-Og -g3), чия налагоджувальна інформація повна шляхів. З -ffile-prefix-map strings бінарного файлу показує ./Application/BuildInfo.c і версію 1.2.3, і нічого про ПК, що його зібрав.

Тест, який не старіє​

Недостатньо зробити збірку відтворюваною один раз, бо перший же __TIME__, який хтось додасть, її зруйнує. Тож зробіть із цього тест: зберіть код двічі й порівняйте. Це скрипт, яким я отримав числа вище; він копіює проєкт у дві теки, збирає обидві з паузою між ними та порівнює 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

Запущений у CI при кожному злитті, він є вартовим. Я використав його й на зламаній версії інформації про збірку, щоб переконатися, що він може впасти, і він упав (NOT REPRODUCIBLE, код виходу 1, два різні хеші). Тест, який ніколи не падав, — це тест, якого ви не знаєте.

Що ще ламає відтворювану збірку​

Я перевірив три речі вище. Далі йдуть інші добре відомі джерела проблем, про які варто пам'ятати (у прикладі вони мені не знадобилися, тож я їх лише називаю):

• Порядок файлів, що походить від file(GLOB ...) або зі списку теки. Вихідні файли слід перелічувати явно, як у файлах CMake модулів платформи.
• Позначка часу в архіві (статична бібліотека, створена ar). Сучасні версії інструментів мають детермінований режим, але старий toolchain може його не мати.
• Згенерований код. Моки й раннери unit-тестів або linker script, згенерований для MCU, мають генеруватися однаково з тих самих вхідних даних. Правила — сортування та жодних позначок часу у виході.
• Сам компілятор. Та сама версія того самого компілятора з двох джерел (пакет дистрибутива та архів вендора) може відрізнятися бібліотеками, які підключає. Це причина брати компілятор з одного місця, у чому й полягає вся суть артефактів.
• Збірка з різною кількістю потоків. Коректна система збірки дає той самий результат з -j1 і -j16, і тест на це — дешеве доповнення до наведеного вище.

Чекліст​

1. Кожен інструмент зафіксований на точній версії в ArtifactsConfig.txt. Жодного latest у релізі.
2. Підмодулі (BSP, платформа) зафіксовано комітами, а оновлення — це видимий коміт.
3. Ніщо у firmware не залежить від часу чи шляху: -Werror=date-time, -ffile-prefix-map.
4. Версія — параметр збірки, виведений з тега, і зберігається у firmware.
5. CI збирає двічі й порівнює. Також час від часу збирає офлайн, із кешу.
6. Поставлений бінарний файл зберігається разом із його SHA-256 і тегом, тож на запитання «чи це той самий файл» є відповідь без перезбирання.

Нагорода — речення, яке ви скажете по телефону замовнику: «Я зібрав саме ваше firmware, і помилка в ньому (не) є».

Код модуля цитується з гілки STM32H5 репозиторію Bsp-Mcal-Gpio. Приклади, що його використовують, були скомпільовані та запущені з справжніми Gpio_Port.h і Gpio_Types.h та невеликою заглушкою реалізації, щоб API можна було спробувати на ПК.

Увесь інтерфейс на одному екрані​

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

Кожне рішення нижче можна прочитати з цього переліку.

1. Пін — це пара ідентифікаторів, а не макрос вендора​

Драйвери вендора адресують пін за допомогою вказівника на блок регістрів і бітової маски: LL_GPIO_SetOutputPin(GPIOA, LL_GPIO_PIN_5). Натомість MCAL приймає два переліки, gpio_PortId_t і gpio_PinId_t:

Gpio_Set_PinLevel( GPIO_PORT_A, GPIO_PIN_ID_5, GPIO_PIN_LEVEL_HIGH );

Чому: код над MCAL не потребує жодного заголовка вендора, він не знає, що таке GPIOA (адреса блоку регістрів вендора), а ідентифікатор можна перевірити на діапазон, чого не можна зробити з довільним вказівником. Кожен перелік закінчується лічильником (GPIO_PORT_CNT, GPIO_PIN_ID_CNT), який є верхньою межею для перевірки на початку функції.

Ціна: таблиця, що перетворює ідентифікатор на блок регістрів (у Gpio.c, один рядок на порт), і ще один рівень непрямості. Таблиця також розв'язує власну проблему: MCU одного сімейства мають різну кількість портів, тож записи загорнуто в #if defined(GPIOK) (див. статтю про сімейства).

2. Кожна функція, що може зазнати невдачі, повертає стан, а результати виходять через вказівник​

Усі функції, окрім Deinit, Task і геттера версії, повертають gpio_RequestState_t, а геттери передають значення через параметр-вказівник:

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

Чому: значення, що повертає геттер, не може нести і значення, і інформацію про те, що значення недійсне (GPIO_PIN_LEVEL_LOW — дійсний рівень, тож повернений 0 неоднозначний). Зі станом у поверненому значенні та даними в параметрі недійсний порт, недійсний пін чи вказівник NULL — це помітна помилка, а не мовчки хибний рівень. * const у сигнатурі говорить, що функція не змінює вказівник, лише дані за ним.

Ціна: два рядки замість одного при кожному використанні. А стан має два значення (GPIO_REQUEST_OK, GPIO_REQUEST_ERROR), тож викликач знає, що сталася помилка, але не чому. Для GPIO цього достатньо, бо причин лише кілька (недійсний ідентифікатор, NULL), і всі вони — помилки програмування. Для периферії з реальними збоями (тайм-аут I2C, помилка шини) викликачеві потрібно більше, і звичайна відповідь — багатший перелік.

Правило з статті про MISRA, яке тут діє, — 17.7 (повернене значення використовується): інтерфейс полегшує його дотримання, бо кожна функція, що може зазнати невдачі, повідомляє про це значенням, на яке треба подивитися.

3. Пін налаштовується даними, а не послідовністю викликів​

Є структура конфігурації з усім, що описує пін, і одна функція, яка її застосовує:

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;

Чому: знання про плату тоді живе в таблиці, а код, що її застосовує, однаковий для кожної плати. Погляньте на приклад, який я скомпілював і запустив: плата — це два записи, а ініціалізація — цикл.

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

Оскільки таблиця — це дані, нова ревізія друкованої плати змінює рядок у таблиці й нічого в коді. В архітектурі Embedbits це завдання шару HAL: він тримає таблиці й використовує MCAL, щоб їх застосувати.

Ціна: структура має вісім полів, і кожен запис має заповнити всі (designated initializers роблять це читабельним, а пропущене поле дорівнює нулю, що не завжди розумне значення). Тому функція Get_DefaultConfig, яку мають деякі інші модулі, — корисний супутник.

4. Полярність сигналу — властивість піна, а не коду​

Структура має поле PinActiveLevel, а також функції Gpio_Set_PinStateActive() і Gpio_Set_PinStateInactive(), які приймають полярність як параметр. Причина — простий факт електроніки: світлодіод можна під'єднати до землі (він світиться при високому рівні) або до живлення (він світиться при низькому рівні), а сигнал chip-select зазвичай active low. Якщо код каже Gpio_Set_PinLevel(..., HIGH) для «світлодіод увімкнено», він правильний для однієї плати й хибний для наступної.

З полярністю в таблиці застосунок каже «увімкнено», а таблиця — що це означає. У наведеному вище прикладі світлодіод під'єднано до живлення, тож PinActiveLevel — це GPIO_PIN_LEVEL_LOW, і тест підтверджує, що робить пін:

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. Переліки — це константи вендора​

Типи не вигадують власних чисел, вони є числами драйвера вендора:

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;

Чому: перетворення з типу MCAL у значення, яке хоче функція LL, безкоштовне: немає switch, немає таблиці й немає способу зробити друкарську помилку в перекладі. Значення констант різняться від сімейства до сімейства, і це сховано в одному #include порту RAL (специфічний для сімейства Stm32_gpio.h).

Ціна: Gpio_Types.h, публічний заголовок, включає заголовок RAL, тож константи вендора просочуються в заголовки, які бачать користувачі модуля. Альтернатива — тип із власними значеннями й таблицею перекладу у файлі .c, що коштує коду й місця для помилки, але тримає вендора поза публічними заголовками. Це рішення — компроміс, і добре знати, що воно таке.

6. Той самий життєвий цикл, що й у кожного іншого модуля​

Gpio_Get_ModuleVersion(), Gpio_Init(), Gpio_Deinit() і Gpio_Task() походять із шаблону, з якого починається кожен модуль (див. статтю про організацію файлів). Різниця в єдиному місці, де вона має сенс: Gpio_Init() не void, вона приймає конфігурацію піна. Модуль GPIO не знає плати, тож «ініціалізувати модуль» не має сенсу без запитання «який пін?». Єдиний життєвий цикл, який гнеться там, де цього вимагає природа модуля, кращий за життєвий цикл, нав'язаний модулю, якому він не підходить.

7. Порядок кроків — частина інтерфейсу​

Погляньте на коментар до 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.
 */

Режим піна, тобто крок, який насправді підключає вихідний драйвер до виводу, — останній. Якби режим ішов першим, пін на мить видавав би рівень, який вихідний регістр мав після скидання (зазвичай низький), а потім стрибав би на правильний: імпульс на лінії, що може бути chip-select, скиданням іншої мікросхеми або затвором транзистора. Такий glitch невидимий у відлагоднику й видимий на осцилографі. Це хороший приклад правила проєктування API: коли порядок кроків важливий для апаратури, функція, що їх виконує, має володіти порядком, щоб користувач не міг його переплутати.

Друге речення коментаря, «stops at the first failed step», — теж проєктне рішення: функція не намагається продовжувати після помилки і повертає стан кроку, що зазнав невдачі.

8. Хибний аргумент — це помилка, яку бачить викликач, а не аварія​

Функції перевіряють свої аргументи, а відповідь — це стан:

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

(Це тест моєї заглушки, але справжня Gpio_Init() робить те саме для NULL: усе тіло знаходиться всередині if( GPIO_NULL_PTR != gpioConfig ).) Константи _CNT тут мають друге завдання: GPIO_PORT_CNT — це перше значення, яке не є дійсним портом, тож перевірка — це одне порівняння. У firmware немає кому показати повідомлення, а assert, що зупиняє програму, зазвичай хибна відповідь для робочої збірки. Помилка, що піднімається до викликача, який знає, що робити (і до модуля над MCAL, який знає, що критично), — краща відповідь.

До чого б я повернувся​

Чесний огляд дизайну завжди має перелік, і цей має два пункти, що походять зі статті про MISRA:

• Gpio_Init( gpio_Config_t *gpioConfig ) лише читає структуру, тож параметр міг би бути const gpio_Config_t * (Rule 8.13). Сигнатура говорила б, що функція не змінює конфігурацію, а таблиця плати могла б бути const і жити у flash замість RAM.
• Двозначний gpio_RequestState_t однаковий у кожному модулі (його генерує шаблон). Це просте й єдине рішення, правильне для GPIO, а модулям із реальними збоями рано чи пізно знадобиться більше.

Принципи коротко​

1. Ховайте апаратуру, а не намір. Користувач каже який пін і яка полярність, а не який регістр.
2. Робіть недійсний стан видимим. Статус для всього, що може зазнати невдачі, а вихідні дані — лише за успіху.
3. Кладіть знання в дані. Плата — це таблиця, яку читає цикл.
4. Нехай функція володіє порядком, коли апаратура про нього дбає.
5. Тримайте інтерфейс єдиним і чесно кажіть, де він гнеться (Init з параметром) та де абстракція протікає (константи вендора в типах).

Інтерфейс має двох читачів: користувача сьогодні й супровідника наступного року. Наведені вище рішення написані для обох, а коментарі в заголовках — доказ того, що хтось подумав про другого.

Ця стаття показує, як у моїх проєктах виглядає задокументований модуль, як його генерують і як зробити документацію частиною CI, яку не можна оминути. Приклади зібрано з Doxygen 1.9.8 та Graphviz, а виводи - справжні.

Що документувати, а що ні​

У моєму стилі кодування цьому присвячено один абзац: коментарі у стилі Doxygen для всіх публічних функцій, типів і макросів, англійською, короткі й точні, чому, а не що. Кілька прикладів різниці:

Перша колонка повторює назву функції, яку читач і так бачить. Друга каже те, чого читач не бачить: одиницю виміру, допустимий діапазон, хто володіє пам'яттю, чи записується вихідне значення у випадку помилки, звідки можна викликати функцію, що треба зробити перед цим. Для embedded-інтерфейсу це також місце для інформації, яку небезпечно вгадувати: чи безпечно викликати з переривання, як довго функція може блокувати, чи може вказівник бути NULL.

Модуль у файлах платформи​

Шаблони EmBi_Platform, з яких починається кожен модуль, мають однаковий скелет документації: заголовок файлу з \author, \file, \ingroup та \brief, а над кожною функцією блок з \brief, описом і \return. Шаблон скінченного автомата додає \pre для передумов і блок \par Used global variables зі списком змінних, які функція читає (in), записує (out) або й те, й інше (in,out). Це напрочуд корисний вид документації: потік даних функції в трьох рядках.

Увесь модуль - це одна група в Doxygen. \ingroup Temperature у кожному файлі каже, що файл належить модулю, а сама група визначається один раз, у 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 */

Типи мають короткий опис самого типу та кожного значення (коментар /**< ... */ після члена документує цей член у тому самому рядку):

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

Генерація​

Doxygen налаштовується файлом з кількома сотнями опцій. Писати його вручну - помилка, якої легко уникнути: платформа має цей файл як шаблон (Doxyfile.in в артефакті Doxygen) і заповнює його зі змінних CMake, а проєкти задають лише ті, що відрізняються від типових. Те саме можливо й за допомогою власного модуля CMake, і ось уся конфігурація прикладу:

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

а збірка - це одна ціль:

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

Результат - тека зі сторінками HTML. Група модуля з файлами, що до неї належать, та описом із port-файлу виглядає так:

Doxygen також малює граф включень (include graph) кожного файлу, а також граф викликів (call graph) і граф викликачів (caller graph) кожної задокументованої функції (HAVE_DOT, Graphviz: ось чому платформа має для нього артефакт). На графи включень варто час від часу поглядати: стрілка від файлу застосунку до внутрішнього заголовка модуля - це та сама проблема, яку описує стаття про організацію файлів, лише побачена згори.

Документація як тест​

Саме ця частина змінює дисципліну. Чотири опції перетворюють відсутню документацію із «варто б» на «збірка червона»:

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)

З FAIL_ON_WARNINGS Doxygen проходить усе, виводить усі попередження й лише потім завершується з помилкою (простий YES зупиняється на першому). Я спробував: видалив опис Temperature_Task() та \param у Temperature_Get_Value() з port-файлу, і збірка відповіла:

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.

(Код завершення команди - 1, тож CI червоний.) Коли описи повернуто, та сама збірка завершується без жодного виводу й з кодом 0. Нова функція без коментаря тепер не може випадково потрапити в головну гілку, і нікому не треба бути тим, хто пам'ятає про це на рев'ю.

Що містить добра документація інтерфейсу​

Для кожної функції публічного інтерфейсу перевірте список:

1. Що вона робить - одним реченням, із дієсловом (\brief).
2. Параметри: напрямок ([in], [out], [in,out]), одиниця виміру, діапазон, чи дозволено NULL.
3. Значення, що повертається: кожне можливе значення та що воно означає.
4. Передумови (\pre): що треба зробити раніше, наприклад ініціалізацію.
5. Контекст: чи можна викликати з переривання, чи блокує, скільки часу виконується.
6. Побічні ефекти: що ще вона змінює (глобальний стан, периферію).

Якщо функція не має відповіді на одне з цих запитань, відповідь лежить у коді, і читач мусить його читати. Це ознака того, що інтерфейс не завершений, а вправа з написання коментаря часто й виявляється моментом, коли ви це помічаєте.

Де це вписується в платформу​

Кожен модуль платформи має в своєму CMakeLists.txt виклик, який реєструє його теку для документації (коли артефакт Doxygen доступний у проєкті), а кореневий білд має опцію DOXYGEN_ENABLED. Отже, документація всього firmware генерується тією самою збіркою, що й firmware: -DDOXYGEN_ENABLED=ON. Артефакти (Doxygen і Graphviz) завантажуються у версії, яку зафіксував проєкт, тому сторінки сьогодні й наступного року виглядають однаково.

Чекліст​

1. Кожна публічна функція, тип і макрос має опис. Внутрішні - лише там, де не очевидно.
2. Опис каже те, чого читач не бачить у сигнатурі: одиниці, діапазони, контекст, помилки.
3. Одна група на модуль (\defgroup у port-файлі, \ingroup в інших).
4. WARN_IF_UNDOCUMENTED, WARN_NO_PARAMDOC і FAIL_ON_WARNINGS у CI.
5. Графи ввімкнені, і хтось час від часу дивиться на граф включень застосунку.
6. Документація генерується тією самою збіркою, що й firmware, із зафіксованими інструментами.

Система збірки платформи Embedbits (EmBi_Platform) зроблена на CMake, і ця стаття пояснює елементи, потрібні кожній embedded-збірці на CMake, на невеликому проєкті, який я зібрав і запустив: toolchain-файл, прапорці з іменами, типи збірки, модулі як бібліотеки, linker script, файли після лінкування та тест, що запускає firmware в симуляторі. Усі числа й виводи - справжні.

Два шари: проєкт і платформа​

Платформа ділить збірку на дві частини, і цю ідею варто запозичити навіть для невеликого проєкту. Кореневий CMakeLists.txt продукту - це мінімальна точка входу, а все складне живе в окремому скрипті, який версіонується і є спільним (підмодуль Git) і який корінь підключає:

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

Скрипт платформи знає типи збірки (Debug, Release, UnitTest, IntegrationTest), перевірки параметрів, toolchain, шляхи включення та реєстрацію модулів. Продукт заповнює лише те, що специфічне для нього. Виправлення збірки - це тоді нова версія підмодуля, а не правка десяти продуктів. Приклад нижче містить обидві частини в одному проєкті для стислості, але зберігає той самий поділ: cmake/ - це «платформа», а CMakeLists.txt - «продукт».

Приклад проєкту​

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-файл: компілятор - це не PC​

CMake припускає, що ви збираєте для комп'ютера, за яким сидите. Toolchain-файл каже інакше:

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

Рядок, про який забувають, - CMAKE_TRY_COMPILE_TARGET_TYPE. На початку CMake збирає тестову програму, щоб перевірити, що компілятор працює, а bare-metal компілятор не може злінкувати програму для PC (немає операційної системи, немає main, який хтось викликає). Якщо ціллю перевірки є статична бібліотека, тест проходить. Toolchain задається в командному рядку один раз, коли створюється тека збірки:

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

Та сама тека з вихідними кодами з іншим -B - це інша збірка: build-release поруч або збірка для модульних тестів на PC, без toolchain-файлу.

Прапорці з іменами​

Рядок на кшталт -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -ffunction-sections ... важко рев'юїти, бо ніхто не знає, яка його частина важлива. Платформа має файл Flags.cmake зі змінною для кожного прапорця та коментарем (THUMB_MODE, ENABLE_ALL_WARNINGS, REMOVE_UNUSED_FUNCTIONS, ENABLE_GC_SECTIONS, PRINT_MEMORY_USAGE і так далі, плюс варіанти CPU та FPU від Cortex-M0 до M85). Тоді проєкт читається як речення. У моєму лише те, що потрібно для прикладу:

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

Увесь кореневий файл прикладу, 80 рядків:

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

Поясню кілька рядків, від яких залежить, чи буде firmware правильним.

Типи збірки з явними прапорцями. Їх лише два: Debug (-Og -g3: достатньо швидко і можна налагоджувати) та Release (-Os -g0: малий розмір і без налагоджувальної інформації), а будь-що інше зупиняє конфігурацію з повідомленням про помилку. Платформа має ще два, UnitTest та IntegrationTest: у першому TARGET_MCU навіть не потрібен, бо збірка йде для PC.

Типові прапорці CMake. Це пастка. CMake додає власні прапорці до кожної конфігурації, -O3 -DNDEBUG для Release і -g для Debug, перед вашими. У першій версії прикладу команда компіляції release виглядала так:

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

Перемагає останній -O, тож це був -Os, але -DNDEBUG (який вимикає assert()) там був, хоча я його не просив. Якщо ви хочете знати, що збираєте, очистіть типові значення (set(CMAKE_C_FLAGS_RELEASE "")) і напишіть усе у власному файлі. Спосіб побачити, що справді йде до компілятора, - compile_commands.json, який створює опція CMAKE_EXPORT_COMPILE_COMMANDS: це також файл, який читають редактори та clang-tidy.

Startup-код - це бібліотека OBJECT. Об'єкти такої бібліотеки потрапляють у виконуваний файл напряму, без покладання на те, що linker витягне їх з архіву.

Linker script - це залежність (LINK_DEPENDS): коли він змінюється, firmware лінкується знову.

Модулі - це бібліотеки​

Кожен модуль - статична бібліотека зі списком власних вихідних файлів і публічних заголовків (стаття про організацію файлів пояснює чому). Застосунок лінкує бібліотеку і разом з нею отримує шлях включення публічних заголовків і більше нічого. У файлі CMake модуля немає file(GLOB ...): вихідні файли перелічено по одному, тож новий файл - це видима зміна в pull request, а файл, випадково залишений у теці, не потрапить у firmware.

TARGET_MCU: одне ім'я, кілька визначень​

Збірки платформи запускаються з -DTARGET_MCU=STM32G474xE. Скрипт розбирає ім'я регулярним виразом і з одного параметра робить визначення для коду (STM32G474xx та STM32G4xx), які заголовки виробника використовують для вибору потрібного пристрою. Та сама логіка, запущена на чотирьох іменах:

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

Це зв'язок зі статтею про родини STM32 і гілки: родина вирішує, яка гілка BSP лежить у дереві, а ім'я MCU вирішує визначення та linker script.

Що вам каже linker​

-Wl,--print-memory-usage наприкінці кожного лінкування виводить, скільки кожної пам'яті використано, -Wl,-Map=firmware.map записує адресу всього, а крок post-build виводить розмір:

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

Два експерименти, які я провів із цими числами, показують, чому прапорці мають бути у збірці, а не в чиїйсь голові.

Linker може викинути те, що ніхто не викликає. З -ffunction-sections -fdata-sections кожна функція лежить у власній секції, а -Wl,--gc-sections дозволяє linker видалити ті, на які немає посилань. У прикладі є функція Unused_Checksum(), яку ніхто не викликає:

Різниця у 48 байтів - це саме функція контрольної суми. У справжньому проєкті з бібліотекою виробника, яка має сотні функцій, з яких ви викликаєте десять, різниця вимірюється в кілобайтах.

Компілятор може додати пам'ять за вашою спиною. Перша release-збірка прикладу мала 772 B, майже втричі більше за debug-збірку (288 B). Map-файл показав memcpy і memset зі стандартної бібліотеки. Причина: коли оптимізація ввімкнена, GCC розпізнає цикли в startup-коді (копіювання .data і обнулення .bss) як копіювання й заповнення та замінює їх викликами цих двох функцій, які потім приходять зі своїм кодом з бібліотеки. Один прапорець на startup-об'єкті це виправляє, і результат - 276 B:

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

Крім розміру, є друга причина про це дбати: startup-код виконується до ініціалізації пам'яті, і чим менше бібліотечного коду він використовує, тим менше може піти не так (див. статтю про те, що відбувається перед main()).

Після лінкування: що ви прошиваєте і що тестуєте​

Команда POST_BUILD створює firmware.bin і firmware.hex (формати, які читають програматори) з файлу ELF і виводить розмір. Остання частина прикладу - тест: add_test запускає firmware в QEMU, а ctest перевіряє, що воно вивело очікуваний текст:

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

Це smoke test (чи стартує firmware і чи доходить до свого main()?), і він виконується за долю секунди на кожному коміті. Він не замінює тест на hardware, але збірку, що не стартує, знаходять у CI, а не за столом. Тести модулів на PC - це інша збірка того самого проєкту CMake (одну показує стаття про Unity і CMock).

Чекліст​

1. Toolchain-файл і CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY.
2. Прапорці в одному файлі з іменами, типові значення конфігурацій CMake очищені.
3. Кожен модуль - бібліотека з явним списком вихідних файлів і публічних заголовків.
4. -ffunction-sections -fdata-sections і --gc-sections, завжди.
5. --print-memory-usage і map-файл у кожному лінкуванні, після нього size.
6. compile_commands.json для редактора та статичного аналізу.
7. Linker script - залежність firmware.
8. Smoke test у симуляторі в CI.
9. Час від часу дивіться на розмір release-збірки. Якщо він зростає без причини, map-файл знає чому.

Ця стаття розбирає три проблеми спільних даних, одну за одною, на коді, який не працює, а потім показує шаблони, які працюють. Експерименти виконувалися на Cortex-M4 (у QEMU, на моделі плати STM32F4) або на PC, а виводи - справжні.

Проблема 1: компілятор не бачить переривання​

Найпростіша комунікація між перериванням і головним циклом - прапорець. Переривання його встановлює, головний цикл на нього чекає:

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

Це вся програма, і з оптимізацією -O2 вона ніколи не завершується. Я запустив її в QEMU з SysTick як джерелом переривання (переривання спрацьовує й встановлює прапорець) і порівняв версію з volatile та без нього:

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

Чому? Подивіться, що компілятор згенерував для циклу в першій версії:

 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

Компілятор міркує лише про код main(), а в цьому коді в dataReady ніхто не пише. Отже, значення не може змінитися, його достатньо прочитати один раз, і цикл стає нескінченним. З його точки зору - саме те, що ви просили. З volatile компілятор мусить читати змінну з пам'яті на кожному проході:

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

Урок: кожна змінна, яку діляться переривання й основний код, має бути volatile. Те саме стосується кожного регістра периферії, і саме тому визначення регістрів у заголовках CMSIS є volatile. Пам'ятайте, що без цього в debug-збірці (-O0) усе працює, а в release-збірці ламається, тому помилку знаходять пізно.

Проблема 2: volatile не робить операцію атомарною​

volatile каже «читай і пиши пам'ять щоразу». Воно не каже «усе одразу». Невинний рядок counter++ - це три інструкції:

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

Якщо переривання надходить між завантаженням і записом, і переривання також інкрементує лічильник, то один із двох інкрементів губиться: основний код записує старе значення плюс один поверх значення, яке щойно записало переривання. Часова послідовність:

Я хотів показати це і на Cortex-M4, але не вийшло: у 200 000 інкрементів із перериванням кожні кілька інструкцій QEMU нічого не втратив. Імовірно, тому що QEMU перевіряє переривання між блоками транслюваного коду, тож жодне ніколи не потрапляє між ldr і str. Це корисне нагадування, що симулятор не доводить відсутності race condition: справжній MCU може перервати після кожної інструкції. Той самий race у місці, де його легко відтворити, - це два потоки на 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)

Третина всіх інкрементів губиться, а результати відрізняються від запуску до запуску. Потік на PC і переривання на MCU в цьому сенсі - одне й те саме: другий потік керування, який може вдарити між двома інструкціями. Те саме стосується всього, що більше за слово CPU: 64-бітова часова мітка або структура з двох полів може бути прочитана наполовину старою, наполовину новою (torn read).

Три способи розв'язання​

1. Один записувач на кожну змінну (найкращий)​

Найнадійніше рішення - спроєктувати дані так, щоб кожна змінна записувалася лише однією стороною. Переривання записує прапорець, основний код лише читає його й не скидає (або навпаки). Без двох записувачів нема чого губити. Якщо обом сторонам потрібно змінювати те саме, вони не повинні це ділити: у кожної своя змінна (лічильник переривань - isrCalls, лічильник основного коду - інший), а суму рахує читач.

2. Критична секція​

Коли двох записувачів уникнути не можна, переривання вимикаються на час операції. Правильний спосіб - зберегти стан і відновити його, а не вмикати переривання наприкінці наосліп, бо функцію могли викликати з уже вимкненими перериваннями:

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

Ціна - затримка (latency): під час секції жодне переривання не може виконатися. Тому секція має бути короткою, як кілька інструкцій, і без виклику функції, циклу чи очікування всередині.

3. Атомарна операція​

Для одного слова (лічильник, прапорець із лічильником) процесор має інструкції LDREX та STREX: запис вдається лише якщо ніхто не торкався адреси після завантаження, а якщо торкався - цикл повторюється. Компілятор генерує їх за вас зі стандартної операції:

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

у C це один рядок, __atomic_fetch_add(&counter, 1u, __ATOMIC_RELAXED) (або atomic_fetch_add() з <stdatomic.h>). Він не вимикає переривання, тож не додає затримки. Він працює для однієї змінної; для двох змінних, що належать одна одній, не допомагає.

Найуживаніший шаблон: кільцевий буфер​

Найпоширеніше, що переривання передає основному коду, - потік даних: байти, прийняті UART, відліки АЦП. Переривання не може їх обробляти (воно має бути коротким), тому кладе їх у чергу, а основний код забирає їх у спокійний момент. Це задача виробник-споживач з одним виробником (переривання) та одним споживачем (основний код), і саме для цього випадку кільцевий буфер не потребує блокування:

#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

Чому це правильно?

• head записує лише виробник, а tail - лише споживач. Немає змінної з двома записувачами, тож жодне оновлення не може загубитися: це перше рішення вище, вбудоване в структуру.
• Лічильники вільно біжать (free-running) і ніколи не скидаються. Кількість елементів - це head - tail, і завдяки беззнаковій арифметиці вона правильна навіть після переповнення лічильників. Якщо розмір - степінь двійки, позиція отримується простою маскою замість ділення.
• Порядок має значення: виробник записує елемент і після цього публікує його зсувом head (memory_order_release), а споживач спершу читає head (memory_order_acquire) і лише потім елемент. На одному ядрі Cortex-M важливий лише порядок, у якому компілятор записує, і атомарні операції його зберігають. На MCU з двома ядрами (деякі STM32H7 мають два) або з кешем той самий код усе ще правильний, і це причина писати його в такій формі, а не з volatile, який «якось працює».
• Виробник не чекає. Повний буфер означає «відкинь елемент і порахуй це», бо переривання не може ні на кого чекати. Лічильник відкинутих у тесті каже вам, що буфер замалий.

Я перевірив це двома способами. На PC з двома потоками, виробником і споживачем, пропускаємо 20 мільйонів елементів через буфер на 16 слотів:

items 20000000, order errors 0

і на Cortex-M4 у QEMU: переривання SysTick - виробник, а main() - споживач, 5000 елементів:

items received  5000
order errors    0
full buffer hits 0

Перший тест жорсткіший (два потоки справді виконуються паралельно на двох ядрах), другий - справжня ситуація MCU. Це також ідеальний кандидат для модульного тесту на PC, як у статті про модульне тестування з Unity та CMock: модуль не залежить від hardware.

Правила для обробників переривань​

1. Короткі. Прочитати регістр, зберегти дані, встановити прапорець, скинути pending-прапорець, повернутися. Обробка виконується в основному коді.
2. Без очікування, без виділення пам'яті, без printf. Нічого, що блокує, триває довго або викликає функцію, небезпечну для виклику з переривання (вона нереентерабельна, якщо всередині використовує статичний буфер).
3. Усе спільне - volatile або атомарне, і в кожної змінної визначений записувач.
4. Не діліть більше, ніж потрібно. Прапорець або черга між сторонами, а не структура з десяти полів.
5. Думайте про пріоритет. Переривання вищого пріоритету може перервати інше переривання. Змінна, спільна для двох переривань, має ту саму проблему, що й спільна з основним кодом.

У Embedbits BSP модулі периферії (наприклад, USART) мають варіанти обробки даних polling, interrupt і DMA, і варіант з перериваннями - саме це: обробник на рівні MCAL, який бере дані з периферії та передає їх застосунку через буфер, тоді як Task модуля працює в головному циклі й виконує обробку.

Підсумок​

Три види коду в цій статті мали одну спільну рису: усі вони виглядали правильно.

Кнопка виглядає тривіальною: пін, високий або низький рівень. Але механічний контакт деренчить (bounce), тож пін робить 1 0 1 1 0 1, перш ніж заспокоїться, а продукт зазвичай хоче від тієї самої кнопки двох різних речей: коротке і довге натискання. Якщо написати це з прапорцями та лічильниками в головному циклі, вийде кілька if, що залежать один від одного так, що за місяць ніхто не зможе пояснити як. Скінченний автомат вирішує це так, що пояснити можна таблицею.

Шаблон в одному абзаці​

Кожен стан має чотири підпрограми, і кожна з них має рівно одне завдання:

Ядро автомата запускає Execute і CheckLeave поточного стану, а коли стан змінився, запускає Leave старого і Entry нового. Підпрограми ніколи не викликають одна одну, а код автомата не містить нічого, крім автомата. Якщо хочете знати, чому пристрій у певному стані, читайте CheckLeave попереднього.

Спочатку дизайн: стани та переходи​

Задача запускається кожні 10 мс і читає сирий контакт. Час debounce — 50 мс, а межа довгого натискання — 1 секунда. П'яти станів достатньо:

Складання таблиці — це справжня робота. Коли вона повна, код — лише вправа з друкування. Коли ні (що відбувається в LONG_PRESS, коли контакт деренчить при відпусканні?), таблиця покаже діру ще до того, як ви напишете рядок C.

Код​

Вхід приходить із BSP, тож модуль не має апаратних залежностей і його можна тестувати на ПК (той самий seam, що й у статті про unit-тестування). Порт модуля — це Init, Task і функція, що повертає подію один раз:

#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

Типи слідують шаблону. Є одна зміна, яку я зробив навмисно: таблиця підпрограм індексується станом, а не обшукується, і перелік закінчується BUTTON_STATE_COUNT, який має два застосування.

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;

Перше застосування — сама таблиця. З designated initializers позиція рядка не має значення, тож стан не можна прив'язати до неправильних підпрограм, коли хтось додасть рядок посередині (шаблон потребує коментаря «цей масив має мати той самий порядок, що й enum станів»):

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

Друге застосування — ядро автомата, в якому та сама константа замінює жорстко закодований «останній стан» у перевірці діапазону:

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