vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6b915e004e892cdab7c78eef06814d88de3ec3eb
RedBear-OS/README.md
T
vasilito f09a094993 docs: 3D driver plan covering Mesa 26.1.4 + virgl + Intel (PTL) + AMD 
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'.
2026-07-25 00:25:12 +09:00

262 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<p align="center">
<img alt="Red Bear OS" width="200" src="assets/redbear-icon.png">
</p>
<h1 align="center">Red Bear OS</h1>
<p align="center">
<strong>A microkernel operating system written in Rust — derived from <a href="https://www.redox-os.org">Redox OS</a>, built for bare metal.</strong>
</p>
<p align="center">
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
<img src="https://img.shields.io/badge/arch-x86__64-red" alt="x86_64">
<img src="https://img.shields.io/badge/status-active%20development-orange" alt="Status">
</p>
---
## What is Red Bear OS?
Red Bear OS is a general-purpose, Unix-like operating system with a **microkernel architecture**,
written entirely in **Rust**. It is a full fork of Redox OS (baseline 0.3.1), actively developed
on branch `0.3.1` with hardware enablement, multiple filesystems, a native greeter and login
system, and a KDE Plasma desktop path.
We aim to stay close to upstream Redox — diverging only where necessary to add missing
functionality, fix bugs, or support new hardware. The build system itself is under constant
active development alongside the OS.
It ships with several **first-in-class Rust-native tools** found nowhere else in the OS world:
- **cub** — an AUR-inspired package manager with pacman-style CLI (`-S`/`-Q`/`-R`) and a ratatui
TUI that converts Arch Linux PKGBUILDs into Red Bear recipes on the fly
- **tlc** (Twilight Commander) — a pure-Rust reimplementation of Midnight Commander; dual-panel
file manager, built-in editor and viewer, 8 color themes, 1204 unit tests, zero unsafe code
- **redbear-power** — interactive ratatui TUI for live CPU frequency, governor, and thermal
monitoring with on-the-fly P-state control
These are joined by dozens of `redbear-*` system utilities — `redbear-netctl` (network control),
`redbear-info` (hardware diagnostics), `redbear-acmd` (admin CLI), `redbear-mtr`,
`redbear-nmap`, `redbear-btctl`, and many more — all written in Rust, all built from source
alongside the OS.
**Goals**:
- **AMD & Intel parity** — equal-priority bare-metal support for both platforms
- **KDE Plasma desktop** — Wayland-based desktop environment via the KWin compositor
- **Hardware GPU acceleration** — AMD (amdgpu) and Intel GPU drivers via `redox-drm`
- **cub package ecosystem** — AUR → recipe.toml pipeline giving access to thousands of packages
- **First-class subsystems** — USB, Wi‑Fi, Bluetooth, ext4, FAT, GRUB, D-Bus (none optional)
- **Power management** — CPU frequency scaling, thermal monitoring, RAPL, sleep states
- **Offline-first, reproducible builds** — BLAKE3-verified source archives with content-hash caching
---
## Our Git Server
Red Bear OS lives on a self-hosted Gitea instance at **https://gitea.redbearos.org**.
This is the canonical home — no GitHub, GitLab, or Codeberg mirror is authoritative.
There is exactly **one repository**: all component sources (kernel, relibc, drivers,
system utilities) live here as submodule branches or tracked trees in `local/sources/`.
| Field | Value |
|----------|------------------------------------------------------|
| Host | `https://gitea.redbearos.org` |
| User | `vasilito` |
| Web UI | `https://gitea.redbearos.org/vasilito` |
| Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` |
> Authentication tokens are per-session credentials — never stored in the repo.
> See [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator runbook.
---
## Quick Start
### Prerequisites
Linux x86_64 host with Rust nightly, QEMU, nasm, and standard build tools.
See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for full setup.
### Build & Run
```bash
# Clone (read-only)
git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git
cd RedBear-OS
# Authenticated clone — supply token via env var
git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git
# Canonical build entry point
./local/scripts/build-redbear.sh redbear-mini # Text-only target
./local/scripts/build-redbear.sh redbear-full # Desktop-capable target
# Boot in QEMU
make qemu
```
> `local/scripts/build-redbear.sh` is the **only supported build entry point**. It handles
> `.config` parsing, prefix staleness detection, protected-recipe authorization, pre-cooking
> critical packages, and source fingerprint tracking. Direct `make` invocations bypass these
> gates. See [`AGENTS.md` § Build Commands](./AGENTS.md) for details.
### Config Targets
| Target | Type | Description |
|--------|------|-------------|
| `redbear-full` | Desktop-capable | GPU drivers + Wayland compositor + Qt 6.11.1 + KF6 6.27.0 + KWin + SDDM + greeter + D-Bus |
| `redbear-mini` | Console | Text-only recovery / install target with tlc, cub, and redbear-* utilities |
| `redbear-grub` | Console | Text-only with GRUB boot manager |
---
## Current Status
Red Bear OS **boots to a login prompt** in QEMU with working wired networking, D-Bus system bus,
hardware detection daemons, and three filesystem backends (RedoxFS, ext4, FAT). The ISO builds
successfully on branch `0.3.1`. Graphics packages are frozen at latest upstream stable
(Qt 6.11.1, KF6 6.27.0, Plasma 6.7.2, SDDM 0.21.0, Mesa 26.1.4, wayland-protocols 1.49).
| Area | Status |
|------|--------|
| Boot (ACPI, x2APIC, SMP) | ✅ Bare-metal proven — Ryzen Threadripper 128-thread verified |
| Userspace drivers (PCI, storage, net) | ✅ Working in QEMU |
| Filesystems — RedoxFS, ext4, FAT | ✅ Scheme daemons + mkfs/fsck tools |
| D-Bus system bus + services | ✅ Working — login1, PolicyKit, UDisks, UPower |
| **cub** package manager | 🟡 17-module Rust workspace; AUR → recipe pipeline; 70+ tests |
| **tlc** file manager | 🟡 113 .rs files, 46k+ lines; 1497 tests; 8 skins; VFS archives; first-paint panic fixed (2026-07-24) |
| IRQ / PCI / MSI-X / IOMMU | 🟡 QEMU-proven; shared-IRQ re-arm bug class swept across 11 drivers (2026-07-20); hardware validation open |
| POSIX gaps (relibc) | 🟡 ~85% coverage; PATCHED-VIA-PATH-FORK — relibc changes are committed directly to `local/sources/relibc/`; `local/patches/relibc/` holds reference and archived patches only |
| DRM/KMS display drivers | 🟡 AMD + Intel + virtio-gpu compile; HW validation open |
| Mesa — llvmpipe + virgl | 🟡 Builds (`virtio_gpu_dri.so`, 17.4 MB); virgl EGL runtime probe open |
| 3D userland (iris / radeonsi / Vulkan) | 🔴 Not built | Mesa 26.1.4 builds only `softpipe,llvmpipe,virgl` (no `iris`, no `crocus`, no `radeonsi`); no `redox` EGL platform; no Vulkan; no Lunar Lake / Panther Lake device IDs | Comprehensive plan in `local/docs/3D-DRIVER-PLAN.md` (2026-07-24) |
| SDDM display manager + Greeter/Login | 🟡 Wired in `redbear-full`; graphical login blocked by Qt6 Wayland crash |
| Qt 6.11.1 (Core, Gui, DBus, Wayland) | 🟡 Builds successfully; Wayland `null+8` crash blocks runtime |
| KF6 Frameworks — 40/40 | 🟡 All frameworks build; KWin cooks successfully |
| Wayland compositor | 🟡 Bounded proof; blocked by Qt6 Wayland protocol crash |
| KWin | 🟡 Builds successfully (redox-drm + Qt6 Wayland); runtime blocked by Qt6 Wayland crash in `wl_proxy_add_listener` |
| KDE Plasma | 🔴 Runtime blocked by Qt6 Wayland null+8 crash — depends on KWin |
| Wi‑Fi (Intel iwlwifi) | 🟡 VFIO/passthrough bounded runtime validation framework exists |
| USB / Bluetooth | 🟡 xHCI mature in QEMU: 51-flag quirks, capability gating, 36-code error recovery, Linux hub enumeration state machine, hub + hub-child enumeration proven, storage BOT proven; USB 2.0 HW LPM (L1) attach path implemented; endpoint-indexing bug class fixed across acmd/ecmd/usbaudiod/usbhidd; UAS/HID-parser expansion in flight; Bluetooth controller path planned |
**Where help is most wanted:**
Qt6 Wayland protocol crash — the #1 blocker for graphical desktop · AMD/Intel GPU hardware validation on bare metal · USB controller maturity · Wi‑Fi native control plane · cub AUR pipeline hardening · package maintainers for the growing recipe catalog · tlc VFS remote backends and archive support
---
## How It Works
Red Bear OS uses a **userspace driver model** — all drivers run as unprivileged daemons
communicating through the kernel's scheme-based IPC.
```
┌─────────────────────────────────────────────────────────────────┐
│ KERNEL (microkernel) │
│ schemes: memory · irq · event · pipe · debug │
└──────────────────────────┬──────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ pcid │ │ e1000d xhcid │ │ vesad redox-drm │
│ PCI enum │ │ Intel USB 3.0 │ │ fbdev GPU manager │
└──────────┘ └──────────────────┘ └──────────────────────┘
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ ext4d │ │ ps2d evdevd │ │ thermald cpufreqd │
│ fatd │ │ KB+mouse input │ │ thermal CPU freq │
└──────────┘ └──────────────────┘ └──────────────────────┘
┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ iommu │ │ acpid │ │ dbus-daemon │
│ DMA map │ │ power mgmt │ │ system + session │
└──────────┘ └──────────────────┘ └──────────────────────┘
```
The kernel provides minimal services: memory, interrupts, and IPC. Everything else —
filesystems, networking, graphics, input, power management, D-Bus — runs in userspace.
Hardware quirks are handled by a data-driven system in `redox-driver-sys` with compiled-in
tables, TOML runtime configuration, and DMI matching.
---
## Engineering Standards
Red Bear OS operates under strict discipline. Full policies: [`local/AGENTS.md`](./local/AGENTS.md).
| Rule | |
|------|---|
| **Never delete to "fix" a build** | If a package breaks, fix the root cause. Never remove, ignore, or comment out a package, service, or config to make a build pass. |
| **Zero stubs** | No fake headers, `#ifdef` no-ops, or "make it compile" shortcuts. Missing functionality must be implemented properly in the right component. |
| **Single repository** | All component sources live here — no per-component repos. 9 `submodule/<component>` branches. |
| **Local fork model** | Core components (kernel, relibc, base, bootloader, installer, redoxfs, userutils) are maintained as local forks in `local/sources/` with immutability guarantees; `syscall` and `libredox` are wired as Cargo path dependencies via `redbear-rt` consumers, not via `recipes/<comp>/recipe.toml path =`. |
| **Adapt to upstream** | Red Bear adapts to upstream API/ABI changes — never pins, downgrades, or holds back a dependency. |
| **Free/libre only** | No proprietary, source-unavailable, or redistributability-restricted dependencies. MIT licensed. |
---
## Documentation
- [Desktop Path Plan](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — Canonical plan v6.0: kernel → DRM → Mesa → Wayland → KDE
- [Implementation Plan](docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) — Roadmap and execution model
- [cub Package Manager](local/docs/CUB-PACKAGE-MANAGER.md) — AUR → recipe pipeline, CLI reference, architecture
- [tlc File Manager](local/recipes/tui/tlc/README.md) — Pure-Rust Midnight Commander replacement
- [D-Bus Integration](local/docs/DBUS-INTEGRATION-PLAN.md) — Session bus architecture
- [IRQ & Low-Level Controllers](local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) — IRQ delivery, MSI/MSI-X, IOMMU
- [Greeter & Login](local/docs/GREETER-LOGIN-IMPLEMENTATION-PLAN.md) — Native greeter, auth daemon, session launch
- [DRM Modernization](local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md) — DRM/KMS display and render maturity
- [USB Plan](local/docs/USB-IMPLEMENTATION-PLAN.md) — USB stack design and implementation
- [Patch Preservation Audit](local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md) — orphan-patch governance, Rounds 1-6 audit results, SUPERSEDED.md log
- [Collision Detection Status](local/docs/COLLISION-DETECTION-STATUS.md) — runtime collision-detection current state
- [Hooks](local/docs/HOOKS.md) — opt-in git hooks (pre-push safety net, etc.)
- [Build Tools](local/scripts/TOOLS.md) — 15-tool reference (patch-status, sync, verify, collision, release-bump, etc.)
- [Fork Push Status](local/docs/fork-push-status/2026-07-12-Round-9-phase-8.3.md) — fork-branch push results + base deadlock (updated Round 9)
- [Wi‑Fi Plan](local/docs/WIFI-IMPLEMENTATION-PLAN.md) — Wireless architecture and driver plan
- [Bluetooth Plan](local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md) — Bluetooth stack design
- [Build Cache](local/docs/BUILD-CACHE-PLAN.md) — Content-hash (BLAKE3) build cache system
- [Build System Hardening](local/docs/BUILD-SYSTEM-HARDENING-PLAN.md) — Collision detection, init service validation
- [Build System Assessment](local/docs/BUILD-SYSTEM-ASSESSMENT-2026-07-18.md) — Architecture, quality, robustness, and gap assessment (2026-07-18)
- [Quirks System](local/docs/QUIRKS-SYSTEM.md) — Hardware quirks infrastructure
- [Documentation Index](docs/README.md) — Full doc map
---
## Contributing
Red Bear OS is a **full fork** of Redox OS. Upstream sources are frozen and archived; all
custom work lives in `local/` and survives every build operation.
```
local/
├── sources/ # Local forks of core components (kernel, relibc, base, bootloader, …)
├── recipes/ # Custom packages — drivers, GPU stack, system daemons, branding
├── patches/ # Durable changes to upstream source trees
│ └── (orphan-patch governance: every patch must correspond to work
│ present in the matching fork source tree. `verify-patch-content.sh`
│ enforces this on every build preflight. See
│ `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` for the audit
│ and AGENTS.md § "Orphan-Patch Supersession Decision Tree" for the
│ decision flow when an orphan is detected.)
├── docs/ # Integration and planning documentation
└── scripts/ # Build, test, validation, and release tooling
```
### We're Looking For
| Role | What you'd work on |
|------|--------------------|
| **Package maintainers** | Port and maintain AUR packages through cub's pipeline; write and test recipe.toml files for Red Bear OS; improve the PKGBUILD → recipe conversion |
| **Driver developers** | AMD/Intel GPU drivers, USB controller maturity, Wi‑Fi native control plane, Bluetooth |
| **Graphics stack engineers** | Qt6 Wayland crash fix (the #1 desktop blocker), Mesa virgl runtime, KWin Wayland compositor |
| **Systems/Rust engineers** | Kernel syscalls, relibc POSIX gaps, filesystem daemons, D-Bus services, hardware quirks |
| **TUI/app developers** | tlc feature completion, cub TUI polish, redbear-power enhancements, new redbear-* utilities |
Contributions are welcome with or without AI assistance — we care about **quality**, not how
the code was produced. Pick an area from the status table above, check the relevant plan doc,
and dive in.
---
## License
[MIT](./LICENSE) — same as upstream Redox OS.
Reference in New Issue View Git Blame Copy Permalink