Skip to content

F0042 ext-4

Rule: External chip registers are written from shadow copies, not read-modify-write.

Code F0042 (stable, never reused)
Id ext-4
Category ext
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big off
ai off
embedded warn bedrock warning: Read-modify-write of an external chip's registers over the bus, clear-on-read registers read more than once: write from shadow copies
ui off
egui off
units-strict off
units-paranoid off

Why

Read-modify-write of an external chip's register over I2C/SPI is two bus transactions with a window between them: another path (an interrupt-driven update, a concurrent caller) can change the chip's state in that window, and the write-back clobbers it. Reading a clear-on-read status or event register more than once for the same event silently drops the second reader's view of it — the first read already cleared what the second one wanted to see.

Example

Pd_bench's fusb302 driver states its rule in AGENTS.md: "No read-modify-write: registers are written from shadow copies; clear-on-read registers are read once." The driver keeps its own in-memory shadow of what each writable register should contain and writes the shadow wholesale, and any clear-on-read register (interrupt/status flags) is read exactly once per occasion and the value distributed from there, not re-read by a second interested piece of code.

How to fix

Keep an in-RAM shadow of configuration registers the firmware itself is the only writer of, and update the shadow then write it whole; for clear-on-read registers, read once into a local value and hand that value to every consumer instead of letting more than one place touch the chip.

How it is checked

Src mid — a lint can flag a write immediately preceded by a read of the same register/field without a shadow struct in scope, and a second read of a known clear-on-read register within one logical operation.

Source

Ported from embedded_bedrock's firmware check catalogue, EXT-4 (book/checks.md, detail in book/checks/ext.md). Found on: pd_bench AGENTS.md.

Configure

[lints.ext-4]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(ext-4) <reason> (waivers); the code works there too, as in [lints.F0042].