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
2.6 KiB
Hardened Drivers
Per ADR-0002 (tiered MC/DC) and ADR-0005 (source-of-truth), our own hardware-facing code migrates here behind a HAL seam and is hardened. "100% MC/DC on 100% of drivers" is infeasible (≈97% of kernel-driver LOC is vendor blobs — AIC8800 alone is 88.5K lines); the realistic, honest target is tiered.
Tier 1 — 100% MC/DC
Self-contained logic with a clean seam, measured to 100% MC/DC (gcc-14
-fcondition-coverage) by the CI mcdc job (make -C drivers/*/test check):
| Driver | Seam | MC/DC |
|---|---|---|
relays/ |
relay_io vtable (sysfs backend + in-memory fake) |
40/40 conditions, 100% |
freshness/ |
produce/render callbacks (the "no stale numbers" guard) | 66/66 conditions, 100% |
Adding a Tier-1 driver: copy <name>.{c,h} here, put the hardware/OS calls behind
a small injectable seam, then mirror relays/test/ (a fake backend for the logic
branches + a real backend over a scratch tree for the plumbing). Reuse the shared
gate — the Makefile calls bash ../../enforce-mcdc.sh <gcov.log> build/<name>.c.gcov build/test.rc (it derives the driver name from the .gcov file, so there is no
per-driver copy to keep in sync). The CI mcdc job picks up any
drivers/*/test/Makefile automatically.
Tier 2 — Fault Injection
Drivers too large or too vendor/UI-coupled for literal MC/DC get fault-injection,
branch coverage, and benchmarks against the simulator instead. Their hardware side
is already modelled and tested here in ../sim/:
| Driver | Serious-testing status | SDK model |
|---|---|---|
modbus_engine.c (RS485 master) |
8 pty scenarios + 3 wire/daemon checks (11 total) + fault-injection (flare-edge tools/modbus-sim/, green) |
sim::modbus RTU slave (11 tests, silent-drop/forced-NAK faults) + modbus_read_holding benchmark |
warden_rga.c (RGA offload) |
offload-dispatch + CPU-fallback logic | sim::rga recording improcess fake (programmable IM_STATUS) + rga_improcess benchmark |
HPMCU supervisor (hpmcu.rs) |
arm/beat/fire + boot-grace safety property | sim::hpmcu (7 tests) + hpmcu_tick benchmark |
Why the Tier-2 source isn't vendored here yet: modbus_engine.c and
warden_rga.c pull in shared UI headers (platform.h, settings.h, lv_*) and
librga. Copying those in would duplicate exactly the shared surface the
flare-edge↔warden-sdk unification (ADR-0003/0005, a separate maintainer-gated step) is
meant to resolve cleanly. So the Tier-2 models (the hardware ends) live here now;
the Tier-2 driver sources migrate in with the unification, at which point their
existing flare-edge harnesses point at this repo.