Update project root docs and contribution guidance

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
2026-04-18 17:58:13 +01:00
parent 42c60f989c
commit 73d10558c1
4 changed files with 51 additions and 43 deletions
+8 -8
View File
@@ -27,13 +27,13 @@ project is in the right shape for long-term maintenance.
```
redox-master/
├── config/ # Build configs (TOML): desktop, server, wayland, x11, minimal
├── config/ # Build configs (TOML): tracked redbear-* targets plus mainline references
├── mk/ # Makefile fragments: config.mk, repo.mk, prefix.mk, disk.mk, qemu.mk
├── recipes/ # Package recipes (TOML + source). 26 categories. See recipes/AGENTS.md
│ ├── core/ # kernel, bootloader, relibc, base drivers — See recipes/core/AGENTS.md
│ ├── wip/ # Wayland, KDE, driver WIP ports — See recipes/wip/AGENTS.md
│ ├── libs/ # Libraries: mesa, cairo, SDL, zlib, openssl, etc.
│ ├── gui/ # Orbital, orbterm, orbutils
│ ├── gui/ # Legacy GUI stack packages
│ └── ... # 21 other categories (net, dev, games, shells, etc.)
├── src/ # Cookbook Rust tooling (repo binary, cook logic)
├── docs/ # Architecture docs (6 detailed integration guides) — See docs/AGENTS.md
@@ -43,7 +43,7 @@ redox-master/
│ ├── patches/ # Patches against mainline sources (kernel, relibc, base)
│ ├── Assets/ # Branding assets (icon, loading background)
│ ├── firmware/ # AMD GPU firmware blobs (fetched, not committed)
│ ├── scripts/ # Build/deploy scripts (fetch-firmware.sh, build-amd.sh)
│ ├── scripts/ # Build/deploy scripts (fetch-firmware.sh, build-redbear.sh)
│ └── docs/ # Red Bear integration docs (AMD roadmap, Wi-Fi/Bluetooth plans, status notes)
├── prefix/ # Cross-compiler toolchain (Clang/LLVM for x86_64-unknown-redox)
├── build/ # Build outputs, logs, fstools, per-arch directories
@@ -73,7 +73,7 @@ redox-master/
| Linux driver compat | `docs/04-LINUX-DRIVER-COMPAT.md` | linux-kpi + redox-driver-sys architecture (**GPU and Wi-Fi only — not USB**) |
| Build system internals | `src/bin/repo.rs`, `src/lib.rs`, `mk/repo.mk` | Cookbook tool in Rust |
| Cross-toolchain setup | `mk/prefix.mk`, `prefix/x86_64-unknown-redox/` | Downloads Clang/LLVM toolchain |
| Display server | Orbital: `recipes/gui/orbital/` | Userspace scheme-based display server |
| Display/session surface | `config/redbear-kde.toml`, `config/wayland.toml` | Tracked KWin desktop target plus bounded validation slice |
| GPU/graphics stack | `recipes/libs/mesa/` | OSMesa + LLVMpipe (software only) |
| GPU hardware drivers | `local/recipes/gpu/redox-drm/source/` | AMD + Intel DRM/KMS via redox-driver-sys |
| D-Bus integration | `local/docs/DBUS-INTEGRATION-PLAN.md` | Architecture, gap analysis, phased implementation for KDE Plasma D-Bus |
@@ -92,8 +92,8 @@ echo 'PODMAN_BUILD?=0' > .config # Native build (no container)
echo 'PODMAN_BUILD?=1' > .config # Podman container build
# Build Red Bear OS
make all # Build desktop config → harddrive.img
make all CONFIG_NAME=redbear-full # Full Red Bear OS desktop + custom drivers
make all # Build tracked KWin Wayland target → harddrive.img
make all CONFIG_NAME=redbear-full # Broader Red Bear integration slice + custom drivers
make all CONFIG_NAME=redbear-minimal # Minimal Red Bear OS server
CI=1 make all CONFIG_NAME=redbear-minimal # CI mode (disables TUI, for non-interactive)
@@ -250,7 +250,7 @@ See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path p
|-----------|--------|--------|
| UEFI boot | ✅ | x86_64 bootloader functional |
| AMD CPUs | ✅ | Ryzen Threadripper 128-thread verified |
| ACPI | ✅ Complete | RSDP/SDT checksums, MADT types 0x4/0x5/0x9/0xA, LVT NMI, FADT shutdown/reboot |
| ACPI | ✅ Boot-baseline complete | RSDP/SDT checksums, MADT types 0x4/0x5/0x9/0xA, LVT NMI, FADT shutdown/reboot; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` for remaining ownership/robustness work |
| ACPI shutdown | ✅ | PM1a/PM1b S5 via `\_S5` AML |
| ACPI reboot | ✅ | Reset register + keyboard controller fallback |
| ACPI power | ✅ | `\_PS0`/`\_PS3`/`\_PPC` AML methods available |
@@ -266,7 +266,7 @@ See `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop path p
| Phase | Duration | Delivers |
|-------|----------|----------|
| ~~P0: Fix ACPI for AMD~~ | ~~4-6 weeks~~ | ✅ Complete — boots on modern AMD bare metal |
| ~~P0: Fix ACPI for AMD~~ | ~~4-6 weeks~~ | ✅ Materially complete — boots on modern AMD bare metal; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` for forward work |
| ~~P1: Driver infrastructure~~ | ~~8-12 weeks~~ | ✅ Complete — redox-driver-sys + linux-kpi + firmware-loader + pcid /config + MSI-X (compiles) |
| ~~P2: AMD GPU display~~ | ~~12-16 weeks~~ | ✅ Complete — redox-drm + AMD DC port + Intel driver (compiles, no HW validation) |
| ~~P3: POSIX + input~~ | ~~4-8 weeks~~ | 🚧 Build-side work substantially complete — relibc gaps exported to downstream consumers, evdevd/udev-shim/libevdev/libinput/D-Bus build; runtime validation still open |
+2 -3
View File
@@ -165,7 +165,6 @@ You can contribute to the Red Bear OS documentation and code on the following re
- [Website](https://gitlab.redox-os.org/redox-os/website)
- [Book](https://gitlab.redox-os.org/redox-os/book) - High-level documentation
- [Build System Configuration](https://gitlab.redox-os.org/redox-os/redox) - Our main repository
- [Orbital](https://gitlab.redox-os.org/redox-os/orbital) - Display Server and Window Manager
- [pkgutils](https://gitlab.redox-os.org/redox-os/pkgutils) - Package Manager
- [acid](https://gitlab.redox-os.org/redox-os/acid) - Redox Test Suite
- [relibc](https://gitlab.redox-os.org/redox-os/relibc) - Redox C Library
@@ -219,8 +218,8 @@ If you know how to code in Rust, and have experience with systems software/OS de
For those who want to contribute to the Redox GUI, our GUI strategy has changed.
- We are improving the [Orbital](https://gitlab.redox-os.org/redox-os/orbital) display server and window manager, you can read more about it on [this tracking issue](https://gitlab.redox-os.org/redox-os/redox/-/issues/1430).
- OrbTk is in maintenance mode, and its developers have moved to other projects such as the ones below. There is currently no Redox-specific GUI development underway.
- We are concentrating current forward desktop work on the KWin Wayland path in the main build-system repository.
- Legacy GUI toolkit efforts are in maintenance mode, and there is currently no separate Redox-specific GUI toolkit effort underway.
## Priorities
+24 -22
View File
@@ -44,7 +44,7 @@ We also recommend to add your `pciutils` log as a comment on [this](https://gitl
## Status
- **Recommended:** The operating system boots with video, sound, PS/2 or USB input, Ethernet, terminal and Orbital working.
- **Recommended:** The operating system boots with video, sound, PS/2 or USB input, Ethernet, terminal, and the graphical session working.
- **Booting:** The operating system boots with some issues or lacking hardware support (write the issues and what supported hardware is not working in the "Report" section).
- **Broken:** The boot loader don't work or can't bootstrap the operating system.
@@ -52,8 +52,10 @@ We also recommend to add your `pciutils` log as a comment on [this](https://gitl
This section contain limitations that apply to any status.
- ACPI bring-up is materially complete for the current boot baseline, but broader platform coverage
and hardware validation are still uneven across machines
- ACPI bring-up is **materially complete for boot baseline**; implemented: RSDP/RSDT/XSDT/MADT/FADT
with typed startup errors, AML mutexes with real tracked state, EC widened accesses via byte
transactions, kstop-based shutdown eventing; sleep state transitions are a **known gap**; broader
platform validation remains uneven — see `local/docs/ACPI-IMPROVEMENT-PLAN.md`
- Wi-Fi broad support is not available yet; bounded Intel Wi-Fi scaffolding and validation paths now
cover probe/status/prepare/init/activate plus bounded scan/connect/disconnect/retry surfaces, but
validated real wireless connectivity support remains incomplete
@@ -100,30 +102,32 @@ Each "Vendor" has its own alphabetical order in "Model", independent from models
| **Vendor** | **Model** | **Red Bear OS Version** | **Image Date** | **Variant** | **CPU Architecture** | **Motherboard Firmware** | **Report** |
|------------|-----------|-------------------|----------------|-------------|----------------------|--------------------------|------------|
| Lenovo | IdeaPad Y510P | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS, UEFI | Boots to Orbital |
| System76 | Galago Pro (galp5) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to Orbital |
| System76 | Lemur Pro (lemp9) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to Orbital |
| Lenovo | IdeaPad Y510P | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS, UEFI | Boots to graphical session |
| System76 | Galago Pro (galp5) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to graphical session |
| System76 | Lemur Pro (lemp9) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to graphical session |
## Booting
| **Vendor** | **Model** | **Red Bear OS Version** | **Image Date** | **Variant** | **CPU Architecture** | **Motherboard Firmware** | **Report** |
|------------|-----------|-------------------|----------------|-------------|----------------------|--------------------------|------------|
| ASUS | Eee PC 900 | 0.8.0 | 2022-11-11 | desktop | i686 | BIOS | Boots to Orbital, No ethernet driver, Correct video mode not offered (firmware issue) |
| ASUS | Eee PC 900 | 0.8.0 | 2022-11-11 | desktop | i686 | BIOS | Boots to graphical session, No ethernet driver, Correct video mode not offered (firmware issue) |
| ASUS | PRIME B350M-E (custom) | 0.9.0 | 2024-09-20 | desktop | x86-64 | UEFI | Partial support for the PS/2 keyboard, PS/2 mouse is broken |
| ASUS | ROG g55vw | 0.8.0 | 2023-11-11 | desktop | x86-64 | BIOS | Boots to Orbital, UEFI panic in SETUP |
| ASUS | X554L | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS | Boots to Orbital, No audio, HDA driver cannot find output pins |
| ASUS | Vivobook 15 OLED (M1503Q) | 0.9.0 | 2025-08-04 | desktop | x86-64 | UEFI | Boots to Orbital, touchpad and usb do not work, cannot connect to the internet, right maximum display resolution 2880x1620 |
| Dell | XPS 13 (9350) | 0.8.0 | 2022-11-11 | desktop | i686 | BIOS | Boots to Orbital, NVMe driver livelocks |
| Dell | XPS 13 (9350) | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS, UEFI | Boots to Orbital, NVMe driver livelocks |
| HP | Dev One | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to Orbital, No touchpad support, requires I2C HID |
| HP | EliteBook Folio 9480M | 0.9.0 | 2025-11-04 | desktop | x86-64 | UEFI | Boots to Orbital, touchpad and usb work, cannot connect to the Internet, install failed, right maximum display resolution 1600x900
| Lenovo | ThinkPad Yoga 260 Laptop - Type 20FE | 0.9.0 | 2024-09-07 | demo | x86-64 | UEFI | Boots to Orbital, No audio |
| Lenovo | Yoga S730-13IWL | 0.9.0 | 2024-11-09 | desktop | x86-64 | UEFI | Boots to Orbital, No trackpad or USB mouse input support |
| ASUS | ROG g55vw | 0.8.0 | 2023-11-11 | desktop | x86-64 | BIOS | Boots to graphical session, UEFI panic in SETUP |
| ASUS | X554L | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS | Boots to graphical session, No audio, HDA driver cannot find output pins |
| ASUS | Vivobook 15 OLED (M1503Q) | 0.9.0 | 2025-08-04 | desktop | x86-64 | UEFI | Boots to graphical session, touchpad and usb do not work, cannot connect to the internet, right maximum display resolution 2880x1620 |
| Dell | XPS 13 (9350) | 0.8.0 | 2022-11-11 | desktop | i686 | BIOS | Boots to graphical session, NVMe driver livelocks |
| Dell | XPS 13 (9350) | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS, UEFI | Boots to graphical session, NVMe driver livelocks |
| Framework | Laptop 16 (AMD Ryzen 7040 Series) | 0.9.0 | 2026-3-29 | desktop, demo | x86-64 | UEFI | ACPI fix applied (RSDP/SDT checksums, MADT NMI types, FADT parse); **hardware validation still needed**; moved from Broken table |
| HP | Dev One | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to graphical session, No touchpad support, requires I2C HID |
| HP | EliteBook Folio 9480M | 0.9.0 | 2025-11-04 | desktop | x86-64 | UEFI | Boots to graphical session, touchpad and usb work, cannot connect to the Internet, install failed, right maximum display resolution 1600x900
| HP | Compaq nc6120 | 0.9.0 | 2024-11-08 | desktop, server | i686 | BIOS | xAPIC fix applied; **hardware validation still needed**; moved from Broken table |
| Lenovo | ThinkPad Yoga 260 Laptop - Type 20FE | 0.9.0 | 2024-09-07 | demo | x86-64 | UEFI | Boots to graphical session, No audio |
| Lenovo | Yoga S730-13IWL | 0.9.0 | 2024-11-09 | desktop | x86-64 | UEFI | Boots to graphical session, No trackpad or USB mouse input support |
| Raspberry Pi | 3 Model B+ | 0.8.0 | Unknown | server | ARM64 | U-Boot | Boots to UART serial console (pl011) |
| Samsung | Series 3 (NP350V5C) | 0.9.0 | 2025-08-04 | desktop | x86-64 | UEFI | Boots to Orbital, touchpad works, USB does not work, can connect to the Internet through LAN. Wrong maximum display resolution 1024x768 |
| System76 | Oryx Pro (oryp10) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to Orbital, No touchpad support, though it should be working |
| System76 | Pangolin (pang12) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to Orbital, No touchpad support, requires I2C HID |
| Toshiba | Satellite L500 | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS | Boots to Orbital, No Ethernet driver, Correct video mode not offered (firmware issue) |
| Samsung | Series 3 (NP350V5C) | 0.9.0 | 2025-08-04 | desktop | x86-64 | UEFI | Boots to graphical session, touchpad works, USB does not work, can connect to the Internet through LAN. Wrong maximum display resolution 1024x768 |
| System76 | Oryx Pro (oryp10) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to graphical session, No touchpad support, though it should be working |
| System76 | Pangolin (pang12) | 0.8.0 | 2022-11-11 | desktop | x86-64 | UEFI | Boots to graphical session, No touchpad support, requires I2C HID |
| Toshiba | Satellite L500 | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS | Boots to graphical session, No Ethernet driver, Correct video mode not offered (firmware issue) |
## Broken
@@ -131,8 +135,6 @@ Each "Vendor" has its own alphabetical order in "Model", independent from models
|------------|-----------|-------------------|----------------|-------------|----------------------|--------------------------|------------|
| ASUS | PN41 | 0.8.0 | 2024-05-30 | server | x86-64 | Unknown | Aborts after panic in xhcid |
| BEELINK | U59 | 0.8.0 | 2024-05-30 | server | x86-64 | Unknown | Aborts after panic in xhcid |
| Framework | Laptop 16 (AMD Ryzen 7040 Series) | 0.9.0 | 2026-3-29 | desktop, demo | x86-64 | UEFI | Crash due to unimplemented acpi function, see [jackpot51/acpi #3](https://github.com/jackpot51/acpi/pull/3) on GitHub |
| HP | Compaq nc6120 | 0.9.0 | 2024-11-08 | desktop, server | i686 | BIOS | Unloads into memory at a rate slower than 1MB/s after selecting resolution. When unloading is complete the logger initializes and crashes after kernel::acpi, some information about APIC is printed. Boot logs do not progress after this point. |
| HP | EliteBook 2570p | 0.8.0 | 2022-11-23 | demo | x86-64 | BIOS (CSM mode?) | Gets to resolution selection, Fails assert in `src/os/bios/mod.rs:77` after selecting resolution |
| Lenovo | G570 | 0.8.0 | 2022-11-11 | desktop | x86-64 | BIOS | Bootloader panics in `alloc_zeroed_page_aligned`, Correct video mode not offered (firmware issue) |
| Lenovo | IdeaPad Y510P | 0.8.0 | 2022-11-11 | desktop | i686 | BIOS | Panics on `phys_to_virt overflow`, probably having invalid mappings for 32-bit |
+17 -10
View File
@@ -41,6 +41,7 @@ predictably from the Red Bear-owned overlay.
## What's New
- KWin Wayland is now treated as the only intended Red Bear desktop direction in the tracked plans, build defaults, live profile wiring, and profile guidance.
- KDE bring-up moved forward: `config/redbear-kde.toml` exists, the Qt6 stack builds in-tree, and the KDE recipe tree is now populated.
- Native Red Bear runtime tooling expanded with `redbear-info`, `redbear-hwutils` (`lspci`, `lsusb`), and a Redox-native `netctl` flow.
- Build and status docs were refreshed to distinguish current in-tree progress from older historical roadmap text.
@@ -69,6 +70,9 @@ Red Bear OS now treats AMD and Intel machines as equal-priority hardware targets
language in historical integration notes should be read as earlier sequencing context, not as the
current platform policy.
The tracked default desktop target is now `redbear-kde` with KWin Wayland, and runtime support
claims remain evidence-qualified until compositor/session proof is stronger.
## Historical Phase Snapshot
The table below is a legacy P0-P6 snapshot retained for historical continuity with older Red Bear
@@ -82,12 +86,12 @@ with the subsystem plans listed above.
| Phase | Status | Notes |
|---|---|---|
| P0 ACPI boot | ✅ Complete | In-tree and documented in `local/docs/ACPI-FIXES.md` |
| P0 ACPI boot | ✅ Materially complete (boot bring-up) | In-tree and documented in `local/docs/ACPI-FIXES.md`; forward ownership/robustness work lives in `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| P1 driver infra | ✅ Complete | Compile-oriented infrastructure present |
| P2 DRM / display | ✅ Code complete | Hardware validation still pending |
| P3 POSIX + input | 🚧 In progress | relibc exports now cover the rebuilt `signalfd`/`timerfd`/`eventfd`/`open_memstream` consumer path; runtime validation remains |
| P4 Wayland runtime | 🚧 In progress | `redbear-wayland` is now a first-class profile, builds to a bootable image, and reaches the `orbital-wayland``smallvil` runtime path in QEMU/UEFI |
| P5 desktop/network plumbing | 🚧 In progress | `redbear-full` now carries the native VirtIO networking path plus D-Bus system-bus plumbing, and the guest-side runtime check reaches `DBUS_SYSTEM_BUS=present` |
| P4 Wayland runtime | 🚧 In progress | bounded Wayland runtime validation builds to a bootable image and reaches its packaged runtime entrypoint in QEMU/UEFI |
| P5 desktop/network plumbing | 🚧 In progress | `redbear-full` now carries the native VirtIO networking path plus D-Bus system-bus plumbing as a broader integration slice, and the guest-side runtime check reaches `DBUS_SYSTEM_BUS=present` |
| P6 KDE Plasma | 🚧 In progress | Mix of real builds, shims, and stubs |
There is no distinct first-class **P7** artifact in this older historical numbering. The canonical
@@ -123,10 +127,10 @@ expand on top of them.
| Component | Status | Detail |
|-----------|--------|--------|
| AMD GPU driver (amdgpu) | ✅ Compiles | LinuxKPI compat + AMD DC modesetting + MSI-X (no HW validation) |
| Intel GPU driver | ✅ Compiles | Display pipe modesetting + MSI-X (no HW validation) |
| AMD GPU driver (amdgpu) | ✅ Compiles | LinuxKPI compat + AMD DC modesetting + quirk-aware MSI-X/MSI/legacy IRQ fallback (no HW validation) |
| Intel GPU driver | ✅ Compiles | Display pipe modesetting + quirk-aware MSI-X/MSI/legacy IRQ fallback (no HW validation) |
| ext4 filesystem | ✅ Compiles | Read/write ext4 alongside RedoxFS |
| ACPI for AMD bare metal | ✅ Complete | x2APIC, MADT, FADT shutdown/reboot, power methods |
| ACPI for AMD bare metal | ✅ Materially complete (boot bring-up) | x2APIC, MADT, FADT shutdown/reboot, power methods; see `local/docs/ACPI-IMPROVEMENT-PLAN.md` for remaining ownership, robustness, and validation work |
| Wired networking | 🚧 Improved | native net stack present, Redox-native `netctl` shipped, RTL8125 autoload wired through the existing Realtek path |
| Custom branding | ✅ | Boot identity, hostname, os-release |
| POSIX gaps (relibc) | 🚧 In progress | implementations exist in-tree; runtime validation against Wayland stack is still ongoing |
@@ -154,12 +158,15 @@ expand on top of them.
Requires a Linux x86_64 host with Rust nightly, QEMU, and standard build tools. See the [Redox Build Instructions](https://doc.redox-os.org/book/podman-build.html) for full prerequisites.
```bash
make all CONFIG_NAME=redbear-full # Full desktop + custom drivers
make all # Default tracked KWin Wayland desktop target
make all CONFIG_NAME=redbear-kde # Explicit KWin Wayland desktop target
make all CONFIG_NAME=redbear-full # Broader integration slice + custom drivers
make all CONFIG_NAME=redbear-minimal # Minimal server
make all CONFIG_NAME=redbear-full-grub # Full desktop with GRUB boot manager
make all CONFIG_NAME=redbear-full-grub # Broader integration slice with GRUB boot manager
make live CONFIG_NAME=redbear-live # Live install ISO (redbear-live.iso)
make live CONFIG_NAME=redbear-live-mini # Tiny boot-test live ISO (~256 MiB image)
make qemu # Boot in QEMU
make qemu # Boot the default tracked KWin Wayland desktop target in QEMU
make qemu CONFIG_NAME=redbear-kde # Explicit KWin Wayland desktop target in QEMU
```
### GRUB Boot Manager (optional)
@@ -167,7 +174,7 @@ make qemu # Boot in QEMU
Red Bear OS can use GNU GRUB as an alternative boot manager with Linux-compatible CLI:
```bash
make all CONFIG_NAME=redbear-full-grub # Build with GRUB chainload
make all CONFIG_NAME=redbear-full-grub # Build broader integration slice with GRUB chainload
./local/scripts/grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img
./local/scripts/grub-mkconfig -o local/recipes/core/grub/grub.cfg
```