vasilito
f09a094993
Comprehensive 3D userland plan based on direct code audit of the
Mesa 26.1.4 build, redox-drm Intel backend, virgl runtime path,
amdgpu C port, and libdrm enablement. Seven critical gaps identified
that block all hardware-accelerated 3D rendering on Red Bear OS
beyond llvmpipe fallback:
1. Mesa gallium-drivers=softpipe,llvmpipe,virgl — NO iris, NO crocus,
NO radeonsi. The README/CHANGELOG claim that 'all 6 Red Bear
Mesa patches are wired' is incorrect: only 5 are wired; patches
03 and 06 are orphans because patch 03 targets
src/egl/drivers/dri2/platform_redox.c which does not exist in
Mesa 26.1.4 upstream (the file was removed). Patches 03/06
cannot be cleanly reapplied — they need re-creation against
the current Mesa API.
2. No 'redox' EGL platform in Mesa 26.1.4. EGL_PLATFORM=wayland
resolves to swrast (llvmpipe) on Redox. virgl and iris are
never auto-selected.
3. No Mesa winsys for Redox (src/gallium/winsys/redox/ does not
exist). The virgl driver uses upstream's generic
virgl_drm_winsys which depends on libdrm's redox.patch to
redirect ioctls to scheme:drm.
4. Intel kernel backend supports only Gen9–Gen14 (Meteor Lake).
No Lunar Lake (Xe2, Gen15) device IDs. No Panther Lake (Xe3,
Gen16) device IDs. The display version table stops at 14.
5. No Vulkan built (vulkan-drivers= empty). No anv (Intel), no
radv (AMD), no venus (virtio-gpu Vulkan).
6. The redox_private_cs_submit ABI exists in redox-drm (real
implementation for Intel ring submission with seqno tracking,
space-wait, MI_FLUSH_DW) but no Mesa gallium driver consumes it.
7. The amdgpu C port is display-only (DC modeset, no render/3D).
It does NOT provide a Mesa radeonsi winsys. Stages 2-4 of the
amdgpu recipe are intentionally empty (no Linux TTM/core
source).
The plan file (786 lines) covers:
- Verified code state from direct read (Mesa recipe, Intel
backend, virgl, amdgpu, libdrm)
- Reality-vs-claim corrections (6 overclaims in current docs)
- Hardware-acceleration status table (10 paths)
- 7-phase execution plan with explicit acceptance criteria
for each phase:
Phase 1: Validate current virgl runtime path (1-2 weeks)
Phase 2: Add Lunar Lake and Panther Lake device IDs
Phase 3: Restore the Redox EGL platform (re-create)
Phase 4: Add Intel iris (Gen8-Gen14) — biggest piece, 8-12 weeks
Phase 5: Add AMD radeonsi — 6-8 weeks
Phase 6: Vulkan (enables anv/radv) — 2-4 weeks
Phase 7: Panther Lake kernel driver — 12-16 weeks
- Validation matrix per vendor
- File-level change catalog
- Risk register
- Operating rule: 'code presence is not support; build success
is not support; llvmpipe is not acceleration; an env-override
that requires manual setup is not a runtime path'.
154 lines
14 KiB
Markdown
154 lines
14 KiB
Markdown
# Red Bear OS Documentation Index
|
||
|
||
Technical documentation for Red Bear OS, a full fork on top of Redox OS.
|
||
|
||
This index is the entry point for the documentation set. Its main job is to make the
|
||
current/canonical versus historical/reference split obvious.
|
||
|
||
> **Status note (2026-07-18):** The canonical desktop path document is
|
||
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0, single comprehensive plan). It supersedes
|
||
> all earlier individual assessments and is the single authority for current state.
|
||
> The historical docs below (01–05) remain useful for architecture reference and implementation
|
||
> rationale, but they should be read together with the new plan and the current local subsystem docs.
|
||
|
||
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0) for current state.
|
||
|
||
> **Red Bear note:** newer subsystem plans can also live under `local/docs/` when they are Red Bear-
|
||
> specific rather than general Redox architecture material. In particular, see
|
||
> `local/docs/WIFI-IMPLEMENTATION-PLAN.md` for the current Wi-Fi direction,
|
||
> and `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path.
|
||
|
||
> **Repository model:** RedBearOS relates to Redox in the same way Ubuntu relates to Debian.
|
||
> Upstream Redox remains the base platform; Red Bear carries packaging, patch, validation, and
|
||
> subsystem release fork on top. For long-term stability, upstream-owned source trees should be treated
|
||
> as immutable archived release snapshot, while durable Red Bear state belongs in `local/patches/`,
|
||
> `local/recipes/`, `local/docs/`, and tracked Red Bear configs.
|
||
>
|
||
> **WIP policy:** if an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a
|
||
> local project until upstream promotes it to first-class status. We may immutable archived from upstream WIP,
|
||
> but we should fix and ship from the Red Bear release fork until upstream support is real enough to
|
||
> replace the local copy.
|
||
|
||
## Document Status Matrix
|
||
|
||
| Document set | Role |
|
||
|---|---|
|
||
| `README.md`, `AGENTS.md`, `docs/README.md`, `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` | canonical repository-level policy and current execution model |
|
||
| `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` | **canonical comprehensive implementation plan** — supersedes all individual subsystem docs |
|
||
| `local/docs/*IMPLEMENTATION-PLAN*.md`, `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` | subsystem plans for deep-dive detail only; authority chain → console-to-KDE plan |
|
||
| `docs/01-REDOX-ARCHITECTURE.md` | architecture reference |
|
||
| `docs/04-LINUX-DRIVER-COMPAT.md`, `docs/05-KDE-PLASMA-ON-REDOX.md` | valuable but partly historical roadmap/design material |
|
||
|
||
When a current-state local document conflicts with an older historical public roadmap, prefer the
|
||
console-to-KDE plan.
|
||
|
||
## Documents
|
||
|
||
| # | Document | Description |
|
||
|---|----------|-------------|
|
||
| 01 | [Architecture Overview](01-REDOX-ARCHITECTURE.md) | Architecture reference for Redox internals: microkernel, scheme system, driver model, display stack |
|
||
| 04 | [Linux Driver Compatibility Layer](04-LINUX-DRIVER-COMPAT.md) | Historical/current hybrid design reference for the LinuxKPI-style driver compatibility model |
|
||
| 05 | [KDE Plasma on Redox](05-KDE-PLASMA-ON-REDOX.md) | Historical KDE implementation path plus deeper KDE-specific rationale |
|
||
| 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 |
|
||
|
||
## Related Red Bear-local current-state plans
|
||
|
||
**Consolidation (2026-04-30)**: 13 standalone assessment docs deleted. All current state is now in
|
||
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0). Individual subsystem plans remain for detail:
|
||
|
||
- `../local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — **CANONICAL** comprehensive plan: kernel→DRM→Mesa→Wayland→KDE path
|
||
- `../local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md` — kernel credential syscalls + IPC (implemented)
|
||
- `../local/docs/3D-DRIVER-PLAN.md` (2026-07-24) — Mesa 26.1.4 + virgl + Intel iris (Gen9–Gen14) + AMD radeonsi + Panther Lake (Xe3) — **3D userland path** (verified code state, 7 critical gaps, 7-phase execution plan)
|
||
- `../local/docs/USB-IMPLEMENTATION-PLAN.md` — USB completeness and rollout
|
||
- `../local/docs/WIFI-IMPLEMENTATION-PLAN.md` — Wi-Fi architecture and rollout
|
||
- `../local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — Bluetooth architecture and rollout
|
||
- `../local/docs/ACPI-IMPROVEMENT-PLAN.md` — ACPI ownership, robustness, validation
|
||
- `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — PCI/IRQ quality, MSI/MSI-X
|
||
- `../local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` — DRM-focused execution (subsystem detail)
|
||
- `../local/docs/DRIVER-MANAGER-MIGRATION-PLAN.md` (v4.0, 2026-07-24) — migration from `pcid-spawner` to `driver-manager`. **CUTOVER COMPLETE (2026-07-23, operator-ratified):** driver-manager owns the boot-time PCI match/claim/spawn path in every `redbear-*` config; pcid-spawner is retired from configs and gated behind `/etc/driver-manager.d/disabled` as the operator fallback (never deleted). See `../local/docs/evidence/driver-manager/ASSESSMENT-2026-07-22.md` (major assessment, findings B1–G10 + § 11 services integration). Delivered: claim-via-channel collapse (pcid `ENOLCK` exclusivity — the pcid-spawner model); init `ConditionPathExists` gate (systemd-style, `!` negation); spawned-mode `pci_register_driver` in linux-kpi (honors `PCID_CLIENT_CHANNEL` — single ownership of match-claim-spawn for native and Linux-port daemons); linux-kpi real MSI/MSI-X via pcid_interface + `pci_request_regions` + `pcie_capability_*` + PM state; redbear-iwlwifi `--daemon` onboarding + `70-wifi.toml`; `--import-linux-ids` Linux id_table→TOML pipeline; scheme operator surface (`bind`/`unbind`/`new_id`/`remove_id`/`driver_override`/`rescan`); Tier-1 driver_override; success-triggered deferred retry; concurrent probes with real `Driver::probe()`; real SIGCHLD/SIGHUP handlers; heartbeat counters; AER `route_to_driver`; `exclusive_with` mutual exclusion; `pci=nomsi` env var; PciQuirkFlags spawn env hints + `REDBEAR_DRIVER_{IOMMU_GROUP,NUMA_NODE,MSIX_VECTORS}`; driver-params bridge live; D-Bus correctly absent (bridge-on-demand). Gate: PASSED in QEMU q35 (initfs ahcid bind, rootfs e1000d concurrent bind, scheme live, resident hotplug). Platform finding: `thread::scope` hangs on Redox (spawn+join used instead). Cookbook now hashes Cargo path-dep sources (staleness hole closed). Open: P2-1 pcid AER/pciehp producers, P3 policy/hygiene. 93 tests pass; 0 audit-no-stubs violations; zero crate-local warnings on host and redox target.
|
||
- `../local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` — Wayland compositor (subsystem detail)
|
||
- `../local/docs/archived/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` — relibc IPC surface
|
||
- `../local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md` — greeter/login design
|
||
- `../local/docs/DBUS-INTEGRATION-PLAN.md` — D-Bus architecture
|
||
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — script guarantees and non-guarantees
|
||
- `../local/docs/QUIRKS-SYSTEM.md` — hardware quirks infrastructure
|
||
|
||
These local Red Bear plans should be treated as first-class subsystem references for desktop/session,
|
||
USB, Wi-Fi, Bluetooth, and low-level controller work. They carry blocker detail that the public docs
|
||
summarize at a higher level.
|
||
|
||
For PCI/IRQ language specifically, prefer the local IRQ plan’s distinction between:
|
||
|
||
- compile-visible infrastructure,
|
||
- bounded QEMU/runtime proof,
|
||
- and broader hardware validation.
|
||
|
||
Do not flatten those into one “supported” claim in public summaries.
|
||
|
||
## Related Red Bear-local governance docs
|
||
|
||
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee
|
||
|
||
## Current State Summary (as of 2026-07-18)
|
||
|
||
This summary is only a quick orientation layer. For canonical current-state detail, see `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` (v6.0).
|
||
|
||
- `docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md` for repository-wide execution order,
|
||
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical comprehensive plan,
|
||
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for support-language by tracked profile,
|
||
- and the active subsystem plans under `local/docs/` for detailed current workstreams.
|
||
|
||
- **Compile targets**: the supported compile targets are `redbear-mini`, `redbear-full`, and `redbear-grub`
|
||
- **Live ISO policy**: live `.iso` outputs (`build-redbear.sh`) are for real bare-metal boot/install/recovery workflows, not the VM/QEMU execution surface.
|
||
- **Wayland**: libwayland + wayland-protocols built. A bounded greeter/compositor-backed login proof now passes, but broader compositor/runtime stability remains incomplete.
|
||
- **Qt6**: qtbase 6.11.1 (Core+Gui+Widgets+DBus+Wayland), qtdeclarative, qtsvg, qtwayland ALL BUILT
|
||
- **D-Bus**: 1.16.2 built for Redox. Qt6DBus enabled.
|
||
- **KF6 Frameworks**: 40/40 built. See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for full breakdown.
|
||
- **Mesa**: software-rendered path is present; full GBM / hardware-validated Wayland path is still incomplete.
|
||
- **GPU drivers**: redox-drm scheme daemon exists; Intel build-oriented path exists; AMD currently has a bounded retained compile path (`redox-drm` + Red Bear glue) while the imported Linux AMD DC/TTM/core trees remain builds and included in redbear-full (2026-04-29). Hardware validation is still pending.
|
||
- **Input**: evdevd compiled, libevdev built, libinput 1.30.2 built
|
||
- **Networking**: native wired stack present (`driver-manager` → NIC daemon → `smolnetd`/`dhcpd`/`netcfg`), Red Bear ships a native `netctl` command, RTL8125 is wired into the existing Realtek autoload path, and the bounded Intel Wi‑Fi path now has host-tested profile start/stop plus interface-specific DHCP handoff without claiming real wireless connectivity.
|
||
- **PCI / IRQ quality**: architecturally strong substrate exists, with bounded MSI-X, IOMMU, xHCI IRQ, and low-level-controller proof surfaces; broader hardware robustness is still intentionally tracked as open work in `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`
|
||
- **Wi-Fi profile target**: `config/redbear-wifi-experimental.toml` is the first explicit tracked image slice for bounded Intel Wi‑Fi validation, instead of spreading that claim across the generic desktop profiles.
|
||
- **Bluetooth**: one bounded in-tree BLE-first experimental slice exists, and the Battery Level read-only workload now has a packaged in-guest checker plus a host QEMU harness; QEMU validation is still in progress, so broad desktop Bluetooth parity is still incomplete
|
||
- **Desktop direction**: `redbear-full` carries the desktop-capable target surface; the bounded greeter/login slice now passes, while the wider desktop runtime stack is still incomplete.
|
||
- **ACPI**: materially complete for the historical boot baseline, not release-grade complete; implemented: AML mutex real state, EC widened accesses via byte transactions, kstop-based shutdown eventing, explicit `RSDP_ADDR` forwarding into `acpid`, x86 BIOS-search AML fallback, and real-but-provisional AML-backed power enumeration. **Known gaps**: the explicit boot-path producer contract for AML bootstrap is still underdocumented, `acpid` startup hardening remains open, shutdown/power reporting are still provisional, sleep state transitions and sleep eventing remain incomplete, DMAR ownership is still transitional, and bare-metal validation is still bounded. See `local/docs/ACPI-IMPROVEMENT-PLAN.md`.
|
||
- **Linux driver compat**: linux-kpi now includes early wireless-subsystem compatibility scaffolding in addition to the earlier helper layer, redox-driver-sys and firmware-loader compile, and the bounded Intel Wi-Fi path now has host-tested scan/connect/disconnect/profile/reporting flows without claiming real hardware Wi-Fi connectivity.
|
||
- **Wi-Fi validation tooling**: `redbear-phase5-wifi-check` and `redbear-phase5-wifi-capture` are now packaged in-guest helpers for bounded Intel Wi-Fi runtime validation and evidence capture on bare metal or VFIO-backed guests.
|
||
- **Phase 5 naming note**: the bounded `redbear-phase5-network-check` / `test-phase5-network-qemu.sh` path proves desktop/network plumbing on `redbear-full` in QEMU; it does **not** mean the Wi-Fi implementation plan's later Phase W5 real-hardware reporting/recovery milestone is complete.
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# 1. Install dependencies (Arch/Manjaro)
|
||
sudo pacman -S --needed --noconfirm gdb meson nasm patchelf python-mako \
|
||
doxygen expat file fuse3 gmp libjpeg-turbo libpng po4a scons \
|
||
sdl12-compat syslinux texinfo xdg-utils zstd
|
||
|
||
# 2. Install Rust + tools
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
|
||
source "$HOME/.cargo/env"
|
||
cargo install just cbindgen
|
||
|
||
# 3. Configure for native build (no Podman)
|
||
echo 'PODMAN_BUILD?=0' > .config
|
||
|
||
# 4. Build (canonical command — produces live ISO)
|
||
./local/scripts/build-redbear.sh redbear-mini
|
||
|
||
# 5. Run in QEMU
|
||
make qemu
|
||
```
|
||
|
||
## Key Repositories
|
||
|
||
| Repo | Purpose | URL |
|
||
|------|---------|-----|
|
||
| All Red Bear sources | Single-Repo Rule canonical source | https://gitea.redbearos.org/vasilito/RedBear-OS |
|
||
| Kernel (reference) | Microkernel | https://gitlab.redox-os.org/redox-os/kernel (reference) |
|
||
| Base (reference) | Drivers + system components | https://gitlab.redox-os.org/redox-os/base (reference) |
|
||
| relibc (reference) | C library (Rust) | https://gitlab.redox-os.org/redox-os/relibc (reference) |
|
||
| RedoxFS (reference) | Default filesystem | https://gitlab.redox-os.org/redox-os/redoxfs (reference) |
|
||
| libredox (reference) | System library | https://gitlab.redox-os.org/redox-os/libredox (reference) |
|