RedBear-OS/local/docs/USB-VALIDATION-RUNBOOK.md

Red Bear OS USB Validation Runbook — v3

Companion to local/docs/USB-IMPLEMENTATION-PLAN.md v3. This runbook tells operators how to validate USB on a Red Bear build.

Validation matrix

Script	What it validates	Maturity target
test-xhci-irq-qemu.sh --check	xHCI interrupt-driven reactor path (line 208 of irq_reactor.rs)	validated-QEMU
test-xhci-device-lifecycle-qemu.sh --check	bounded USB attach/detach for HID + storage	validated-QEMU
test-usb-qemu.sh	full USB stack (xHCI + keyboard + tablet + storage)	validated-QEMU
test-usb-storage-qemu.sh	usbscsid autospawn + sector write+readback+restore	validated-QEMU
test-usb-runtime.sh	guest + QEMU mode dispatch harness	harness only
test-usb-maturity-qemu.sh	aggregate runner — calls the five above in sequence	runner
test-uhci-runtime-qemu.sh --check (P1-B)	UHCI controller enumeration on legacy QEMU machine	validated-QEMU (P1-B)
test-ohci-runtime-qemu.sh --check (P1-B)	OHCI controller enumeration on legacy QEMU machine	validated-QEMU (P1-B)
test-ehci-class-autospawn-qemu.sh --check (P1-A)	USB keyboard on EHCI route reaches inputd	validated-QEMU (P1-A)
test-usb-hub-qemu.sh --check (P3-A)	USB hub enumeration including power timing + wHubDelay	validated-QEMU (P3-A)
test-usb-error-recovery-qemu.sh --check (P8-C)	hot-unplug mid-transfer — graceful error, no panic	validated-QEMU (P8-C)
test-usb-uas-qemu.sh --check (P4-A)	USB 3.0 storage UAS path active	validated-QEMU (P4-A)

A row's last-passed ISO date goes in local/docs/HARDWARE-VALIDATION-MATRIX.md.

Path A — Host-side QEMU validation

Pre-flight

# Confirm the build is fresh
./local/scripts/build-redbear.sh --upstream redbear-mini
ls build/x86_64/redbear-mini/harddrive.img

Run aggregate

./local/scripts/test-usb-maturity-qemu.sh redbear-mini

This runs all five existing QEMU tests in sequence and reports a single pass/fail.

Run individual

# Interrupt-mode proof (must show "Running IRQ reactor with IRQ file
# and event queue" in the boot log; must NOT show "in polling mode").
./local/scripts/test-xhci-irq-qemu.sh --check

# Storage write+readback+restore (sector 2048; expects
# [PASS] STORAGE_DISCOVERY + STORAGE_WRITE + STORAGE_READBACK +
# STORAGE_RESTORE).
./local/scripts/test-usb-storage-qemu.sh

# Lifecycle proof (QEMU monitor-driven attach/detach).
./local/scripts/test-xhci-device-lifecycle-qemu.sh --check

What it validates vs. claims

Claim	Evidence
xhcid runs interrupt-driven	[RUNNING] IRQ reactor with IRQ file and event queue in log
usbscsid auto-spawns on storage attach	usbscsid: scheme event or [redbear-usb-storage-check] STORAGE_DISCOVERY: disk.usb-...
Storage read+write works	[PASS] STORAGE_WRITE: + [PASS] STORAGE_READBACK: + [PASS] STORAGE_RESTORE:
HID auto-spawns on keyboard attach	usbhidd: registered producer in log
No panics	absence of panic|crash|abort|RUST_BACKTRACE in log

Path B — In-guest manual validation

Boot the image and check:

# Inside the guest:
ls /scheme/usb*        # host controllers' scheme namespaces
lsusb                  # walker (in redbear-hwutils package)
redbear-usb-check      # pass/fail scheme validator

A healthy USB stack shows:

• /scheme/usb.0000:XX:XX.X_xhci/ (xhcid port directory)
• /scheme/usb/ (ehcid port directory)
• /scheme/disk.usb-...+...-scsi/ (usbscsid disk)
• /scheme/input/... (usbhidd device)

Path C — Bare-metal hardware validation (P8-A)

For each (controller, class, board) tuple in HARDWARE-VALIDATION-MATRIX.md:

# On the bare-metal host:
./local/scripts/build-redbear.sh <config>
dd if=build/x86_64/<config>/harddrive.img of=/dev/<target> bs=4M status=progress
# Boot; capture serial console
minicom -D /dev/ttyUSB0 -b 115200 -C capture.bin

# In the captured console:
redbear-info --verbose
lsusb
redbear-usb-check

Required test points (per row in the matrix):

1. Controller PCI ID detected
2. Specific class test (HID keypress, storage read+write, etc.)
3. Hot-plug works
4. Suspend/resume works (if device supports)

Update the matrix row: last_tested = <ISO date>, result = pass|fail|partial.

Operator runbook for failures

If test-xhci-irq-qemu.sh reports polling-mode:

# Check the boot log for the interrupt path:
grep "IRQ reactor" build/x86_64/redbear-mini/xhci-irq-check.log
# If "in polling mode" appears, xHCI interrupts are bypassed.
# Check the base fork commit:
git -C local/sources/base log --oneline drivers/usb/xhcid/src/main.rs | head -5
# Confirm commit cbd40e0d (or later) is in the merge base.

If test-usb-storage-qemu.sh reports a panic:

# Find the panic site:
grep -n 'panic\|unwrap\|expect' build/x86_64/redbear-mini/usb-storage-check.log
# Cross-reference to usbscsid:
grep -rn 'panic!' local/sources/base/drivers/storage/usbscsid/src/
# After P1-B is complete, no panic sites should exist.

If a USB device is not auto-spawning:

# Check if the class driver is wired in the configs:
grep -A2 "redbear-acmd\|redbear-ecmd\|redbear-usbaudiod" config/redbear-mini.toml
# Cross-check drivers.d:
cat local/config/drivers.d/70-usb-class.toml
# After P1-A, all four controllers should auto-spawn via the unified trait.

Validation cadence

• On every release branch cut: run all QEMU tests; update matrix with last-tested dates.
• On every P-phase completion: add the new test scripts to the matrix.
• Monthly: if any operator has bare-metal access, add one hardware row.

See also

• local/docs/USB-IMPLEMENTATION-PLAN.md v3 — the plan this runbook validates
• local/docs/HARDWARE-VALIDATION-MATRIX.md — the matrix this runbook populates
• local/scripts/test-usb-maturity-qemu.sh — the aggregate entry point