BFE EngineeringandClaude Fable 5
2756de0b46
CI/pipeline: - KERNEL_TARBALL passed as a YAML env literal '~' was never tilde-expanded and would have failed every hosted kernel-build dispatch; the path is now exported from the shell. Verified reproducible before the fix. - Every job gets timeout-minutes; boot smoke uses timeout -k so a wedged qemu is SIGKILLed instead of holding the job. - Tarball fetch + fail-closed sha256 verification deduplicated into build/fetch-kernel-tarball.sh (with curl retries), used by build-kernel.sh and both CI jobs. busybox fetch gains retries too. - ccache layer for kernel-build (cache keyed on defconfig+patches) recovers the incremental-compile speed the ephemeral-runner move cost. - build-kernel.sh now asserts every fragment option survived olddefconfig — merge_config -m pastes text and Kconfig silently drops unmet symbols. rs485-bridge: - pending-buffer cap (2x max RTU ADU) instead of unbounded growth; explicit accept-loop error handling with backoff instead of .flatten(); per-arm inline bounds instead of the string-keyed lookup whose default would have mis-bounded a future get-input; control-socket cleanup errors surfaced; flag-shaped values rejected in arg parsing; doc example uses a private mktemp dir. Test timing margins widened for contended runners (gap 25->120ms, 60x margin on the split-frame test). VM harness: - stage-1/stage-2 boot scripts share one validated slot parser and one by-name populator (qemu/rootfs/etc/warden-lib.sh) — the duplicated parser had already diverged on validation; userdata/oem mount failures now fail fast with a greppable sentinel; udhcpc fallback keys off the interface actually having an address; switch_root applet guarded. - boot-smoke delegates the qemu invocation to run.sh (machine shape lives in ONE place); run.sh port 0 disables a hostfwd. - mkimage: unknown partition names fail at build time; DISK_END is a max, not last-entry; --state keys validated as filenames. - portal-scenario: mock readiness is asserted (no silent fall-through), hostfwd port collisions retried, mount-failure sentinel fails fast. - ui-shot: fixed sleeps replaced with bounded screendump polling; the repaint assertion is real and documented as such. qmp.py loses its module-global and gains argv validation. Docs/scrub: bench-host paths and the site AP name removed from six more port docs and two evidence tables; path-bearing build artifacts (.elf, .map) untracked (the 154-byte firmware .bin is path-free and stays); ADR-0003 marked visibility-superseded by ADR-0007; stale section cross-reference fixed; flare-edge noted as private for outside readers; stale root-level review report removed per the new workspace rule. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018HUayid7W5w7jBdb9Rrj1K
qemu/ — the WardenOS device simulator
A QEMU virtual machine that boots the real forward-ported kernel (build/ +
patches/) and real userspace, so the device — init, daemons, networking,
OTA, watchdog, display — can be tested off-hardware. The third simulator in
the stack, deliberately not named "sim":
lvglsim(flare-edge) — SDL desktop build of the UI. Rendering only.sim/(this repo) — register-level Rust models of RV1106 blocks behind driver seams.qemu/(this) — the whole machine above the kernel entry point, running the real binaries.
Decision record: docs/decisions/0006-qemu-device-sim.md.
The boundary (read this before trusting a green run)
There is no RV1106 machine model in QEMU and everything below the kernel is
closed rkbin blobs plus mask ROM, so the VM enters at -kernel zImage on
-M virt,highmem=off (single Cortex-A7, 256M — the RV1106G3's shape).
| Emulated / substituted | Not emulated (stays bench / sim/ territory) |
|---|---|
| Kernel boot, init ordering, switch_root | BootROM, idblock/DDR-init, SPL, U-Boot |
A/B outcome (warden.slot= cmdline) |
Real BCB A/B selection, bootcount auto-revert |
Storage: virtio-blk with the device's exact blkdevparts= layout + /dev/block/by-name/ contract |
eMMC controller itself |
| Network: virtio-net (slirp, hostfwd 22/80/28443) | GMAC, AIC8800 wifi, usb0 gadget |
| Display: virtio-gpu 720x720 via fbdev emulation | VOP/RGB666 pipeline, CH32V003 panel init, RGA blits |
Touch: virtio-tablet (QMP input-send-event) |
GT911 on I2C3 |
Watchdog: i6300esb (PCI), -action watchdog=reset |
DW watchdog @0xff5a0000, HPMCU supervisor |
RS485: pci-serial chardev bridged to sim/'s ModbusSlave |
Real UART4 timing/electrical behavior |
RTC: PL031 (--rtc reproduces the no-RTC 2021-clock incident class) |
The unpopulated backup-cell reality |
"Boots/works under emulation" is never evidence of "works on silicon." The VM narrows which claims need a panel; on-device claims still need on-device evidence. Conversely, the VM is the first environment that runs production binaries on a non-RV1106 memory map — it found flare-edge #106 (fatal SIGBUS in flared's HPMCU probe) and #107 (Y2038 time_t truncation) on its first two boots of real userspace.
Documented guest deviations from production, set by stage-2 init:
WARDEN_FLARE_INSECURE=1 (the desk mock portal is plain HTTP) and
WARDEN_HPMCU=0 (no mailbox SRAM on virt; flared >= flare-edge#106 fix
required, or the daemon dies of SIGBUS).
Quick start
# 1. kernel: canonical build boots the VM as-is; the fragment variant adds
# the scenario devices (PCI serial, watchdog, WireGuard, virtio-gpu/input)
WORK=$HOME/kbuild-out CROSS_COMPILE=arm-linux-gnueabihf- \
WARDEN_KCONFIG_FRAGMENT=qemu/configs/virt.fragment bash build/build-kernel.sh
# 2. initramfs (sha256-pinned static busybox + qemu/rootfs/) and A/B disk
bash qemu/mkinitramfs.sh
bash qemu/mkimage.sh # options: --portal-url --state K=V --fw-version
# 3. run (see run.sh header for all flags)
bash qemu/run.sh --kernel $HOME/kbuild-out/linux-6.18.46/arch/arm/boot/zImage --shell
Payload: drop static musl armv7 binaries into qemu/payload/ (see its
README) — warden-flared, warden-modbus, and warden-ui (the LVGL
fbdev+evdev build from flare-edge tools/build-ui-vm.sh) are started by
stage-2 init when present.
Scenario tests (qemu/tests/)
boot-smoke.sh <zImage>— sentinel-asserting boot; runs in CI inside the kernel-build job.portal-scenario.sh <zImage>(needsFLARE_EDGE=<checkout>) — the real flared in the VM against the desk mock portal: authenticated check-in, firmware desired-state pull, and download of a real signed tier-1.wfwoffer. Verify/stage/APPLYING run as a dry run (noWARDEN_FW_ALLOW_APPLY); flipping it on inside the VM is the documented stretch — apply writes/dev/block/by-name/rootfs_binside disk.img, then--slot _bboots it.ui-shot.sh <zImage>— display+touch: boots headless with virtio-gpu, QMP-screendumps the 720x720 UI, taps the Metrics tab viainput-send-event(a 200 ms hold — an instantaneous press+release lands inside one LVGL poll and never clicks), and asserts the frame changed.qmp.pyis the tiny QMP client.- Watchdog:
run.sh --watchdog, arm/dev/watchdogin the guest, don't pet — the VM resets ~30 s later (verified). Do NOT combine with a flared payload expecting survival: flared pets only while the UI heartbeat is fresh.
Gotchas that cost time (so they cost it once)
- AF_UNIX socket paths cap at ~108 chars — keep
--rs485/--qmppaths short. - A serial port that is closed discards incoming bytes: hold ONE fd open across write and read when scripting the guest side of the RS485 bridge.
highmem=offand-global virtio-mmio.force-legacy=falseare load-bearing (32-bit ECAM reach; virtio-1-only gpu/input) — both live ONLY in run.sh, which every script (boot smoke included) delegates to.- Never pass
earlyprintk: DEBUG_UART_PHYS is the RV1106's 0xff4c0000.
Host requirements
qemu-system-arm (Debian 13 ships QEMU 10), curl, cpio, mkfs.ext4,
gcc-arm-linux-gnueabihf (kernel build), python3 (+cryptography for the
portal scenario's .wfw signing). CI: the hosted qemu-tools job builds the
tooling; the boot smoke runs inside the (also hosted, dispatch-only)
kernel-build job, which apt-installs its own toolchain and qemu (ADR-0007).