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

Refresh project documentation

Browse Source 
Red Bear OS Team
This commit is contained in:
Vasilito
2026-04-16 12:46:07 +01:00
parent aeac5a6d92
commit 90fa45c545
32 changed files with 1659 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-REDOX-ARCHITECTURE.md
+5 -4
View File
@@ -132,10 +132,11 @@ driven wired setup.
### GPU Driver Status
- **No hardware-accelerated GPU drivers**
- Only BIOS VESA and UEFI GOP framebuffers
- Experimental Intel modesetting (Kaby Lake, Tiger Lake) — no acceleration
- AMD, NVIDIA, ARM, PowerVR: not supported
- Broad hardware-validated GPU acceleration is not yet available as a general support claim.
- BIOS VESA and UEFI GOP framebuffers remain the default proven display path.
- Experimental Intel modesetting exists.
- Red Bear also carries compile/integration-oriented AMD and Intel DRM work in its local overlay,
but that should not be read as broad hardware-validated acceleration support yet.
## 4. Orbital Display Server
docs/02-GAP-ANALYSIS.md
+2 -2
View File
@@ -19,7 +19,7 @@ Use the matrix below as the authoritative phase summary before reading the older
| P2 DRM / AMD+Intel display | Complete in-tree, hardware validation pending | `local/docs/P2-AMD-GPU-DISPLAY.md`, `local/recipes/gpu/redox-drm/`, `local/recipes/gpu/amdgpu/` |
| P3 POSIX + input | Implemented in-tree; consumer-visible `signalfd`/`timerfd`/`eventfd`/`open_memstream` header-export path fixed in this repo pass; runtime validation still pending | `recipes/core/relibc/source/src/header/`, `recipes/core/relibc/source/include/sys/signalfd.h`, `local/patches/relibc/`, `local/recipes/system/evdevd/`, `local/recipes/system/udev-shim/` |
| P4 Wayland stack | Partially complete | `recipes/wip/wayland/`, `recipes/wip/libs/other/libinput/`, `recipes/wip/services/seatd/` |
| P5 AMD acceleration / IOMMU | Partial | `local/recipes/gpu/amdgpu/`, `local/recipes/system/iommu/` (now buildable via surfaced recipe) |
| P5 AMD acceleration / IOMMU | Partial, but no longer blocked on basic QEMU first-use proof | `local/recipes/gpu/amdgpu/`, `local/recipes/system/iommu/` |
| P6 KDE Plasma | In progress with mixed real builds and stubs/shims | `config/redbear-kde.toml`, `local/recipes/kde/`, `local/docs/QT6-PORT-STATUS.md` |
### Ordered Remaining Gaps
@@ -27,7 +27,7 @@ Use the matrix below as the authoritative phase summary before reading the older
1. **Validate the completed P3→P4 bridge in practice**: `libwayland` now rebuilds with `signalfd`, `timerfd`, `eventfd`, `open_memstream`, `MSG_CMSG_CLOEXEC`, and `MSG_NOSIGNAL` restored, but compositor/runtime validation is still outstanding.
2. **Complete P4 runtime path**: libinput/seatd/GBM/Wayland compositor integration is still incomplete even though the base libraries now build, `seatd` now builds for Redox, and the KDE runtime config now starts a seatd service.
3. **Separate KDE real builds from scaffolding**: parts of the KDE stack are genuine builds, while others are shimmed or stubbed only to satisfy dependency resolution.
4. **Hardware validation remains open** for AMD/Intel DRM and the IOMMU path, even though the IOMMU daemon now builds.
4. **Hardware validation remains open** for AMD/Intel DRM and the IOMMU path, even though the IOMMU daemon now builds and its guest-driven QEMU first-use proof passes.
### P7 Note
docs/04-LINUX-DRIVER-COMPAT.md
+39 -1
View File
@@ -16,7 +16,45 @@
| `redox-drm` | Present and compiling in `local/recipes/gpu/redox-drm/` |
| Intel path | Compile-oriented, no hardware validation yet |
| AMD path | Compile-oriented via `amdgpu` + AMD DC port, no hardware validation yet |
| IOMMU | Partial — daemon now builds, hardware validation still TODO in `local/recipes/system/iommu/` |
| IOMMU | QEMU first-use proof present — daemon builds, AMD-Vi units initialize in QEMU, real hardware validation still open |
### Wi-Fi-facing note
Although this document is primarily about the LinuxKPI path for GPU-class drivers, the same compat
layer is now being exercised more directly by the bounded Intel Wi-Fi transport port as well.
In particular, the current tree now carries LinuxKPI-backed direct/async firmware helpers plus
exported timer, mutex, and IRQ save/restore bindings that the in-tree Intel Wi-Fi transport shim
can consume through actual Linux-style headers. That is still intentionally below the cfg80211 /
mac80211 boundary, but it makes the transport-facing Linux driver port more realistic than a pure
compile-only placeholder.
The tree now also contains the first explicit wireless-subsystem compatibility scaffolding inside
`linux-kpi` itself: initial `sk_buff`, `net_device`, `cfg80211` / `wiphy`, and `mac80211`
registration surfaces that compile and pass host-side crate tests. This should still be read as
foundational compatibility work, not as proof that Red Bear now has a complete Linux wireless stack
or working Intel Wi‑Fi connectivity.
On top of that, the bounded Intel path now also carries the first station-mode compatibility slice:
driver-side scan/connect/disconnect actions, control-daemon connect/disconnect flows, profile-
manager orchestration, and runtime-reporting surfaces that exercise those new LinuxKPI wireless
compatibility surfaces in host-side tests. This is still intentionally below real hardware
scan/auth/association/data-path proof.
Concrete repo entry points for that current bounded Wi‑Fi path are:
- `local/recipes/drivers/redbear-iwlwifi/` — bounded Intel driver-side package
- `local/recipes/system/redbear-wifictl/` — native Wi‑Fi control daemon and `/scheme/wifictl`
- `local/recipes/system/redbear-netctl/` — profile-manager orchestration and post-association handoff
- `local/recipes/system/redbear-info/` — runtime-reporting surface for Wi‑Fi lifecycle state
- `local/recipes/system/redbear-hwutils/` — packaged Wi‑Fi validation, capture, and analysis tools
- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` and `local/docs/WIFI-VALIDATION-RUNBOOK.md` — current
architecture and operator validation path
The validation claim here should also be read narrowly: the repo now has a clean host-side
`linux-kpi` test suite, passing bounded Intel shim/control-plane tests in the dependent crates, and
one host-side CLI flow test for the current Intel path. This is not a claim that a full Linux
Wi‑Fi stack is validated.
## Goal
docs/06-BUILD-SYSTEM-SETUP.md
+20
View File
@@ -123,6 +123,26 @@ make all
This produces `build/x86_64/desktop/harddrive.img`.
### Export External Toolchain
After `make prefix`, you can export a relocatable external cross toolchain that provides
`x86_64-unknown-redox-gcc` and the related host-side wrappers in one directory:
```bash
make export-toolchain TARGET=x86_64-unknown-redox
source build/toolchain-export/x86_64-unknown-redox/activate.sh
x86_64-unknown-redox-gcc --version
```
To export somewhere else:
```bash
make export-toolchain TARGET=x86_64-unknown-redox \
TOOLCHAIN_EXPORT_DIR=/opt/redbear/toolchains/x86_64-unknown-redox
```
For the full layout and rationale, see `local/docs/EXTERNAL-TOOLCHAIN.md`.
### Build with Specific Config
```bash
docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md
+18 -7
View File
@@ -324,10 +324,17 @@ Goal:
Current state:
- Wi-Fi is still missing,
- prerequisites exist,
- `linux-kpi` is only a partial low-level aid, not the Wi-Fi architecture itself,
- a native control plane is still required.
- one bounded experimental Intel Wi-Fi path is now in-tree,
- the corresponding tracked validation profile is `redbear-wifi-experimental`,
- `linux-kpi` now carries early wireless-subsystem compatibility scaffolding in addition to the
earlier low-level helper layer,
- the native control-plane/profile/reporting stack now has bounded scan/connect/disconnect flows,
including profile-manager start/stop wiring for the current Wi-Fi path,
- packaged in-target Wi-Fi validation/capture commands now exist for the current bounded Intel path
(`redbear-phase5-wifi-check`, `redbear-phase5-wifi-link-check`, `redbear-phase5-wifi-capture`,
`redbear-phase5-wifi-run`, `redbear-phase5-wifi-analyze`),
- real hardware scan/auth/association/data-path proof is still missing,
- `linux-kpi` is still not the Wi-Fi architecture by itself.
Canonical plan:
@@ -337,6 +344,8 @@ Acceptance:
- one experimental Wi-Fi family is packaged and evidence-backed,
- post-association handoff to the existing network stack is real,
- the bounded station-mode lifecycle is visible through driver, control-daemon, profile-manager,
and runtime-reporting surfaces,
- desktop-facing Wi-Fi claims remain honest and bounded.
### 6. Bluetooth
@@ -347,8 +356,10 @@ Goal:
Current state:
- Bluetooth is still missing,
- one bounded in-tree BLE-first experimental slice now exists,
- architecture direction is documented,
- the currently credible implementation target is one bounded BLE-first host-side slice rather than
broad desktop Bluetooth parity,
- transport dependency on USB maturity remains explicit.
Canonical plan:
@@ -357,8 +368,8 @@ Canonical plan:
Acceptance:
- one controller path, one host path, and one bounded user-facing workflow exist with experimental
support language.
- one controller path, one host path, and one bounded BLE-first user-facing workflow exist with
experimental support language.
### 7. Graphics, Wayland, and desktop/session compatibility
docs/AGENTS.md
+1
View File
@@ -43,6 +43,7 @@ docs/
| Which docs are current vs historical? | README | Document Status Matrix |
| What is the current WIP ownership policy? | local/docs/WIP-MIGRATION-LEDGER.md | Entire document |
| What do the main sync/fetch/apply/build scripts actually guarantee? | local/docs/SCRIPT-BEHAVIOR-MATRIX.md | Entire document |
| What is the current Wi-Fi architecture and validation path? | local/docs/WIFI-IMPLEMENTATION-PLAN.md / local/docs/WIFI-VALIDATION-RUNBOOK.md | Entire document |
| What is the current desktop-stack truth? | local/docs/DESKTOP-STACK-CURRENT-STATUS.md | Entire document |
| What is the current Qt/KF6 status? | local/docs/QT6-PORT-STATUS.md | Entire document |
| What's missing for Wayland? | 02 | Status correction + ordered remaining gaps |
docs/README.md
+18 -5
View File
@@ -49,16 +49,20 @@ current local subsystem plan.
| 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 |
| 08 | [Firmware in Red Bear OS](firmware.md) | Canonical firmware packaging, licensing, and runtime-loading policy |
## Related Red Bear-local plans
## Related Red Bear-local current-state plans
- `../local/docs/USB-IMPLEMENTATION-PLAN.md` — current USB completeness and rollout plan
- `../local/docs/WIFI-IMPLEMENTATION-PLAN.md` — current Wi-Fi architecture and rollout plan
- `../local/docs/WIFI-VALIDATION-RUNBOOK.md` — canonical operator path for bare-metal/VFIO Wi-Fi validation and evidence capture
- `../local/docs/WIFICTL-SCHEME-REFERENCE.md` — bounded `/scheme/wifictl` interface reference for the current Wi-Fi control surface
- `../local/recipes/system/redbear-netctl-console/source/` — Redox-native ncurses terminal client for the bounded Wi-Fi profile flow
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — guarantees and non-guarantees for the main Wi-Fi and Bluetooth validation helpers plus core repo scripts
- `../local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — current Bluetooth architecture and rollout plan
- `../local/docs/BLUETOOTH-VALIDATION-RUNBOOK.md` — canonical operator path for the bounded Bluetooth Battery Level QEMU validation slice
- `../local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — current low-level controller and IRQ blocker plan
- `../local/docs/AMD-FIRST-INTEGRATION.md` — AMD-focused technical roadmap; historical AMD-first sequencing, not current platform-priority policy
- `../local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership and upstream-vs-local migration ledger
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee
- `../local/docs/PROJECT-DOCUMENTATION-ASSESSMENT.md` — current assessment of documentation quality, canon, and remaining cleanup priorities
- `../local/docs/DESKTOP-STACK-CURRENT-STATUS.md` — canonical current build/runtime truth summary for the desktop stack
@@ -66,6 +70,12 @@ These local Red Bear plans should be treated as first-class subsystem references
Bluetooth, and low-level controller work. They carry blocker detail that the public docs summarize
at a higher level.
## Related Red Bear-local governance docs
- `../local/docs/WIP-MIGRATION-LEDGER.md` — current WIP ownership and upstream-vs-local migration ledger
- `../local/docs/SCRIPT-BEHAVIOR-MATRIX.md` — what the main sync/fetch/apply/build scripts do and do not guarantee
- `../local/docs/EXTERNAL-TOOLCHAIN.md` — how to export a relocatable external `x86_64-unknown-redox-gcc` toolchain from the built prefix
## Current State Summary (as of 2026-04-15)
This summary is only a quick orientation layer. For canonical current-state detail, prefer:
@@ -83,9 +93,12 @@ This summary is only a quick orientation layer. For canonical current-state deta
- **Mesa**: software-rendered path is present; full GBM / hardware-validated Wayland path is still incomplete.
- **GPU drivers**: redox-drm scheme daemon and AMD+Intel compile-oriented paths exist; 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, and RTL8125 is wired into the existing Realtek autoload path
- **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.
- **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 is now QEMU-validated through a packaged in-guest checker plus a host harness; broad desktop Bluetooth parity is still incomplete
- **KDE**: `redbear-kde.toml` exists and the recipe tree is populated, but the runtime stack is still incomplete.
- **Linux driver compat**: linux-kpi (31 C headers + 13 Rust FFI), redox-driver-sys, firmware-loader all compile.
- **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.
## Quick Start
docs/firmware.md
+85
View File
@@ -0,0 +1,85 @@
# Firmware in Red Bear OS
## Purpose
This document defines the Red Bear firmware policy.
Firmware is treated as third-party runtime content, not as normal project source code.
## Basic Rules
- firmware is third-party
- firmware licenses vary by vendor and artifact
- firmware remains under its own licenses
- firmware is redistributed unmodified
- firmware is loaded at runtime from the filesystem
- firmware should not be embedded into driver binaries
## Source and Packaging Model
Red Bear should package firmware separately from the core OS logic.
Recommended package-group model:
- `firmware-base`
- `firmware-intel`
- `firmware-amd`
- `firmware-wifi`
The current Red Bear package path for the broad upstream firmware corpus is:
- `local/recipes/system/redbear-firmware/`
That package is intended to stage firmware under:
- `/lib/firmware/`
License metadata should remain clearly separated inside the firmware tree, for example under:
- `/lib/firmware/LICENSES/`
## Licensing and Redistribution
The practical downstream model is the same one used by Linux distributions:
- Linux distributions ship `linux-firmware` as a separate package
- the operating system itself can remain under its own license
- firmware stays under the vendor license documented in `WHENCE` and related license files
Red Bear should follow the same model.
Do not claim a single Red Bear repo-wide license applies to the firmware blobs themselves.
## What Red Bear Must Not Do
- do not claim firmware is MIT just because Red Bear OS code is MIT-like or permissive
- do not remove vendor license files or `WHENCE`
- do not modify firmware blobs
- do not merge firmware blobs into normal source trees without clear separation
- do not assume every blob is redistributable without checking upstream `WHENCE` / license metadata
## Runtime Loading Rule
Drivers and userspace daemons should request firmware from the filesystem at runtime.
For Red Bear, the canonical runtime path is:
- `/lib/firmware/...`
The current helper daemon for that model is:
- `firmware-loader` providing `scheme:firmware`
This keeps the architecture cleaner and legally safer than embedding blobs into binaries.
## Upstream References
- upstream firmware source: `linux-firmware`
- upstream license and redistribution metadata: `WHENCE`
- vendor-specific license files: `LICENCE.*`, `LICENSE*`
## Bottom Line
Red Bear can distribute a Linux-firmware-derived firmware package, but it must do so as separate
firmware content with its own license metadata, installed under `/lib/firmware/`, and loaded at
runtime rather than compiled into project binaries.