Update local docs for four compile targets

This commit is contained in:
2026-04-19 17:57:29 +01:00
parent cd41c52982
commit 370d27f44d
2 changed files with 71 additions and 58 deletions
+34 -5
View File
@@ -11,6 +11,7 @@ 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`
- a repeatable bounded xHCI lifecycle log via `./local/scripts/test-xhci-device-lifecycle-qemu.sh --check`
## Path A - Host-side QEMU validation
@@ -18,21 +19,22 @@ Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow.
### On the host
Build the tracked desktop profile first:
Build the tracked mini profile first:
```bash
./local/scripts/build-redbear.sh redbear-desktop
./local/scripts/build-redbear.sh redbear-mini
```
Then run the automated QEMU harness:
```bash
./local/scripts/test-usb-qemu.sh --check
./local/scripts/test-xhci-device-lifecycle-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
1. boots `redbear-mini` 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
@@ -40,9 +42,21 @@ What that harness does today:
6. checks for BOS descriptor processing (or graceful fallback for USB 2 devices)
7. checks that no crash-class errors appear in the log
What the lifecycle harness does today:
1. boots `redbear-mini` in QEMU with `qemu-xhci` and no pre-attached USB devices
2. logs into the guest over serial, then uses the QEMU monitor to hotplug a USB keyboard
3. requires xHCI attach and completion logs plus USB HID driver spawn evidence
4. uses one-shot guest-side `/tmp/xhcid-test-hook` commands to inject a bounded
post-`SET_CONFIGURATION` failure and a delayed attach-commit timing case
5. hot-unplugs the keyboard and requires detach evidence
6. hotplugs and hot-unplugs a USB storage device and requires attach/detach plus SCSI driver spawn evidence
7. fails on panic-class or teardown-class xHCI errors in the captured log
### Artifact to preserve
- the full terminal log from `./local/scripts/test-usb-qemu.sh --check`
- the full terminal log from `./local/scripts/test-xhci-device-lifecycle-qemu.sh --check`
## Path B - Interactive guest validation
@@ -51,7 +65,7 @@ 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
./local/scripts/test-usb-qemu.sh redbear-mini
```
### Inside the guest
@@ -83,6 +97,7 @@ enumerated, ports have devices attached, and device descriptors are readable.
- BOS/SuperSpeed capability detection
- HID class driver spawning (keyboard/tablet)
- SCSI class driver spawning (mass storage)
- bounded xHCI hotplug attach/detach lifecycle behavior for HID and storage devices in QEMU
- No panic or crash-class errors in USB daemons
## What this does not validate
@@ -91,7 +106,7 @@ enumerated, ports have devices attached, and device descriptors are readable.
- Hub topology (direct-attached devices only in the default harness)
- USB 3 SuperSpeed data paths
- Isochronous or streaming transfers
- Hot-plug stress testing
- Broad hot-plug stress testing on real hardware
- USB device mode / OTG / USB-C
## Existing USB test scripts
@@ -99,6 +114,7 @@ enumerated, ports have devices attached, and device descriptors are readable.
| Script | What it tests |
|--------|---------------|
| `test-usb-qemu.sh --check` | Full USB stack (xHCI + HID + SCSI + bounded sector-0 readback + BOS + no crashes) |
| `test-xhci-device-lifecycle-qemu.sh --check` | Bounded xHCI hotplug lifecycle proof for HID + storage attach/detach |
| `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 |
@@ -107,3 +123,16 @@ 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
## Compile-target note
Red Bear has exactly four compile targets:
- `redbear-mini`
- `redbear-live-mini`
- `redbear-full`
- `redbear-live-full`
Older names such as `redbear-desktop`, `redbear-wayland`, `redbear-kde`, and `redbear-minimal` may
still appear in historical notes or implementation details, but they are not the supported
compile-target surface.