qemu: display + touch scenario, ADR-0006, docs
Phase 4+5 of the device sim: - Display + touch verified end-to-end: virtio-gpu at 720x720 (fbdev emulation) renders the real WardenOS dashboard from the static LVGL fbdev+evdev UI build (flare-edge qemu-vm-support tools/build-ui-vm.sh); QMP input-send-event taps the Metrics tab and qemu/tests/ui-shot.sh asserts the repaint from screendumps. Two load-bearing QEMU flags found and documented: -global virtio-mmio.force-legacy=false (gpu/input are VERSION_1-only) and the 200ms press hold (an instantaneous press+release lands inside one LVGL indev poll and never clicks). - qemu/tests/qmp.py: minimal QMP client (screendump, tap, quit). - stage-2 init starts warden-ui when present and fb0 exists. - docs/decisions/0006-qemu-device-sim.md: virt-not-custom-board, the enters-at-kernel boundary, fragment policy, naming, consequences. - docs/architecture.md: new section 7 (device emulation), order-of-work item 7; modbus cross-reference to the bridge. - qemu/README.md: emulated-vs-not table, scenarios, gotchas, host/runner requirements. docs/ci-cd.md: runner needs one-time qemu-system-arm install (fail-closed smoke until then, [maintainer]-gated). Repo README updated. Final sweep on this commit: shellcheck clean, bridge 7/7 tests, boot smoke PASS, portal scenario PASS (check-in + fw pull + signed .wfw download), ui-shot PASS (touch navigates to Metrics) — all under the final flags. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018HUayid7W5w7jBdb9Rrj1K
This commit is contained in:
BFE Engineering
co-authored by
Claude Fable 5
Claude Fable 5
parent
c7e06514ad
commit
13b7d063a2
+75
-21
@@ -2,46 +2,100 @@
|
||||
|
||||
A QEMU virtual machine that boots the real forward-ported kernel (`build/` +
|
||||
`patches/`) and real userspace, so the *device* — init, daemons, networking,
|
||||
OTA, watchdog — can be tested off-hardware. The third simulator in the stack,
|
||||
deliberately not named "sim":
|
||||
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.
|
||||
- `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` (generic ARMv7 machine, virtio peripherals). That means:
|
||||
`-M virt,highmem=off` (single Cortex-A7, 256M — the RV1106G3's shape).
|
||||
|
||||
- **Not emulated, not tested here:** BootROM, idblock/DDR-init, SPL, U-Boot,
|
||||
the real BCB-driven A/B slot selection, bootcount auto-revert. The untested
|
||||
A/B rollback chain stays untested by this tool.
|
||||
- **Substituted, not modeled:** display (virtio-gpu, not VOP), input
|
||||
(virtio-tablet, not GT911), network (virtio-net, not GMAC), storage
|
||||
(virtio-blk, not eMMC). NPU/RGA/HPMCU behavior stays `sim/` territory.
|
||||
- "Boots under emulation" is **not** "works on silicon". On-device claims
|
||||
still need on-device evidence; the VM narrows which claims need a panel.
|
||||
| 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
|
||||
|
||||
```sh
|
||||
# 1. build the QEMU kernel variant (canonical RV1106 build + virt fragment)
|
||||
# 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. build the initramfs (sha256-pinned static busybox + qemu/rootfs/)
|
||||
# 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. smoke it
|
||||
bash qemu/tests/boot-smoke.sh $HOME/kbuild-out/linux-6.18.46/arch/arm/boot/zImage
|
||||
# 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
|
||||
```
|
||||
|
||||
Host requirements: `qemu-system-arm` (Debian 13 ships QEMU 10), `curl`, `cpio`,
|
||||
`gcc-arm-linux-gnueabihf` for the kernel build.
|
||||
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.
|
||||
|
||||
Status: bringup — boot smoke only. Disk/network harness, RS485 bridge to
|
||||
`sim/`, portal scenarios, and display/touch land in later phases (see
|
||||
`docs/decisions/0006-qemu-device-sim.md` once written).
|
||||
## Scenario tests (`qemu/tests/`)
|
||||
|
||||
- `boot-smoke.sh <zImage>` — sentinel-asserting boot; runs in CI inside the
|
||||
kernel-build job.
|
||||
- `portal-scenario.sh <zImage>` (needs `FLARE_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 `.wfw`
|
||||
offer. Verify/stage/APPLYING run as a dry run (no `WARDEN_FW_ALLOW_APPLY`);
|
||||
flipping it on inside the VM is the documented stretch — apply writes
|
||||
`/dev/block/by-name/rootfs_b` inside disk.img, then `--slot _b` boots it.
|
||||
- `ui-shot.sh <zImage>` — display+touch: boots headless with virtio-gpu,
|
||||
QMP-screendumps the 720x720 UI, taps the Metrics tab via `input-send-event`
|
||||
(a 200 ms hold — an instantaneous press+release lands inside one LVGL poll
|
||||
and never clicks), and asserts the frame changed. `qmp.py` is the tiny QMP
|
||||
client.
|
||||
- Watchdog: `run.sh --watchdog`, arm `/dev/watchdog` in 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`/`--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 load-bearing
|
||||
(32-bit ECAM reach; virtio-1-only gpu/input) — both live in run.sh.
|
||||
- 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 on the self-hosted kernel-build runner, which
|
||||
needs a one-time `apt-get install qemu-system-arm` (see docs/ci-cd.md).
|
||||
|
||||
@@ -77,6 +77,14 @@ for d in /usr/bin/warden-flared /usr/bin/warden-modbus; do
|
||||
fi
|
||||
done
|
||||
|
||||
# The UI (LVGL fbdev+evdev build from flare-edge tools/build-ui-vm.sh) needs
|
||||
# virtio-gpu's fbdev: present only with run.sh --display on|headless AND the
|
||||
# virt.fragment kernel.
|
||||
if [ -x /usr/bin/warden-ui ] && [ -c /dev/fb0 ]; then
|
||||
echo "init: starting warden-ui (fbdev)"
|
||||
/usr/bin/warden-ui > /tmp/warden-ui.log 2>&1 &
|
||||
fi
|
||||
|
||||
if grep -qw warden.shell /proc/cmdline; then
|
||||
echo "warden.shell: interactive shell (exit powers off)"
|
||||
setsid cttyhack sh
|
||||
|
||||
@@ -78,6 +78,9 @@ fi
|
||||
APPEND="console=ttyAMA0 rdinit=/init"
|
||||
ARGS=(
|
||||
-M "virt,highmem=off" -cpu cortex-a7 -smp 1 -m 256M
|
||||
# virtio-mmio defaults to the legacy (0.9) transport; virtio-gpu and
|
||||
# virtio-input are VERSION_1-only devices and never bind without this.
|
||||
-global "virtio-mmio.force-legacy=false"
|
||||
-kernel "$KERNEL" -initrd "$INITRD"
|
||||
-netdev "user,id=n0,hostfwd=tcp:127.0.0.1:${SSH_PORT}-:22,hostfwd=tcp:127.0.0.1:${HTTP_PORT}-:80,hostfwd=tcp:127.0.0.1:${API_PORT}-:28443"
|
||||
-device "virtio-net-device,netdev=n0"
|
||||
|
||||
Executable
+62
@@ -0,0 +1,62 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Tiny QMP client for the qemu/ device-sim tests.
|
||||
|
||||
qmp.py <socket> screendump <out.ppm>
|
||||
qmp.py <socket> tap <x> <y> # absolute 0..32767 (virtio-tablet)
|
||||
qmp.py <socket> quit
|
||||
"""
|
||||
import json
|
||||
import socket
|
||||
import sys
|
||||
import time
|
||||
|
||||
|
||||
def rpc(sock, obj):
|
||||
sock.sendall((json.dumps(obj) + "\n").encode())
|
||||
while True:
|
||||
line = sock_file.readline()
|
||||
if not line:
|
||||
raise RuntimeError("QMP connection closed")
|
||||
msg = json.loads(line)
|
||||
if "return" in msg:
|
||||
return msg["return"]
|
||||
if "error" in msg:
|
||||
raise RuntimeError(f"QMP error: {msg['error']}")
|
||||
# asynchronous events are interleaved; skip them
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 3:
|
||||
sys.exit(__doc__)
|
||||
path, cmd = sys.argv[1], sys.argv[2]
|
||||
global sock_file
|
||||
s = socket.socket(socket.AF_UNIX)
|
||||
s.connect(path)
|
||||
sock_file = s.makefile("r")
|
||||
sock_file.readline() # greeting banner
|
||||
rpc(s, {"execute": "qmp_capabilities"})
|
||||
|
||||
if cmd == "screendump":
|
||||
rpc(s, {"execute": "screendump", "arguments": {"filename": sys.argv[3]}})
|
||||
elif cmd == "tap":
|
||||
x, y = int(sys.argv[3]), int(sys.argv[4])
|
||||
press = [
|
||||
{"type": "abs", "data": {"axis": "x", "value": x}},
|
||||
{"type": "abs", "data": {"axis": "y", "value": y}},
|
||||
{"type": "btn", "data": {"down": True, "button": "left"}},
|
||||
]
|
||||
release = [{"type": "btn", "data": {"down": False, "button": "left"}}]
|
||||
rpc(s, {"execute": "input-send-event", "arguments": {"events": press}})
|
||||
# Hold the press across several LVGL indev poll periods (33 ms each):
|
||||
# an instantaneous press+release lands inside one poll and no click
|
||||
# is ever registered.
|
||||
time.sleep(0.2)
|
||||
rpc(s, {"execute": "input-send-event", "arguments": {"events": release}})
|
||||
elif cmd == "quit":
|
||||
s.sendall(b'{"execute":"quit"}\n')
|
||||
else:
|
||||
sys.exit(f"unknown command {cmd}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Executable
+92
@@ -0,0 +1,92 @@
|
||||
#!/usr/bin/env bash
|
||||
# Display + touch scenario: boot the VM headless with virtio-gpu, wait for the
|
||||
# LVGL UI (fbdev build) to start, screendump over QMP, inject an absolute
|
||||
# touch tap (virtio-tablet), screendump again. Asserts the first frame is
|
||||
# non-blank; reports (does not assert) whether the tap changed pixels — the
|
||||
# device-level analogue of flare-edge's Xvfb/xdotool sim-test.sh.
|
||||
#
|
||||
# FAILS CLOSED on missing prerequisites.
|
||||
#
|
||||
# Usage: ui-shot.sh <zImage-virt> [out-dir]
|
||||
set -euo pipefail
|
||||
|
||||
HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # qemu/tests/
|
||||
QDIR="$(cd "$HERE/.." && pwd)" # qemu/
|
||||
|
||||
ZIMAGE="${1:-}"
|
||||
OUTDIR="${2:-$QDIR/out}"
|
||||
if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
|
||||
echo "FATAL: usage: $0 <zImage> [out-dir] — the virt.fragment kernel variant" >&2
|
||||
exit 1
|
||||
fi
|
||||
[ -x "$QDIR/payload/warden-ui" ] || {
|
||||
echo "FATAL: no qemu/payload/warden-ui — build it with flare-edge tools/build-ui-vm.sh" >&2
|
||||
exit 1
|
||||
}
|
||||
command -v qemu-system-arm >/dev/null || {
|
||||
echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Short-named scratch: AF_UNIX socket paths are capped at ~108 chars.
|
||||
WORK="$(mktemp -d /tmp/wqu.XXXXXX)"
|
||||
QEMU_PID=""
|
||||
cleanup() {
|
||||
if [ -n "$QEMU_PID" ]; then kill "$QEMU_PID" 2>/dev/null || true; fi
|
||||
rm -rf "$WORK"
|
||||
}
|
||||
trap cleanup EXIT
|
||||
|
||||
bash "$QDIR/mkinitramfs.sh"
|
||||
bash "$QDIR/mkimage.sh"
|
||||
|
||||
PORT=$((21000 + RANDOM % 20000))
|
||||
bash "$QDIR/run.sh" --kernel "$ZIMAGE" --display headless --qmp "$WORK/qmp.sock" \
|
||||
--ssh-port "$PORT" --http-port $((PORT + 1)) --api-port $((PORT + 2)) \
|
||||
> "$WORK/console.log" 2>&1 &
|
||||
QEMU_PID=$!
|
||||
|
||||
deadline=$((SECONDS + 120))
|
||||
while [ $SECONDS -lt $deadline ]; do
|
||||
grep -aq 'init: starting warden-ui' "$WORK/console.log" && break
|
||||
kill -0 "$QEMU_PID" 2>/dev/null || { echo "FATAL: VM exited early" >&2; tail -25 "$WORK/console.log" >&2; exit 1; }
|
||||
sleep 2
|
||||
done
|
||||
grep -aq 'init: starting warden-ui' "$WORK/console.log" || {
|
||||
echo "FATAL: warden-ui never started (no fb0? wrong kernel?)" >&2
|
||||
tail -25 "$WORK/console.log" >&2
|
||||
exit 1
|
||||
}
|
||||
sleep 8 # let LVGL render the first frames
|
||||
|
||||
qmp() { python3 "$HERE/qmp.py" "$WORK/qmp.sock" "$@"; }
|
||||
|
||||
qmp screendump "$WORK/shot1.ppm"
|
||||
# Tap the "Metrics" tab: pixel (373,40) of 720x720 scaled to the QMP absolute
|
||||
# range 0..32767 — switching tabs must repaint the content area.
|
||||
qmp tap 16975 1820
|
||||
sleep 3
|
||||
qmp screendump "$WORK/shot2.ppm"
|
||||
|
||||
mkdir -p "$OUTDIR"
|
||||
cp "$WORK/shot1.ppm" "$OUTDIR/ui-shot1.ppm"
|
||||
cp "$WORK/shot2.ppm" "$OUTDIR/ui-shot2.ppm"
|
||||
|
||||
# Non-blank: more than one distinct pixel value in the raw PPM payload.
|
||||
python3 - "$WORK/shot1.ppm" <<'EOF'
|
||||
import sys
|
||||
data = open(sys.argv[1], "rb").read()
|
||||
# P6 header: magic, dims, maxval, then raw RGB
|
||||
parts = data.split(b"\n", 3)
|
||||
pixels = parts[3] if len(parts) == 4 else b""
|
||||
distinct = len(set(pixels[i:i+3] for i in range(0, min(len(pixels), 3*720*720), 3)))
|
||||
print(f"shot1: {len(pixels)} bytes of pixels, {distinct} distinct colors")
|
||||
sys.exit(0 if distinct > 1 else 1)
|
||||
EOF
|
||||
|
||||
if cmp -s "$WORK/shot1.ppm" "$WORK/shot2.ppm"; then
|
||||
echo "FATAL: tapping the Metrics tab did not change the frame — touch is not reaching the UI" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "tap on the Metrics tab repainted the frame (touch reached the UI)"
|
||||
echo "UI-SHOT-PASS (screenshots in $OUTDIR/ui-shot{1,2}.ppm)"
|
||||
Reference in New Issue
Block a user