diff --git a/local/docs/PROFILE-MATRIX.md b/local/docs/PROFILE-MATRIX.md index 1b430350..dd7b9b19 100644 --- a/local/docs/PROFILE-MATRIX.md +++ b/local/docs/PROFILE-MATRIX.md @@ -18,7 +18,7 @@ USB plan uses: - **enumerates** — runtime surfaces can discover controllers, ports, or descriptors - **usable** — a specific controller/class path works in a limited real scenario -## Tracked Profiles +## Compile Targets > **Phase numbering note:** phase labels below use the v2.0 desktop plan phases from > `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. Scripts and older docs may reference the @@ -26,24 +26,47 @@ USB plan uses: | Profile | Intent | Key Fragments | Current support language | |---|---|---|---| -| `redbear-minimal` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline / DHCP boot profile enabled / input-runtime substrate wired / USB: daemons built via base but not validated or support-scoped for this profile | -| `redbear-bluetooth-experimental` | First bounded Bluetooth validation profile | `redbear-bluetooth-experimental.toml`, `redbear-bluetooth-services.toml`, `redbear-minimal.toml` | builds / boots in QEMU / packaged Battery Level checker + QEMU harness present / QEMU validation still in progress / explicit-startup USB BLE-first only / not generic GATT / not USB-class-autospawn | -| `redbear-wifi-experimental` | First bounded Intel Wi-Fi validation profile | `redbear-wifi-experimental.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / experimental bounded Intel Wi-Fi slice / driver + control/profile/reporting stack present / packaged in-target validation and capture commands available / real hardware connectivity still unproven | -| `redbear-desktop` | Supplementary Red Bear integration support profile without KDE-specific session wiring | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / input-runtime substrate wired / runtime reporting installed / USB: xHCI host present + HID keyboard/mouse usable + mass storage autospawns in QEMU / QEMU-validated only / no real hardware USB claim | -| `redbear-wayland` | v2.0 Phase 2 Wayland compositor validation profile | `wayland.toml` | builds / boots in QEMU / experimental software-path graphics-runtime slice / validation-only | -| `redbear-full` | Broader desktop/network/session plumbing (spans v2.0 Phases 2–3) | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / boots in QEMU / D-Bus system bus wired / experimental runtime path | -| `redbear-kde` | v2.0 Phases 3–4 KWin Wayland target desktop profile | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / tracked KWin desktop direction / D-Bus+seatd+sessiond+KWin session surface wired | -| `redbear-live` | Live and recovery image layered on desktop | `redbear-kde.toml` | builds / follows the tracked KWin desktop target | +| `redbear-mini` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline / DHCP boot profile enabled / input-runtime substrate wired / USB: daemons built via base and targeted for bounded mini-profile validation | +| `redbear-live-mini` | Live/recovery form of the mini baseline | `redbear-live-minimal.toml`, `redbear-minimal.toml` | builds / live media variant of the mini profile / desktop graphics intentionally absent | +| `redbear-full` | Desktop/network/session plumbing target | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml`, `redbear-greeter-services.toml` | builds / boots in QEMU / active desktop-capable compile target / support claims remain evidence-qualified | +| `redbear-live-full` | Live/recovery form of the full desktop target | `redbear-live-full.toml`, `redbear-full.toml` | builds / live desktop-capable image / inherits the full target surface | ## Profile Notes -### `redbear-minimal` +### `redbear-mini` - First place to validate repository discipline and profile reproducibility. - Should stay smaller and less assumption-heavy than the graphics profiles. - Enables the shared `wired-dhcp` netctl profile by default for the VM/wired baseline. - Ships the shared firmware/input runtime service prerequisites so the early substrate can be tested on the smallest profile as well. +### Historical and experimental overlays + +- Experimental overlays such as `redbear-bluetooth-experimental` and `redbear-wifi-experimental` + are bounded validation slices layered on top of the tracked compile targets, not additional + compile targets. + +### `redbear-live-mini` + +- Carries the same bounded non-graphics intent as `redbear-mini`, but in live/recovery image form. +- Should not grow desktop/session assumptions. + +### `redbear-full` + +- Desktop-capable tracked target for the current Red Bear session/network/runtime plumbing surface. +- Carries the broader D-Bus, greeter, seat, and desktop-oriented service surface. + +### `redbear-live-full` + +- Live/demo/recovery form of the full desktop-capable target. +- Inherits the same desktop-target assumptions as `redbear-full`, but for live media workflows. + +### Historical notes + +- Older names such as `redbear-minimal`, `redbear-desktop`, `redbear-wayland`, `redbear-kde`, and + `redbear-live` remain in older docs and some implementation details, but they are not the current + supported compile-target surface. + ### `redbear-bluetooth-experimental` - Standalone tracked profile for the first in-tree Bluetooth slice instead of a blanket claim about @@ -67,44 +90,6 @@ USB plan uses: connect/disconnect lifecycle, packaged in-target validation and capture commands, and no claim yet of validated real AP association or end-to-end Wi-Fi connectivity. -### `redbear-desktop` - -- Carries the standard Red Bear integration package additions. -- Inherits shared behavior while avoiding the heavier KDE session-specific wiring. -- Now includes the shared firmware/input runtime service fragment used by the wider desktop bring-up path. -- Also includes `redbear-info`, making this profile a main runtime-reporting integration environment. -- This remains available as a supplementary integration support profile. - -### `redbear-wayland` - -- Wraps the repo's existing `wayland.toml` into a tracked Red Bear validation target. -- Serves as the v2.0 Phase 2 compositor validation surface. -- Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase4-wayland-check`, with the compositor reaching xkbcommon initialization and EGL platform selection on Redox. -- Current QEMU renderer evidence is still software-based (`llvmpipe` on the current `-vga std` harness), so this profile must not be described as a hardware-accelerated desktop proof yet. -- Treat this profile as the bounded Wayland/Qt regression harness. -- The intended desktop direction is `redbear-kde` with KWin Wayland. - -### `redbear-full` - -- Used for broader desktop/session plumbing after the narrower `redbear-wayland` validation slice. -- Current role: carry D-Bus system-bus plumbing together with the native Red Bear network stack (spans v2.0 Phases 2–3). -- Current verified path: QEMU/UEFI boot to login prompt plus guest-side `redbear-phase5-network-check`, with functional VirtIO networking, `DBUS_SYSTEM_BUS=present`, and bounded UPower/UDisks2 runtime-backed enumeration. -- Should not be described as fully supported until runtime validation is evidence-backed. -- This bounded QEMU Phase 5 proof is not the same thing as the Wi-Fi plan's later Phase W5 real-hardware runtime-reporting-and-recovery exit criteria. - -### `redbear-kde` - -- Dedicated profile for the intended KWin Wayland desktop path. -- Keep KDE-specific service wiring here instead of leaking it into the generic desktop profile. -- Current role: carry the KWin session launch surface and its D-Bus/seatd dependencies in one image (v2.0 Phases 3–4). -- This is the tracked compositor/session direction. - -### `redbear-live` - -- Intended for install, demo, and recovery workflows. -- Should inherit only stable desktop-profile assumptions unless explicitly documented. -- It now inherits `redbear-kde` so the live image follows the tracked desktop direction. - ## Bluetooth Note - `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile. @@ -117,14 +102,13 @@ USB plan uses: ## USB Note -- `redbear-desktop` is the primary profile carrying USB stack components (xHCI, HID, mass storage) - and the only profile where USB is validated and support-scoped. +- `redbear-mini` is the preferred non-graphics target for bounded USB validation because these + proofs do not require the full desktop graphics/session surface. - USB validation is QEMU-only (`test-usb-qemu.sh --check`). No profile makes a real hardware USB support claim. - USB error handling and correctness carry significant Red Bear patches over upstream; see `local/patches/base/redox.patch` and `local/docs/USB-IMPLEMENTATION-PLAN.md` for details. -- `redbear-minimal` inherits the base recipe which builds `xhcid`, `usbhidd`, `usbhubd`, `usbscsid`, - and `usbctl`. These binaries are present in the image but USB is not validated or support-scoped - for this profile. +- The in-tree mini image is still assembled through legacy `redbear-minimal*` config files in some + places, but the supported compile-target names are `redbear-mini` and `redbear-live-mini`. - `redbear-bluetooth-experimental` uses USB only as a transport for BLE dongles; it does not make a general USB-class-autospawn claim. diff --git a/local/docs/USB-VALIDATION-RUNBOOK.md b/local/docs/USB-VALIDATION-RUNBOOK.md index 19a64705..284998df 100644 --- a/local/docs/USB-VALIDATION-RUNBOOK.md +++ b/local/docs/USB-VALIDATION-RUNBOOK.md @@ -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.