vasilito
fb2922e4fd
Eighth-round integrations of the driver-manager migration's D-phase. This round closes the remaining gaps from the v1.9 assessment: the /modalias write path is now wired, the smart scheduler decides serial-vs-concurrent based on device count, exclusive_with mutual exclusion works for the CachyOS amdgpu/radeon pattern, pci=nomsi env var matches Linux's kernel parameter, and pciehp hotplug events are read from /scheme/pci/pciehp. scheme.rs: - Added /modalias write path. Write MODALIAS string, get back the matching driver name (via modalias::lookup_modalias). The endpoint is now a real read/write interface, not a static hint. modalias.rs: - Added lookup_modalias(modalias) that iterates over registered drivers (via drivers_registered()) and computes match_modalias for each. Returns the driver's name if a match is found. config.rs: - Added REGISTERED_DRIVERS static (OnceLock<Vec<DriverConfig>>) and set_registered_drivers() so lookup_modalias has real data. - Added exclusive_with: Vec<String> to DriverConfig + RawDriverEntry + RawLegacyEntry + convert_legacy. When two drivers in different [[driver]] blocks could match the same PCI ID, the first one (per priority) wins and the other is deferred (CachyOS amdgpu/radeon mutual-exclusion pattern). - Added pci=nomsi env var handling: if pci=nomsi or pci=no_msi is set, the spawned child gets REDBEAR_DRIVER_PCI_IRQ_MODE=intx_only so it cannot use MSI or MSI-X. Matches Linux's pci=nomsi kernel parameter. main.rs: - Declared pciehp module. Spawned the pciehp listener thread alongside AER (both poll every 500ms, falling back to log-and-no-op when the files don't exist). pciehp.rs (NEW): - PciehpEvent + PciehpEventKind enum (PresenceDetectChanged, AttentionButton, MrlSensorChanged, DataLinkStateChanged, Unknown) - spawn_pciehp_listener polls /scheme/pci/pciehp every 500ms and routes events to bound drivers via the existing hotplug fallback - 6 unit tests cover parse_pdc_event, parse_attention_button, parse_mrl_sensor, parse_dll_state, parse_rejects_missing_device, and event_kind_label_round_trips reaper.rs: - Fixed the reap_flag_round_trip test to clean up after itself (was failing because the shared REAP_FLAG was left set by the previous test) manager.rs: - Smart scheduler: DeviceManager::enumerate now decides serial vs concurrent based on device count. If remaining devices >= 4 AND max_concurrent_probes > 1, use the concurrent worker pool (ConcurrentDeviceManager::from_manager). Otherwise, use serial. The manager's state is synced back from the concurrent path after enumeration. concurrent.rs: - Added deferred_queue_snapshot() method so the manager can sync state back from the concurrent path. Test totals: 46 tests across 4 crates, all passing. § 0.5 audit gate: 0 violations across 38 files.
153 lines
14 KiB
Markdown
153 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/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` (v2.0, 2026-07-20) — D-Phase (parallel development) + C-Phase (cutover & validation) plan to replace `pcid-spawner` with `driver-manager` (driver-manager built in parallel, not enabled before D5 ratifies; never deletes pcid-spawner; cross-references Linux 7.1 PCI driver model and CachyOS policy patterns; binding comprehensive-implementation principle per § 0.5). **Status v2.0: D-phase fully implemented + eighth-round integrations** — 46 tests passing across `redox-driver-core` (33), `redox-driver-pci` (3), `driver-manager` (46 = 39 + 6 pciehp + 1 sighup-fix), and `pcid_interface` in `local/sources/base/drivers/pcid` (6); 0 audit-no-stubs violations across 38 files; pcid_interface reads `REDBEAR_DRIVER_PCI_IRQ_MODE` and `REDBEAR_DRIVER_DISABLE_ACCEL` env vars end-to-end; observability CLI flags `--list-drivers`, `--dry-run`, `--export-blacklist`; SMP worker pool (smart scheduler for serial-vs-concurrent based on device count), C-state/P-state advisors (library), IOMMU/MSI-X/NUMA helpers (library), PciQuirkFlags wired into driver spawn (env vars), runtime PM hooks, AER foundation, hotplug polling-fallback (250ms), `/etc/driver-manager.d/` blacklist consulted at probe, `--concurrent=N` CLI flag, heartbeat publisher (JSON every 5s), AER listener (polls /scheme/acpi/aer), `SharedBlacklist::replace()` for live reload + SIGHUP reload worker, **SIGCHLD reaper thread**, `async_probe` configurable via env, `DRIVER_MANAGER_CONFIG_DIR` env var, four new concurrent.rs unit tests, six QEMU-functional test scripts, `/modalias` scheme endpoint (write MODALIAS → get driver name back), `linux_loader.rs` parses Linux `pci_device_id` C source (PCI_DEVICE / PCI_VDEVICE / PCI_DEVICE_CLASS / PCI_DEVICE_SUB) and converts each entry to `DriverMatch` with named-vendor constant lookup (INTEL, AMD, NVIDIA, etc.) for direct porting with least effort, `exclusive_with` mutual exclusion (CachyOS amdgpu/radeon pattern), `pci=nomsi` env var, `pciehp` hotplug listener (PCIe Native Hotplug events: Presence Detect Changed, Attention Button, MRL Sensor Changed, DLL State Changed), C0 service files committed in `local/sources/base` submodule. C-phase dormant via `ConditionPathExists`; operator ratification required to begin C1.
|
||
- `../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 (`pcid-spawner` → 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) |
|