Skip to content

lint.pl

Xaeian edited this page Nov 17, 2026 · 2 revisions

Lint

make lint sprawdza projekt, zanim zrobi to recenzent: wątki i przerwania, stosy, wartości i nagłówki, a na koniec przepuszcza kod przez cppcheck i analizator gcc. Reguły żądają dowodu, a nie jednego sposobu pisania w C: poprawny kod przechodzi, a zgłoszenie wskazuje to, co naprawdę może się zepsuć. Zgłoszenie podaje regułę, a jeśli stoi za nią norma, także normę: CWE, CERT C, MISRA C albo BARR-C. Podstawy Forge są w readme.

Większości projektów wystarczy uruchomienie. lint.yaml jest potrzebny dopiero wtedy, gdy projekt włącza dodatkowe reguły albo zapisuje wyjątek.

Uruchomienie

make lint

Lint sprawdza ostatni build, więc make lint najpierw buduje projekt. Na Windowsie pierwsze uruchomienie dokłada cppcheck do narzędzi Forge. Na Linuksie w PATH muszą być cppcheck 2.17 albo nowszy i arm-none-eabi-gcc 14 albo nowszy.

Zgłoszenie wygląda jak ostrzeżenie kompilatora: miejsce, reguła, co jest nie tak i normy.

projects/app/sensor.c:42:3: heap-owner: `sensor_read` frees every block of the thread calling it [CWE-416, CERT MEM30-C]
ERR Lint checks 19/20 in 35.8s

Ostatnia linia liczy sprawdzenia, które niczego nie znalazły, tak jak make test liczy swoje programy. Gdy zostaje choć jedno zgłoszenie, kod wyjścia to 1 i CI się zatrzymuje.

Po każdym buildzie

Build dla układu wypisuje pod FLASH i RAM zużycie stosu każdego wątku. Uruchamia też reguły Forge dla wątków i plików, ale ich zgłoszenia są tylko ostrzeżeniami i niczego nie zatrzymują.

FLASH 41.7kB / 512kB (8%)
RAM 25.1kB / 192kB (13%)
STACK DBG_Loop 716B / 1024B (69%, at least)

Zużycie stosu to najgłębsza ścieżka wywołań od funkcji wątku plus to, co przełączenie wątku zostawia na jego stosie. at least znaczy, że ścieżka woła coś przez wskaźnik albo z biblioteki, więc rzeczywista głębokość może być większa.

Reguły włączone domyślnie

Wątki i przerwania

Reguła Wykrywa Normy
irq-yield przerwanie, które woła let, delay albo timeout CWE-479, CERT SIG30-C
irq-heap przerwanie, które sięga do sterty CWE-364, CERT SIG30-C
irq-log przerwanie, które pisze do bufora konsoli używanego też przez wątki CWE-479, CERT SIG30-C
irq-volatile zmienna bez volatile, którą przerwanie zapisuje, a wątek odpytuje w pętli BARR-C 1.8, CERT DCL22-C, CWE-362
thread-hold wątek, który woła sleep i blokuje rdzeń CWE-1322
heap-owner heap_clear poza funkcją wątku CWE-416, CERT MEM30-C
heap-cleared wątek, który bierze bloki z heap_new i nigdy nie woła heap_clear CWE-401, CERT MEM31-C

Przerwanie to handler z tablicy wektorów albo funkcja, którą sterownik dostaje do obsługi swojego przerwania, w argumencie albo w polu. Reguły czytają graf wywołań, który gcc zapisuje po inliningu, więc widzą wywołania przez wskaźnik i tylko kod, który trafia do obrazu. Wątek albo przerwanie uruchomione wewnątrz makra ukrywa argumenty, więc reguły je pomijają, a ostrzeżenie wskazuje to miejsce. Panika kończy program, więc przerwanie może pisać do logu przez panic.

O volatile reguła pyta tylko tam, gdzie wątek odpytuje zmienną: kompilator może trzymać ją w rejestrze i nigdy nie zobaczyć zapisu z przerwania. while(!flag) {} potrzebuje volatile, a while(!flag) let(); nie, bo wywołanie funkcji z innego pliku każe kompilatorowi przeczytać flag od nowa. Tak samo działa wywołanie przez wskaźnik, asm i __disable_irq(). Pojedynczy odczyt na wywołanie, indeks pierścienia i odczyt przy zamaskowanych przerwaniach też niczego nie potrzebują.

Stos

Reguła Wykrywa Normy
recursion funkcja, która woła samą siebie, wprost albo przez inne MISRA C 17.2, CWE-674
stack-fit wątek, którego najgłębsza ścieżka nie mieści się w stosie CWE-787

Wartości

Reguła Wykrywa Normy
switch-enum switch maszyny stanów bez default po otwartym enumie CWE-478

switch, którego przypadki ustawiają tę samą wartość, po której się przełącza, to maszyna stanów, a wartość spoza enuma zatrzymałaby ją na zawsze. Nie potrzebuje default, gdy enum jest zamknięty w całej aplikacji, czyli każda wartość innego typu trafia do niego dopiero po sprawdzeniu, że jest jednym z jego enumeratorów. Wtedy -Wswitch wskaże enumerator dodany później, którego switch nie obsługuje.

uint8_t raw = frame[0];
if(raw > MODE_Stop) return ERR; // MODE_Idle = 0, MODE_Run = 1, MODE_Stop = 5
act((MODE_t)raw); // 2, 3 i 4 nadal przechodzą, więc MODE_t jest otwarty

Sam zakres niczego nie dowodzi, gdy enum ma luki, jak wyżej, ale stała, sprawdzenie konkretnych wartości albo przycięcie zaraz po konwersji już tak. Surowe bajty z memcpy, z funkcji z listy load w lint.yaml albo z unii potrzebują sprawdzenia dalej w tej samej funkcji. Każdy inny switch może pomijać wartości, jak pozwala C, a skutki takiego pominięcia łapią -Wmaybe-uninitialized i -Wreturn-type.

Pliki i nagłówki

Reguła Wykrywa Normy
header-object zmienna zdefiniowana w nagłówku MISRA C 8.6, BARR-C 4.2
header-guard nagłówek bez strażnika #ifndef, nawet z #pragma once MISRA C Dir 4.10, CERT PRE06-C
extern-in-c extern w pliku .c MISRA C 8.5, CERT DCL40-C
own-header-first plik źródłowy, który nie zaczyna się od własnego nagłówka MISRA C 8.4, BARR-C 4.3
static-scope funkcja albo zmienna projektu bez static, której nie deklaruje żaden nagłówek MISRA C 8.7, 8.8, CERT DCL15-C
include-form #include w cudzysłowie do innego drzewa albo w nawiasach ostrych do własnego
config-order wartość domyślna pod #ifndef w nagłówku, do której main.h nie dociera CERT DCL40-C
config-unread ustawienie w main.h, którego żaden plik nie czyta albo które plik definiuje bez #ifndef MISRA C 2.5

static-scope wymaga static przy wszystkim, czego nie deklaruje żaden nagłówek: taki symbol zostaje w swoim pliku, a inne pliki mogą użyć tej samej nazwy. main i handlery przerwań zostają globalne, bo kod startowy woła je po nazwie, a Core nie jest sprawdzany.

include-form sprawia, że już samo #include mówi, skąd jest plik: cudzysłów oznacza to samo drzewo, a nawiasy ostre każde inne. Drzewa to projekt, Core, kod zewnętrzny z listy vendor i toolchain, więc projekt pisze #include <uart.h>, a Core #include <stm32g0xx.h>. main.h i boot.h konfigurują build, więc zawsze stoją w cudzysłowie. Żadna norma tego nie wymaga: to styl OpenCPLC.

Ustawienie modułu ma wartość domyślną pod #ifndef w swoim nagłówku, a main.h ją zmienia. config-order sprawdza, czy nagłówek włącza main.h nad wartością domyślną, wprost albo przez inny nagłówek: inaczej jeden plik zbuduje się z wartością domyślną, a reszta z ustawieniem. config-unread sprawdza, czy każde ustawienie z main.h trafia do pliku, który je czyta, więc literówka albo przemianowane ustawienie nie przejdą po cichu. Nazwy zaczynające się od PRO_ i BOOT_ należą do Forge i są pomijane.

Reguły, które projekt włącza sam

Te reguły są domyślnie wyłączone, każda z własnego powodu. Projekt włącza je w swoim lint.yaml:

rules: [no-heap, stack-margin, status-used]
Reguła Sprawdza Domyślnie wyłączona, bo
no-heap projekt nie korzysta ze sterty VRTS ani biblioteki C (MISRA C 21.3) VRTS i biblioteki Core korzystają ze sterty
stack-margin każdy wątek zostawia wolne 25% swojego stosu to wymóg produktu, nie frameworku
switch-enum-default brak default w switch po zamkniętym enumie, żeby -Wswitch nadal pilnował default nie szkodzi, dopóki enum nie urośnie
switch-default default w każdym switch po liczbie (MISRA C 16.4) wartość bez etykiety, która pomija switch, to zwykłe C
status-used każdy zwrócony status_t jest czytany (MISRA C 17.7, CERT ERR33-C, CWE-252) Core pomija status tam, gdzie błąd niczego nie zmienia
conversion -Wconversion, zawężenie wartości przy konwersji (MISRA C 10.3) dużo szumu w arytmetyce na uint8_t
double-promotion -Wdouble-promotion, double tam, gdzie miał być float to sprawa szybkości, nie poprawności: M4 liczy double programowo
cppcheck-style sprawdzenia cppchecka z kategorii style dużo uwag o formie, mało o błędach

Sprawdzają tylko kod projektu, a Core kompiluje się jak zawsze. Reguły domyślnej nie da się wyłączyć: zgłoszenie w kodzie, który jest poprawny z założenia, trafia do wyjątków.

Wyjątki

Zgłoszenie, które wynika z celowej konstrukcji, dostaje wyjątek w lint.yaml: najpierw reguła, a pod nią miejsce i powód.

except:
  recursion:
    lib/ext/nanopb/: Komunikaty protokołu zagnieżdżają się najwyżej na trzy poziomy
  thread-hold:
    main.c:calibrate: Pomiar wymaga 50ms ciszy na magistrali, pozostałe wątki czekają
  • Miejsce to ścieżka względem folderu z lint.yaml, zapisana jak w .gitignore. Dopisek :nazwa zawęża je do jednej funkcji, zmiennej albo ustawienia. Miejsce zaczynające się od * trzeba wziąć w cudzysłów, bo YAML czyta * jako alias.
  • Przy switch-enum miejscem może być też to, w którym wartość trafia do enuma, więc projekt ręczy za własne wejście, nawet gdy switch leży w Core.
  • Wyjątek bez powodu jest odrzucany i make lint kończy się błędem.
  • Wyjątek, który niczego nie wycisza, daje ostrzeżenie, więc nie przeżyje kodu, dla którego powstał.
  • Projekt wycisza tylko swój kod, a Core ma własne wyjątki.

lint.yaml

lint.yaml leży w katalogu głównym Core i, gdy trzeba, także projektu:

  • roles: co robią funkcje jego API
  • vendor: kod zewnętrzny, który reguły, cppcheck i analizator pomijają
  • rules: reguły, które projekt włącza
  • except: wyjątki z powodami

Core opisuje całe swoje API: funkcje, które oddają albo zajmują rdzeń, korzystają ze sterty, uruchamiają wątki, rejestrują przerwania, piszą do konsoli, kończą program albo ładują surowe bajty, a do tego typ statusu i ramkę przełączenia wątku dla każdego rdzenia. Projekt dopisuje do tych list swój kod, np. pola callbacków własnych sterowników albo własne funkcje ładujące bajty:

rules: [no-heap, stack-margin]
roles:
  irq:
    field: [OnFrame]
  load: [SENSOR_Read]
vendor: [lib/third/*]

Nieznany klucz to błąd z jego nazwą, a roli ustawianej tylko przez Core, np. thread, projekt nie może wpisać. Gdy Core nie ma lint.yaml, działają tylko cppcheck, analizator ze static-scope i pierwsze cztery reguły plików.

Pod maską

Ostrzeżenia gcc

Każdy build dla układu kompiluje się z ostrzeżeniami dla tych reguł MISRA C, które potrafi sprawdzić gcc:

  • -Wundef: 20.9
  • -Wvla: 18.8
  • -Wshadow: 5.3
  • -Wimplicit-fallthrough: 16.3
  • -Wwrite-strings: 7.4
  • -Wstrict-prototypes: 8.2
  • -Wcast-function-type: 11.1
  • -Wcast-qual: 11.8
  • -Wall: 9.1, 13.2, 17.3 i 17.4

cppcheck i analizator

make lint uruchamia cppcheck ze sprawdzeniami z kategorii warning, performance i portability, a każdy plik źródłowy kompiluje jeszcze raz z -fanalyzer. Oba narzędzia sprawdzają aplikację i jej bootloader, każdy program z jego własnymi definicjami. cppcheck czyta kopie źródeł bez nagłówków układu, co daje te same zgłoszenia trzy razy szybciej, a jego zrzut typów i wartości zasila reguły wartości. Forge usuwa pliki .dump i .ctu-info, które cppcheck zostawia obok kopii. Zgłoszenia zachowują nazwy nadane przez narzędzia, np. comparePointers albo Wanalyzer-malloc-leak, z numerem CWE, jeśli jest znany. shiftNegativeLHS jest pomijane, bo gcc definiuje przesunięcie liczby ujemnej. Plik, którego analizator nie skompiluje, sam staje się zgłoszeniem, więc sprawdzenie nigdy nie przejdzie na kodzie, którego nikt nie przeanalizował. Kod zewnętrzny z listy vendor jest pomijany: sprawdza go jego własny projekt.

Clone this wiki locally