Update hardware utilities and USB validation

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-04-17 00:04:08 +01:00
parent 054acba072
commit d20d44df15
7 changed files with 583 additions and 21 deletions
@@ -0,0 +1,103 @@
+# Red Bear OS USB Validation Runbook
+
+This runbook is the canonical operator path for exercising the USB stack on Red Bear OS.
+
+It does not claim that USB is broadly solved. Its job is to make the current QEMU-validated USB
+workload reproducible and honest.
+
+## Goal
+
+Produce one or both of the following:
+
+- a successful USB stack validation via `redbear-usb-check` inside the guest
+- a repeatable QEMU/UEFI validation log via `./local/scripts/test-usb-qemu.sh --check`
+
+## Path A - Host-side QEMU validation
+
+Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow.
+
+### On the host
+
+Build the tracked desktop profile first:
+
+```bash
+./local/scripts/build-redbear.sh redbear-desktop
+```
+
+Then run the automated QEMU harness:
+
+```bash
+./local/scripts/test-usb-qemu.sh --check
+```
+
+What that harness does today:
+
+1. boots `redbear-desktop` in QEMU with `qemu-xhci`, USB keyboard, USB tablet, and USB mass storage
+2. captures the full boot log over serial
+3. checks for xHCI interrupt-driven mode in the log
+4. checks for USB HID driver spawn
+5. checks for USB SCSI driver spawn
+6. checks for BOS descriptor processing (or graceful fallback for USB 2 devices)
+7. checks that no crash-class errors appear in the log
+
+### Artifact to preserve
+
+- the full terminal log from `./local/scripts/test-usb-qemu.sh --check`
+
+## Path B - Interactive guest validation
+
+Use this when you want to inspect the runtime manually inside the guest.
+
+### On the host
+
+```bash
+./local/scripts/test-usb-qemu.sh redbear-desktop
+```
+
+### Inside the guest
+
+Run the packaged checker directly:
+
+```bash
+redbear-usb-check
+```
+
+Expected output:
+
+```
+redbear-usb-check: found N usb scheme entries: [...]
+redbear-usb-check:   xhci.0 -> M ports
+redbear-usb-check:     port 1 -> vendor:product [device name]
+redbear-usb-check:     port 2 -> vendor:product [device name] [SS]
+redbear-usb-check: xhci controllers: ["xhci.0"]
+redbear-usb-check: all checks passed
+```
+
+The checker walks `/scheme/usb/` and `/scheme/xhci/` to verify that the xHCI controller is
+enumerated, ports have devices attached, and device descriptors are readable.
+
+## What this validates
+
+- xHCI controller initialization
+- USB device enumeration and descriptor fetching
+- BOS/SuperSpeed capability detection
+- HID class driver spawning (keyboard/tablet)
+- SCSI class driver spawning (mass storage)
+- No panic or crash-class errors in USB daemons
+
+## What this does not validate
+
+- Real hardware USB controllers (QEMU qemu-xhci only)
+- Hub topology (direct-attached devices only in the default harness)
+- USB 3 SuperSpeed data paths
+- Isochronous or streaming transfers
+- Hot-plug stress testing
+- USB device mode / OTG / USB-C
+
+## Existing USB test scripts
+
+| Script | What it tests |
+|--------|---------------|
+| `test-usb-qemu.sh --check` | Full USB stack (xHCI + HID + SCSI + BOS) |
+| `test-usb-storage-qemu.sh` | USB mass storage autospawn |
+| `test-xhci-irq-qemu.sh --check` | xHCI interrupt delivery mode |