bfe-core1106-sdk/qemu

The Device Simulator

A QEMU virtual machine that boots the real forward-ported kernel and real userspace: the 86 Panel (init, daemons, networking, OTA, watchdog, display) developed and tested with no board attached. The third simulator in the stack (three-way split: root README), deliberately not named "sim": it runs the whole machine above the kernel entry point on real binaries: bring your own, or drop prebuilt payloads in payload/. Decision record: ADR-0006.

The Boundary

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).

The VM's kernel is ahead of the panels' in one way that shows in the UI. It is built from build/warden_defconfig plus configs/virt.fragment, so it has CONFIG_BRIDGE; the vendor 5.10 kernel most panels still run does not. A Client-mode access point is bridged to the wired uplink and needs that, so the Wi-Fi page offers it in the VM and says "Needs Router mode: this kernel cannot bridge" on a 5.10 panel. Both are correct for the kernel underneath. The difference disappears as panels move to the 6.18 build, but until then a screenshot from here is not evidence about a 5.10 panel's Wi-Fi page.

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). Stage-2 init starts every panel daemon it finds, in the panel's own S-number order (warden-ai, warden-automation, warden-modbus, warden-mikrotik, warden-asic, warden-starlink, warden-stratum, warden-flared), then warden-ui (the LVGL fbdev+evdev build from flare-edge tools/build-ui-vm.sh). The quickest faithful payload is the daemons a bench panel already runs: flare-edge tools/rig-pull-daemons.sh --host <panel> copies them in. The RS485 UART is always present (a null chardev without --rs485), so warden-modbus polls a port with nothing on it, as on a panel with an empty header, and never the control channel.

The VT cursor is kept off (vt.global_cursor_default=0): fbcon shares the virtio-gpu framebuffer with warden-ui and its blinking cursor would otherwise show up in screendumps at random (issue #18).

The guest carries the panel's own /etc/passwd, /etc/shadow and /etc/group (root's md5-crypt of the documented default password), so a screen that verifies the root password against /etc/shadow behaves as it does on a panel instead of rejecting every attempt. qemu_stage_rootfs() (lib.sh) forces etc/shadow to mode 0600 on every stage: git tracks only the executable bit, so the checked-out source file's own mode depends on the checking-out umask and cannot be trusted to arrive non-world-readable.

Scenarios

All take the virt-fragment <zImage>; FLARE_EDGE=<checkout> where noted.

Scenario	Needs	Proves
stage-rootfs-perms.sh	-	offline, no VM: qemu_stage_rootfs() always lands etc/shadow at 0600, even staged from a source copy deliberately left 0644
seed-dir.sh	-	offline, no VM: mkimage.sh's SEED_DIR hook lands every seeded file under userdata/warden with its original mode (a 0600 secret included), a seeded file beats a same-named --state value, a SEED_DIR that isn't a directory fails closed, and so does an individual entry that is a symlink, a subdirectory, or named outside [A-Za-z0-9_.-]+ -- a hyphenated key such as gas-plant.devices still seeds cleanly
boot-smoke.sh	-	sentinel-asserting boot; runs in CI inside kernel-build
portal-scenario.sh	FLARE_EDGE	real flared against the desk mock portal: authenticated check-in, desired-state pull, signed tier-1 .wfw download; verify/stage/APPLYING as a dry run (no WARDEN_FW_ALLOW_APPLY)
ota-apply.sh	FLARE_EDGE	the FULL apply: the .wfw's bootable rootfs payload is written to rootfs_b (run.sh --allow-apply gates it per boot), the AvbABData in misc flips, and slot _b boots the applied version
ui-shot.sh	-	display+touch, headless: QMP-screendumps the 720x720 UI, taps the Metrics tab via input-send-event, asserts the frame changed (qmp.py is the QMP client)
ui-drive.sh <script>	-	the same rig for a SEQUENCE: boots once, runs a qmp.py drive script of taps/swipes/screenshots in panel pixels, and FAILS if warden-ui died on the way (stage-2 init announces the exit on the console). tests/scripts/nav-stress.txt is the navigation regression: it reproduces the s_row_left overflow that segfaulted the UI on returning to Settings > Apps; tests/scripts/home-leaves-fullscreen.txt proves the home verb clears dashboard fullscreen, the state a hardware wake tap leaves behind (flare-edge #176); tests/scripts/fullscreen-toggle-tracks-real-state.txt proves a fullscreen toggle right after home (or a real tap) reads the dashboard's actual state rather than a belief home bypassed -- test_qmp_drive.py's FullscreenToggleTracksRealState pins the same contract offline
real-image-boot.sh	matched rootfs.img + oem.img	an ACTUAL flare-edge build (placed by mkimage.sh --rootfs-image/--oem-image) boots its own init chain to getty; binaries predating known fixes reproduce their bugs faithfully, a time machine for field issues
test-ui-drive-rs485.sh	-	offline, no VM: a fake run.sh and (for one case) a fake socat stand in so ui-drive.sh --rs485-devices's startup fails closed instead of printing a false "== rs485 simulator: ..." over a bus nothing is serving, for each of a qemu rs.sock that never appears, a socat that never links rs.pty, and an mbsim.py that dies before opening rs.ctl; also proves cleanup() escalates to SIGKILL for a sim process that ignores SIGTERM
run-sh-args-test.sh	-	offline, no VM: a fake qemu-system-arm captures run.sh's own argv and pins the ctl/rs485 pci-serial ordering contract rootfs/sbin/init's ttyS0-vs-ttyS1 alias depends on -- the ctl device always enumerates before rs485, warden.ctl only lands on the cmdline when --ctl is given, and an rs485 pci-serial device (real or null-backed) is always present so the port count never shifts
watchdog (run.sh --watchdog)	-	arm /dev/watchdog, don't pet: the VM resets ~30 s later (verified)

Scenario fine print:

• OTA: the BCB slot CHOICE and the physical reset stay emulated by the harness (ADR-0006 boundary); the VM exports WARDEN_HARD_RESET=0 so flared's post-apply reset surfaces as a reported error, not a /dev/mem fault.
• Touch injection holds 200 ms: an instantaneous press+release lands inside one LVGL poll and never clicks.
• Watchdog + a flared payload don't mix: flared pets only while the UI heartbeat is fresh.

Gotchas

• AF_UNIX socket paths cap at ~108 chars; keep --rs485/--qmp paths 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=off and -global virtio-mmio.force-legacy=false are required (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.

Requirements

qemu-system-arm (Debian 13 ships QEMU 10), curl, cpio, mkfs.ext4, debugfs (both ship in e2fsprogs; seed-dir.sh reads a built partition back with it), 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).