vasilito
1bc5f8ac88
v3 USB-IMPLEMENTATION-PLAN supersedes v2 (archived). Comprehensive
audit-driven roadmap with 9 phases (P1–P9) to make USB a first-class
citizen in Red Bear OS:
P1: Trait unification (all 4 controllers implement UsbHostController)
+ panic hardening (usbscsid 0 panics, xhcid <20 unwraps)
+ remove 3 empty stubs (usbaudiod, acmd, ecmd)
P2: xHCI core — 51-quirk table, HCCPARAMS2 parsing, 36-code error
recovery (babble, transaction error, stall, split)
P3: Hub driver — full enumeration (wHubDelay, power timing, USB 3 SS)
+ interrupt-driven change detection + port LED
P4: Storage — UAS protocol, multi-LUN, SYNCHRONIZE_CACHE, UNMAP, mass-storage
quirks applied at runtime
P5: HID — report descriptor parser, usage→evdev mapping, LED sync, quirks,
multi-touch
P6: Class driver completeness — CDC ACM, CDC NCM, USB Audio, USB-serial
(FTDI/CP210x/PL2303/CH341), compliance test driver
P7: Power management — USB 2.0 LPM, USB 3.0 U1/U2/U3, runtime PM autosuspend
P8: Validation — hardware matrix ≥10 rows + 6 new QEMU scripts
+ error-injection tests
P9: Modern USB scope ADR (host-only; already written in v2 §12)
Linux 7.1 is the implementation of excellence — every feature has a
concrete cross-reference (file:line) and a 'port line-by-line' strategy
when implementation detail is in doubt.
USB-VALIDATION-RUNBOOK v3 replaces v2 (archived): test matrix with
per-phase exit gates, operator runbook for failures.
Stale items cleared:
- v2 active plan archived as USB-IMPLEMENTATION-PLAN-v2-2026-07.md
- v2 active runbook archived as USB-VALIDATION-RUNBOOK-2026-07.md
- archived/README.md supersession table extended
155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# 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 |