vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update local docs for four compile targets

Browse Source
This commit is contained in:
Vasilito
2026-04-19 17:57:29 +01:00
parent cd41c52982
commit 370d27f44d
2 changed files with 71 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/PROFILE-MATRIX.md
+37 -53
View File
@@ -18,7 +18,7 @@ USB plan uses:
- **enumerates** — runtime surfaces can discover controllers, ports, or descriptors - **enumerates** — runtime surfaces can discover controllers, ports, or descriptors
- **usable** — a specific controller/class path works in a limited real scenario - **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 > **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 > `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 | | 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-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-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-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-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-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-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-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 |
| `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 |
## Profile Notes ## Profile Notes
### `redbear-minimal` ### `redbear-mini`
- First place to validate repository discipline and profile reproducibility. - First place to validate repository discipline and profile reproducibility.
- Should stay smaller and less assumption-heavy than the graphics profiles. - 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. - 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. - 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` ### `redbear-bluetooth-experimental`
- Standalone tracked profile for the first in-tree Bluetooth slice instead of a blanket claim about - 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 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. 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 ## Bluetooth Note
- `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile. - `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile.
@@ -117,14 +102,13 @@ USB plan uses:
## USB Note ## USB Note
- `redbear-desktop` is the primary profile carrying USB stack components (xHCI, HID, mass storage) - `redbear-mini` is the preferred non-graphics target for bounded USB validation because these
and the only profile where USB is validated and support-scoped. 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 - USB validation is QEMU-only (`test-usb-qemu.sh --check`). No profile makes a real hardware USB
support claim. support claim.
- USB error handling and correctness carry significant Red Bear patches over upstream; see - 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. `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`, - The in-tree mini image is still assembled through legacy `redbear-minimal*` config files in some
and `usbctl`. These binaries are present in the image but USB is not validated or support-scoped places, but the supported compile-target names are `redbear-mini` and `redbear-live-mini`.
for this profile.
- `redbear-bluetooth-experimental` uses USB only as a transport for BLE dongles; it does not make a - `redbear-bluetooth-experimental` uses USB only as a transport for BLE dongles; it does not make a
general USB-class-autospawn claim. general USB-class-autospawn claim.
local/docs/USB-VALIDATION-RUNBOOK.md
+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 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 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 ## 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 ### On the host
Build the tracked desktop profile first: Build the tracked mini profile first:
```bash ```bash
./local/scripts/build-redbear.sh redbear-desktop ./local/scripts/build-redbear.sh redbear-mini
``` ```
Then run the automated QEMU harness: Then run the automated QEMU harness:
```bash ```bash
./local/scripts/test-usb-qemu.sh --check ./local/scripts/test-usb-qemu.sh --check
./local/scripts/test-xhci-device-lifecycle-qemu.sh --check
``` ```
What that harness does today: 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 2. captures the full boot log over serial
3. checks for xHCI interrupt-driven mode in the log 3. checks for xHCI interrupt-driven mode in the log
4. checks for USB HID driver spawn 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) 6. checks for BOS descriptor processing (or graceful fallback for USB 2 devices)
7. checks that no crash-class errors appear in the log 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 ### Artifact to preserve
- the full terminal log from `./local/scripts/test-usb-qemu.sh --check` - 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 ## 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 ### On the host
```bash ```bash
./local/scripts/test-usb-qemu.sh redbear-desktop ./local/scripts/test-usb-qemu.sh redbear-mini
``` ```
### Inside the guest ### Inside the guest
@@ -83,6 +97,7 @@ enumerated, ports have devices attached, and device descriptors are readable.
- BOS/SuperSpeed capability detection - BOS/SuperSpeed capability detection
- HID class driver spawning (keyboard/tablet) - HID class driver spawning (keyboard/tablet)
- SCSI class driver spawning (mass storage) - 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 - No panic or crash-class errors in USB daemons
## What this does not validate ## 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) - Hub topology (direct-attached devices only in the default harness)
- USB 3 SuperSpeed data paths - USB 3 SuperSpeed data paths
- Isochronous or streaming transfers - Isochronous or streaming transfers
- Hot-plug stress testing - Broad hot-plug stress testing on real hardware
- USB device mode / OTG / USB-C - USB device mode / OTG / USB-C
## Existing USB test scripts ## Existing USB test scripts
@@ -99,6 +114,7 @@ enumerated, ports have devices attached, and device descriptors are readable.
| Script | What it tests | | Script | What it tests |
|--------|---------------| |--------|---------------|
| `test-usb-qemu.sh --check` | Full USB stack (xHCI + HID + SCSI + bounded sector-0 readback + BOS + no crashes) | | `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-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-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 | | `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 - `lsusb` — walks `/scheme/usb.*`, reads descriptors, shows vendor:product + quirks
- `redbear-info --verbose` — reports USB controller count and integration status - `redbear-info --verbose` — reports USB controller count and integration status
- `redbear-usb-check` — scheme tree walk with pass/fail exit code - `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.