F0110 pan-1¶
Rule: Every panic site of the release ELF is acknowledged with a reason.
| Code | F0110 (stable, never reused) |
| Id | pan-1 |
| Category | pan |
| Source | spirit_level |
| Fix | by hand |
| Needs | the firmware's linked ELF (--elf); skipped without a firmware binary |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | off | |
| embedded | off | the strict level: every panic site of the release ELF acknowledged in panics.toml; a firmware turns it on for releases, with spl panics --ack to start the file |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
file |
string | "panics.toml" |
the acknowledgement file, relative to the firmware crate directory |
panic-fns |
list of strings | ["defmt::export::panic"] |
functions outside the standard library that panic for their caller: a call to one is a site |
zero-in |
list of strings | ["service"] |
task classes whose modules have no panic site in release: an entry does not acknowledge one there |
Why¶
A panic in firmware resets the whole MCU: embassy has no per-task restart. A release should not ship a panic nobody looked at. The ELF says what can still panic after the optimizer has run: every call into the standard library's panic entry points (core::panicking::*, unwrap_failed, panic_bounds_check, the overflow and division checks, RefCell's borrow failures), placed in the source by the DWARF of the call. At the strict level each of those sites is acknowledged in a file in the repo, with a reason: a review sees a new panic as a new line in that file.
spl panics --elf target/thumbv7em-none-eabihf/release/app lists the sites.
Example¶
# panics.toml, beside the firmware's Cargo.toml
[[site]]
function = "app::power::duty"
kind = "panic"
index = 0
reason = "a zero period is a broken config table; the stage is off until the reset"
[[crate]]
name = "embassy_stm32"
reason = "the HAL's own invariants; its configuration errors fire at init, before any output"
A site is named by the path of the function it is written in, without generic arguments, its kind (unwrap, expect, panic, assert, bounds, slice, overflow, division, refcell, alloc, resumed) and its index among the sites of that kind in that function, in source order. The key survives edits in other functions and new lines above it; a new site of the same kind earlier in the same function shifts the indices after it, and the review sees that.
- Inlining: a site inlined into several callers is one site, placed where it is written, with several call addresses.
- Generics: each monomorphization is a copy of the same site: one key.
- Folded sites: where the optimizer merged several sites into one call, the DWARF has no line (line 0). The site is listed under the function that holds the call and is acknowledged like any other.
- Resumed: each
async fnholds a compiler-maderesumedsite, reached only when an executor polls a finished future. Its entry gives that reason once per function. - Dependencies: a
[[crate]]entry acknowledges every site of a crate outside the project at once. The project's own crates are acknowledged site by site. - Service modules: a site in a module of a class in
zero-in(service) is reported whatever the file says: such a module never reaches the panic handler in release. Aresumedsite is acknowledged there like anywhere else.
An entry that matches no site any more is reported as stale.
What the ELF cannot tell¶
The lint does not run, and says why, when the ELF:
- has no DWARF: set
debug = 2in the release profile, debug info does not reach the flash; - has compressed debug sections;
- has no panic handler and no
core::panickingfunction: built withpanic-immediate-abort, where every panic is a trap that no call names, or no panic path is left; - is not Arm Thumb code.
A check the optimizer proved never fails is not in the binary: it cannot panic, and it is not listed. A call reached through a literal pool the linear Thumb decoder misreads, or a conditional tail branch into a panic entry, is not seen.
How to fix¶
Remove the panic (a Result, .get(i), checked_*), or add the site to the file with a reason: why it cannot fire, or why a reset is the right answer there.
How it is checked¶
elf: the call sites of the Thumb code into the panic entry points, the DWARF inline chain of each, the acknowledgement file (file, relative to the firmware crate directory).
Configure¶
[lints.pan-1]
level = "deny"
file = "panics.toml"
panic-fns = ["defmt::export::panic"]
zero-in = ["service"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(pan-1) <reason> (waivers); the code works there too, as in [lints.F0110].