From 81ff478c1b227b006c0c65c66e41f6c5727413b0 Mon Sep 17 00:00:00 2001 From: Vasilito Date: Tue, 14 Apr 2026 11:20:01 +0100 Subject: [PATCH] Add Red Bear OS implementation plan document Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus --- docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md | 327 +++++++++++++++++++++ docs/README.md | 1 + 2 files changed, 328 insertions(+) create mode 100644 docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md diff --git a/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md new file mode 100644 index 00000000..2d26823d --- /dev/null +++ b/docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md @@ -0,0 +1,327 @@ +# 07 — Red Bear OS Implementation Plan + +## Purpose + +This document defines a clear, practical implementation plan for Red Bear OS. It focuses on +building a usable, validated system through disciplined packaging, profile-based composition, and +incremental hardware enablement, while preserving Redox architecture: userspace drivers, services, +and capability-oriented system boundaries. + +This is the canonical public plan for how Red Bear OS should evolve at the repository level. +Detailed subsystem notes still live in focused documents such as +`local/docs/AMD-FIRST-INTEGRATION.md`, `docs/03-WAYLAND-ON-REDOX.md`, and +`docs/05-KDE-PLASMA-ON-REDOX.md`. + +## Core Principles + +### Preserve the architecture + +- Keep drivers and services in userspace. +- Preserve clear system boundaries and capability-based design. +- Stay aligned with upstream Redox where practical. + +### Packaging is the integration layer + +- Deliver functionality as packages and package groups. +- Compose profiles from packages rather than monolithic changes. +- Prefer packaging and configuration work over invasive core-tree rewrites when possible. + +### Keep Red Bear changes isolated + +- Place Red Bear-specific work under `local/` whenever possible. +- Keep upstream-facing areas clean and rebase-friendly. +- Use scripts and overlays to make sync/rebase work predictable. + +### Profiles are products + +The supported product surfaces are: + +- `redbear-minimal` +- `redbear-desktop` +- `redbear-full` +- `redbear-live` + +Each profile must be buildable, testable, and documented. + +### Validation over claims + +- “Compiles” is not the same as “supported”. +- Every user-visible feature must map to a profile. +- Support status must be explicit, reproducible, and evidence-backed. + +## System Structure + +### Layers + +1. **Upstream platform** — Redox kernel, libc, and core services +2. **Red Bear integration (`local/`)** — patches, recipes, configs, scripts, overlays +3. **Profiles** — concrete system builds assembled from packages and package groups + +### Profiles + +#### `redbear-minimal` + +Console-focused. + +- Boot +- Storage +- Package manager +- Wired networking + +This is the primary development and validation target. + +#### `redbear-desktop` + +Wayland plus base desktop services. + +This is the main integration environment for graphics, input, and desktop bring-up. + +#### `redbear-full` + +KDE Plasma target. + +This profile should only include graphics and networking paths that are validated enough to be +presented as real user-facing system behavior. + +#### `redbear-live` + +Live, demo, and rescue environment. + +This profile should prioritize diagnostics, recovery workflows, and installability. + +## Packaging Model + +### Package groups + +- `base-core` +- `storage-base` +- `desktop-base` +- `wayland-base` +- `kde-base` +- `net-base` +- `net-vm` +- `net-wired-common` +- `net-wifi-experimental` +- `gpu-intel-experimental` +- `gpu-amd-experimental` +- `redbear-branding` +- `redbear-live-tools` +- `redbear-hwdiag` + +### Rules + +- All functionality is delivered via packages. +- Drivers are packaged individually. +- Profiles depend on package groups. +- Package metadata should make support status obvious. + +## Workstreams + +### 1. Repository discipline + +Define and maintain contribution rules. + +- Keep all custom work under `local/` where possible. +- Provide scripts for rebasing, diffing, and resyncing upstream. +- Make repository governance visible and repeatable. + +**Outputs** + +- `local/docs/repo-governance.md` +- Maintenance scripts + +**Acceptance** + +- Custom work is easy to identify. +- Upstream sync work is predictable and documented. + +### 2. Profiles and packaging + +Formalize profile definitions and package-group composition. + +- Map each profile to package groups. +- Standardize package metadata and support labeling. +- Keep profile behavior reproducible. + +**Acceptance** + +- Profiles are reproducible and documented. + +### 3. Driver substrate + +Implement and stabilize the shared driver base. + +- `redox-driver-sys` for shared driver plumbing +- PCI, MMIO, IRQ, and DMA support +- Driver daemon template for new device work + +**Acceptance** + +- A new driver can be created from a known template. + +### 4. Graphics and Wayland + +Drive the graphical stack through concrete milestones. + +**Milestones** + +- Run one Wayland application +- Start KWin +- Launch Plasma shell + +**Acceptance** + +- At least one profile runs a real graphical session. + +### 5. Networking + +#### Architecture + +- Per-NIC driver daemons +- Network service for interfaces, DHCP, and routing +- D-Bus compatibility surface where desktop software expects it + +#### Milestones + +**N1: VM networking** + +- `virtio-net` +- DHCP and package access + +**N2: Wired hardware** + +- Intel NICs +- Realtek NICs + +**N3: KDE integration** + +- NetworkManager-compatible D-Bus subset + +**N4: Wi-Fi (experimental)** + +- Single chipset family first + +**Acceptance** + +- Wired networking works in at least one real profile. + +### 6. KDE integration + +- Package the D-Bus session path +- Provide a networking shim where KDE expects one +- Provide an audio compatibility layer where needed +- Package session startup and startup dependencies + +**Acceptance** + +- A KDE session launches and its limitations are documented. + +### 7. Live image and diagnostics + +- Hardware detection tools +- Network diagnostics +- Graphics diagnostics + +**Acceptance** + +- The live image can diagnose common failure cases. + +### 8. Validation and CI + +#### Support labels + +- `builds` +- `boots` +- `network` +- `wayland` +- `kde` +- `validated` +- `experimental` + +#### Tasks + +- VM-based tests +- Hardware validation matrix + +**Acceptance** + +- Support status is explicit and reproducible. + +## Development Phases + +### Phase A — Structure + +- Repository rules +- Profile definitions + +### Phase B — Minimal system + +- Boot +- Package management +- VM networking + +### Phase C — Driver base + +- Shared driver layer + +### Phase D — Graphics + +- Wayland +- Qt application bring-up + +### Phase E — Networking + +- Wired networking +- KDE-visible networking path + +### Phase F — Desktop + +- KDE session becomes usable + +### Phase G — Hardware validation + +- One fully validated profile + +### Phase H — Wi-Fi + +- Experimental expansion + +## Task Template + +Every substantial work item should capture: + +- **Title** +- **Objective** +- **Scope** +- **Files affected** +- **Dependencies** +- **Implementation notes** +- **Acceptance criteria** +- **Validation steps** +- **Risks** + +## Final Direction + +Red Bear OS should evolve as a profile-driven, package-defined system built on Redox architecture. +Progress should be measured by working profiles, not theoretical completeness. + +### Priority order + +1. Repository discipline +2. Profile reproducibility +3. VM usability +4. Graphics bring-up +5. Wired networking +6. KDE integration +7. Hardware validation +8. Wi-Fi expansion + +## Related Documents + +- [Root README](../README.md) +- [Architecture Overview](01-REDOX-ARCHITECTURE.md) +- [Gap Analysis & Roadmap](02-GAP-ANALYSIS.md) +- [Wayland on Redox](03-WAYLAND-ON-REDOX.md) +- [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) +- [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) +- [`local/docs/AMD-FIRST-INTEGRATION.md`](../local/docs/AMD-FIRST-INTEGRATION.md) diff --git a/docs/README.md b/docs/README.md index 6c9afaf0..920675b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ KDE Plasma desktop environment, and a Linux driver compatibility layer. | 04 | [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) | Design for a FreeBSD LinuxKPI-style driver compatibility shim | | 05 | [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) | Feasibility study and implementation plan for KDE Plasma | | 06 | [Build System Setup](06-BUILD-SYSTEM-SETUP.md) | How to build Redox from this repository | +| 07 | [Red Bear OS Implementation Plan](07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) | Canonical public implementation plan focused on profiles, packaging, validation, and staged hardware enablement | ## Current State Summary (as of 2026-04-14)