vasilito
d20d44df15
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
104 lines
2.9 KiB
Markdown
104 lines
2.9 KiB
Markdown
# 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 |
|