From 5be1ec17b30e9bdc84641fc7380c1e3f8687472d Mon Sep 17 00:00:00 2001 From: vasilito Date: Sat, 4 Jul 2026 09:18:22 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20rewrite=20README=20for=20public=20audie?= =?UTF-8?q?nce=20=E2=80=94=20highlight=20cub,=20tlc,=20redbear-*=20utiliti?= =?UTF-8?q?es,=20current=20status,=20call=20for=20contributors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 214 ++++++++++++++++++++++++++++++------------- local/sources/relibc | 2 +- 2 files changed, 152 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 73452f2a65..d3d5ad1475 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Red Bear OS

- A microkernel operating system written in Rust, derived from Redox OS + A microkernel operating system written in Rust — derived from Redox OS, built for bare metal.

@@ -18,40 +18,60 @@ ## What is Red Bear OS? -Red Bear OS is a general-purpose, Unix-like operating system with a **microkernel architecture**, written in **Rust**. It is a full fork of Redox OS, frozen at release 0.1.0, with added hardware support, filesystem drivers, and a KDE Plasma desktop path. +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.1.0), actively developed +on branch `0.2.5` with hardware enablement, multiple filesystems, a native greeter and login +system, and a KDE Plasma desktop path. + +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, 986 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** — first-class support for both platforms on bare metal +- **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 GPU (amdgpu) and Intel GPU drivers via `redox-drm` -- **Modern subsystems** — USB, Wi‑Fi, Bluetooth, ext4, GRUB, D-Bus -- **Offline-first builds** — reproducible from archived, BLAKE3-verified sources +- **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 for the fork — there is no GitHub / GitLab / Codeberg -mirror that is authoritative. +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` | -| Token | *(session-only — never stored in repo)* | | Web UI | `https://gitea.redbearos.org/vasilito` | | Main repo| `https://gitea.redbearos.org/vasilito/RedBear-OS` | -> **Token policy.** The `vasilito` token is a per-session credential and **must -> never** be committed to any tracked file. Use `git credential.helper` (store / -> cache / libsecret), `~/.netrc`, or `$REDBEAR_GITEA_TOKEN` env var. See -> [`local/AGENTS.md` § Our Git Server](./local/AGENTS.md) for the full operator -> runbook, mirror list, API reference, and recovery procedure. +> 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. +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 @@ -61,94 +81,162 @@ See the [Redox Build Guide](https://doc.redox-os.org/book/podman-build.html) for git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git cd RedBear-OS -# Authenticated clone (one-off) — supply token via env var, not literal here +# Authenticated clone — supply token via env var git clone https://vasilito:${REDBEAR_GITEA_TOKEN}@gitea.redbearos.org/vasilito/RedBear-OS.git -# Recommended: use the Red Bear wrapper +# 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 with the resulting image +# Boot in QEMU make qemu ``` -> **Build script:** `local/scripts/build-redbear.sh` is the canonical and only -> supported build entry point. It handles `.config` parsing, prefix staleness -> detection, `REDBEAR_ALLOW_PROTECTED_FETCH=1`, pre-cooking critical packages, -> and source fingerprint tracking. Direct `make` invocations bypass these gates -> and should not be used. See `AGENTS.md` § Build Commands for full details. - -### Public Scripts - -| Script | Purpose | -|--------|---------| -| `local/scripts/build-redbear.sh` | **Canonical** build wrapper for redbear-mini/full/grub | -| `scripts/network-boot.sh` | PXE network boot helper | -| `scripts/dual-boot.sh` | Dual-boot installation helper | +> `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 | Wayland + KDE + GPU drivers + D-Bus services | -| `redbear-mini` | Console | Text-only recovery / install target | +| `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 filesystem support (RedoxFS, ext4, FAT). +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.2.5`. 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 24.0.8). | Area | Status | |------|--------| -| Boot (ACPI/x2APIC/SMP) | ✅ Bare-metal proven | +| Boot (ACPI, x2APIC, SMP) | ✅ Bare-metal proven — Ryzen Threadripper 128-thread verified | | Userspace drivers (PCI, storage, net) | ✅ Working in QEMU | -| D-Bus system bus + services | ✅ Working (login1, PolicyKit, UDisks, UPower) | -| ext4 / FAT filesystems | ✅ Compiles, installer-wired | -| POSIX gaps (relibc) | 🚧 Bounded Wayland-facing support | -| DRM/KMS display drivers | 🚧 AMD + Intel compile; HW validation pending | -| Wayland compositor | 🚧 Bounded proof; Qt6/KF6 clients crash at init | -| KDE Plasma desktop | 🔄 In progress (Qt6/KF6 compile; KWin/QML blocked) | -| Wi‑Fi / Bluetooth | 📋 Planned (architected, implementation pending) | +| 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; 986 tests; 8 skins; VFS archives | +| IRQ / PCI / MSI-X / IOMMU | 🟡 QEMU-proven; hardware validation open | +| POSIX gaps (relibc) | 🟡 ~85% coverage; ~38 active patches | +| 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 | +| 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 | +| KDE Plasma / KWin | 🔴 Blocked by Qt6 Wayland crash in `wl_proxy_add_listener` | +| Wi‑Fi (Intel iwlwifi) | 🟡 VFIO/passthrough bounded runtime validation framework exists | +| USB / Bluetooth | 🔴 USB maturity work in progress; 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: +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 - └── Driver daemons (userspace) - ├── pcid → PCI enumeration - ├── e1000d → Intel ethernet - ├── xhcid → USB controller - └── vesad → Display framebuffer +┌─────────────────────────────────────────────────────────────────┐ +│ 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, IPC). Everything else — filesystems, networking, graphics, input — runs in userspace. +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/` branches. | +| **Local fork model** | Core components (kernel, relibc, base, etc.) maintained as local forks in `local/sources/` with immutability guarantees. | +| **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 -- [Implementation Plan](docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) — roadmap and execution model -- [Desktop Path Plan](local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — kernel → DRM → Mesa → Wayland → KDE -- [D-Bus Integration](local/docs/DBUS-INTEGRATION-PLAN.md) — session bus architecture -- [USB Plan](local/docs/USB-IMPLEMENTATION-PLAN.md) — USB stack design -- [Wi‑Fi Plan](local/docs/WIFI-IMPLEMENTATION-PLAN.md) — wireless architecture -- [Bluetooth Plan](local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md) — BT stack design -- [Documentation Index](docs/README.md) — full doc map +- [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 +- [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 +- [Quirks System](local/docs/QUIRKS-SYSTEM.md) — Hardware quirks infrastructure +- [Documentation Index](docs/README.md) — Full doc map + +--- ## Contributing -Red Bear OS uses a **full fork** model. Upstream Redox sources are frozen and archived. All custom work lives in `local/`: +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 -├── recipes/ # Custom packages (drivers, GPU, system) -├── docs/ # Integration and planning docs -└── scripts/ # Build, test, and release tooling +├── docs/ # Integration and planning documentation +└── scripts/ # Build, test, validation, and release tooling ``` -We welcome contributions made with or without AI assistance — we care about **quality**, not how the code was produced. +### 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 diff --git a/local/sources/relibc b/local/sources/relibc index 89a4aa8a05..68ed35f243 160000 --- a/local/sources/relibc +++ b/local/sources/relibc @@ -1 +1 @@ -Subproject commit 89a4aa8a05c073b7a24762a7959c0a3f99d4f223 +Subproject commit 68ed35f2437787f5af4ffce73ab041a88f65827b