BFE Engineering
c756622c96
The repo's documentation framed it as a support repo for one product (WardenOS). Since going public the real audience is anyone with a Luckfox Pico 86 Panel: a maintained 6.18 kernel, an off-device development loop, and a device simulator that exist nowhere else for this board. Reframe the README and top-level docs board-first, with WardenOS documented as the downstream consumer it is (ADR-0008). Also an editorial pass over the whole doc set: - every H1/H2 is now a short title, not a sentence (ADRs, qemu/, patches/, drivers/, architecture, NPU feasibility, config-lint, payload); workflow flowchart titles fixed at the source in tools/flowgen.py and regenerated with fresh bench numbers - README Quick Start commands verified against the scripts; requirements corrected (curl, bare python, gcc >= 14) and the MC/DC gate added as a step (run green locally on gcc 14.2) - dropped the 'needs python (not python3)' vendor dig: build-kernel.sh inherited the same requirement (filed #10 to remove it) - glossed MC/DC and HPMCU on first use; marked the tests/uboot-ab reference as flare-edge; deduplicated the three-simulator list into the root README table
1.8 KiB
1.8 KiB
ADR 0002 — Tiered MC/DC
Status: Accepted (2026-08-25).
Context
The goal "port + harden 100% of drivers to 100% MC/DC" is infeasible as literally stated: ~97% of driver LOC is vendor blobs (the AIC8800 wifi driver alone is 88.5K lines) that we cannot meaningfully unit-test to MC/DC on the host. Forcing MC/DC on that code would be theatre, not assurance.
Decision
A two-tier policy, measured against the Hardware Abstraction Seam:
- Tier 1 — our own hardware-facing code → real 100% MC/DC.
modbus_engine.c,relays.c,warden_rga.c(wrapper),hpmcu.rs,devmem.rs,freshness.c, plus the two smallest near-mainline drivers where feasible. Enforced in CI (gcc-14 -fcondition-coverage+gcov-14 --conditions). Rust usescargo-llvm-covline/region coverage for now — true--mcdcneeds a nightly toolchain (-Z coverage-options=condition) and is deferred on that tooling skew; the C drivers carry the literal MC/DC gate. - Tier 2 — ported/vendor drivers → fault-injection + branch coverage + benchmarks against the simulator, behind a stable seam. Explicitly NOT literal MC/DC.
Consequences
- Matches the user's framing: "as many drivers as possible at 100% MC/DC; for the rest, a very serious testing and benchmarking system."
- The seam is the shared object: the same thing MC/DC is measured against and the simulator implements — the two goals reinforce, not duplicate.
- Every Tier-1 file gets a
drivers/<name>/test/host harness (aMakefile+test_<name>.c) that calls the one shareddrivers/enforce-mcdc.sh— which derives the driver name from the.gcovfile, so there is a single gate to maintain, not a per-driver copy. The CImcdcjob auto-discovers anydrivers/*/test/Makefileand fails below 100%.