# 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

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

### Run aggregate

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

```bash
# 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:

```bash
# 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`:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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