Repository navigation
lint.pl
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.
make lintLint 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.
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ł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ą.
| 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 |
| 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 otwartySam 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.
| 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.
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.
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:nazwazawęż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-enummiejscem może być też to, w którym wartość trafia do enuma, więc projekt ręczy za własne wejście, nawet gdyswitchleży w Core. - Wyjątek bez powodu jest odrzucany i
make lintkoń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 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.
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
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.