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

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:

./local/scripts/build-redbear.sh redbear-desktop

Then run the automated QEMU harness:

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

./local/scripts/test-usb-qemu.sh redbear-desktop

Inside the guest

Run the packaged checker directly:

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 + bounded sector-0 readback + BOS + no crashes)
test-usb-storage-qemu.sh	USB mass storage autospawn + bounded sector-0 readback + crash pattern check
test-xhci-irq-qemu.sh --check	xHCI interrupt delivery mode (MSI/MSI-X/INTx)
test-usb-maturity-qemu.sh	Sequential wrapper for the bounded USB maturity checks

In-guest quick checks:

• lsusb — walks /scheme/usb.*, reads descriptors, shows vendor:product + quirks
• redbear-info --verbose — reports USB controller count and integration status
• redbear-usb-check — scheme tree walk with pass/fail exit code