Repository navigation
lint
make lint checks a project before a reviewer has to: threads and interrupts, stacks, values and headers, then cppcheck and gcc analyzer.
Rules ask for proof, not for one way of writing C: correct code passes, and findings mark what can really break.
Findings name their rule and its norms, if any: CWE, CERT C, MISRA C or BARR-C.
Forge basics are in the readme.
Most projects need only Running.
lint.yaml comes in only to turn on more rules or keep exceptions.
make lintLint checks the last build, so make lint builds first.
On Windows the first run installs cppcheck into Forge tools.
On Linux cppcheck 2.17 or newer and arm-none-eabi-gcc 14 or newer have to be on PATH.
Findings print like compiler warnings: place, rule, what is wrong and norms.
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
The last line counts checks that found nothing, as make test counts its programs.
Any finding left gives exit code 1, so CI stops.
Each chip build prints stack use of every thread below FLASH and RAM. Forge rules on threads and files run there too, as warnings that stop nothing.
FLASH 41.7kB / 512kB (8%)
RAM 25.1kB / 192kB (13%)
STACK DBG_Loop 716B / 1024B (69%, at least)
Stack use is the deepest call path from the thread function, plus what each thread switch leaves on its stack.
at least means the path calls through pointers or into libraries, so real depth can be greater.
| Rule | Finds | Norms |
|---|---|---|
irq-yield |
interrupt calling let, delay or timeout
|
CWE-479, CERT SIG30-C |
irq-heap |
interrupt touching the heap | CWE-364, CERT SIG30-C |
irq-log |
interrupt writing to the console buffer threads use too | CWE-479, CERT SIG30-C |
irq-volatile |
variable an interrupt writes and a thread polls in a loop, without volatile
|
BARR-C 1.8, CERT DCL22-C, CWE-362 |
thread-hold |
thread calling sleep, which holds the core |
CWE-1322 |
heap-owner |
heap_clear outside a thread function |
CWE-416, CERT MEM30-C |
heap-cleared |
thread taking blocks from heap_new and never calling heap_clear
|
CWE-401, CERT MEM31-C |
Interrupts are handlers from the vector table and functions drivers get for their interrupts, as arguments or in fields.
Rules follow the call graph gcc writes after inlining, so they see calls through pointers and only code that ends up in the image.
Threads and interrupts started inside macros hide their arguments, so rules skip them and a warning says where.
Panic ends the program, so interrupts may log through panic.
volatile is asked only where a thread polls: the compiler may keep a variable in a register and never see an interrupt write it.
while(!flag) {} needs volatile, while(!flag) let(); does not, since calling into another file makes the compiler read flag again.
So do calls through pointers, asm and __disable_irq().
Single reads per call, ring indexes and reads with interrupts masked need nothing either.
| Rule | Finds | Norms |
|---|---|---|
recursion |
function calling itself, directly or through others | MISRA C 17.2, CWE-674 |
stack-fit |
thread whose deepest path does not fit its stack | CWE-787 |
| Rule | Finds | Norms |
|---|---|---|
switch-enum |
state machine switch without default over an open enum |
CWE-478 |
A switch whose cases set the value it switches on is a state machine, and any value outside its enum stops it for good.
It needs no default when its enum is closed in the whole application: every value entering it from another type is checked to be one of its enumerators.
Then -Wswitch names any enumerator added later that the switch misses.
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 and 4 still pass, so MODE_t stays openA range proves nothing when the enum has gaps, as above, while constants, checks of exact values or a clamp right after conversion do.
Raw bytes from memcpy, from load functions of lint.yaml or from unions need a check later in the same function.
Any other switch may leave values out, as C allows, and -Wmaybe-uninitialized and -Wreturn-type catch what that would break.
| Rule | Finds | Norms |
|---|---|---|
header-object |
variable defined in a header | MISRA C 8.6, BARR-C 4.2 |
header-guard |
header without an #ifndef guard, even with #pragma once
|
MISRA C Dir 4.10, CERT PRE06-C |
extern-in-c |
extern in a .c file |
MISRA C 8.5, CERT DCL40-C |
own-header-first |
source file not starting with its own header | MISRA C 8.4, BARR-C 4.3 |
static-scope |
project function or variable no header declares, without static
|
MISRA C 8.7, 8.8, CERT DCL15-C |
include-form |
#include in quotes for another tree, or in angle brackets for its own |
|
config-order |
default under #ifndef in a header that main.h cannot reach |
CERT DCL40-C |
config-unread |
setting in main.h that no file reads, or that a file defines without #ifndef
|
MISRA C 2.5 |
static-scope wants static on what no header declares: it stays in its file, and other files may reuse its name.
main and interrupt handlers stay global, since startup code calls them by name, and Core is not checked.
include-form lets each #include show where its file comes from: quotes for the same tree, angle brackets for any other.
Trees are the project, Core, code of others under vendor and the toolchain, so projects write #include <uart.h> and Core writes #include <stm32g0xx.h>.
main.h and boot.h configure the build, so they always come in quotes.
No norm asks for this: it is OpenCPLC house style.
Module settings have defaults under #ifndef in their headers, and main.h changes them.
config-order checks that each such header includes main.h above its defaults, directly or through another header: otherwise one file builds with a default and the rest with the setting.
config-unread checks that each setting in main.h reaches a file that reads it, so typos and renamed settings never pass silently.
Names starting with PRO_ and BOOT_ belong to Forge and stay out.
These rules are off by default, each for its own reason.
A project turns them on in its lint.yaml:
rules: [no-heap, stack-margin, status-used]| Rule | Checks | Off by default because |
|---|---|---|
no-heap |
project uses neither the VRTS heap nor the C library one (MISRA C 21.3) | VRTS and Core libraries use the heap |
stack-margin |
each thread keeps 25% of its stack free | it is a product requirement, not a framework one |
switch-enum-default |
no default in a switch over a closed enum, so -Wswitch keeps watching |
default does no harm until the enum grows |
switch-default |
default in every switch over an integer (MISRA C 16.4) |
a value with no label skipping the switch is plain C |
status-used |
every returned status_t is read (MISRA C 17.7, CERT ERR33-C, CWE-252) |
Core ignores a status where failure changes nothing |
conversion |
-Wconversion, a value narrowed by conversion (MISRA C 10.3) |
noise on uint8_t arithmetic |
double-promotion |
-Wdouble-promotion, double where float was meant |
speed, not correctness: the M4 computes double in software |
cppcheck-style |
cppcheck checks of the style category |
many notes on form, few on defects |
They check only project code, and Core compiles as always. Default rules cannot be turned off: findings that are right go to exceptions.
Findings that are right by design get exceptions in lint.yaml: rule, then place and reason.
except:
recursion:
lib/ext/nanopb/: Protocol messages nest three levels at most
thread-hold:
main.c:calibrate: Measurement needs 50ms of quiet bus, other threads wait- Places are paths from the folder of
lint.yaml, written as in.gitignore.:namenarrows a place to one function, variable or setting. Places starting with*go in quotes, since YAML reads*as an alias. - For
switch-enuma place may also be where a value enters the enum, so projects vouch for their own entries even when theswitchlies in Core. - Exceptions without reasons are refused, and
make lintfails. - Exceptions silencing nothing print warnings, so none outlives its code.
- Projects silence only their own code, and Core keeps its own exceptions.
lint.yaml sits at the root of Core and, when needed, of a project:
-
roles: what functions of its API do -
vendor: code of others, which rules, cppcheck and the analyzer skip -
rules: rules the project turns on -
except: exceptions with reasons
Core describes its whole API: functions that yield or hold the core, use the heap, start threads, register interrupts, write to the console, end the program or load raw bytes, plus the status type and the thread switch frame of each CPU. Projects add their own code to those lists, such as callback fields of their drivers or their functions loading bytes:
rules: [no-heap, stack-margin]
roles:
irq:
field: [OnFrame]
load: [SENSOR_Read]
vendor: [lib/third/*]Unknown keys are errors naming them, and roles only Core sets, such as thread, have no place in projects.
Without lint.yaml in Core, only cppcheck, the analyzer with static-scope and the first four file rules run.
Every chip build compiles with warnings for MISRA C rules gcc can check:
-
-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 and 17.4
make lint runs cppcheck with its warning, performance and portability checks, and compiles every source again with -fanalyzer.
Both check the application and its bootloader, each with its own defines.
cppcheck reads copies of sources without chip headers, which gives the same findings three times faster, and its dump of types and values feeds value rules.
Forge deletes .dump and .ctu-info files cppcheck leaves beside the copies.
Findings keep names their tools give, such as comparePointers or Wanalyzer-malloc-leak, with CWE numbers when known.
shiftNegativeLHS stays out, since gcc defines shifts of negative values.
Sources the analyzer cannot compile are findings of their own, so the check never passes on code nobody analyzed.
Code of others under vendor is left out: its own project checks it.