Skip to content
Xaeian edited this page Nov 17, 2026 · 2 revisions

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.

Running

make lint

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

After every build

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.

Rules on by default

Threads and interrupts

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.

Stack

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

Values

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 open

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

Files and headers

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.

Rules a project turns on

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.

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. :name narrows a place to one function, variable or setting. Places starting with * go in quotes, since YAML reads * as an alias.
  • For switch-enum a place may also be where a value enters the enum, so projects vouch for their own entries even when the switch lies in Core.
  • Exceptions without reasons are refused, and make lint fails.
  • Exceptions silencing nothing print warnings, so none outlives its code.
  • Projects silence only their own code, and Core keeps its own exceptions.

lint.yaml

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.

Under the hood

gcc warnings

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

cppcheck and analyzer

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.

Clone this wiki locally