Skip to content

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 fn holds a compiler-made resumed site, 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. A resumed site 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 = 2 in the release profile, debug info does not reach the flash;
  • has compressed debug sections;
  • has no panic handler and no core::panicking function: built with panic-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].