Update local docs for four compile targets
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user