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

docs: polish public README with project goals, status, and quick-start guide

Browse Source
This commit is contained in:
Vasilito
2026-05-06 08:12:21 +01:00
parent 2ca82fab28
commit 1cdb6d4d99
1 changed files with 88 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -226
View File
@@ -1,267 +1,129 @@
<p align="center">
<img alt="Red Bear OS" width="200" src="assets/redbear-icon.png">
<img alt="Red Bear OS" width="200" src="assets/redbear-icon.png">
</p>
<h1 align="center">Red Bear OS</h1>
<p align="center">
<strong>Microkernel operating system in Rust — based on <a href="https://www.redox-os.org">Redox OS</a></strong>
<strong>A microkernel operating system written in Rust, derived from <a href="https://www.redox-os.org">Redox OS</a></strong>
</p>
<p align="center">
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
<img src="https://img.shields.io/badge/architecture-microkernel-orange.svg" alt="Microkernel">
<img src="https://img.shields.io/badge/language-Rust-000000.svg" alt="Rust">
<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>
---
Red Bear OS is a derivative of [Redox OS](https://www.redox-os.org) — a general-purpose, Unix-like, microkernel-based operating system written in Rust. It is a full fork based on frozen Redox snapshots, adding custom drivers, filesystems, and hardware support.
## What is Red Bear OS?
RedBearOS is a **full fork** of Redox OS — based on frozen, archived source snapshots at release 0.1.0.
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.
- Redox is upstream
- Red Bear carries integration, packaging, validation, and subsystem release fork on top
- upstream-owned source trees are immutable archived release snapshot
- durable Red Bear state belongs in `local/patches/`, `local/recipes/`, `local/docs/`, and tracked
Red Bear configs
**Goals**:
- **AMD & Intel parity** — first-class support for both platforms on bare metal
- **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
Operational resilience policy:
## Quick Start
- package/source usage is local-first by default,
- local copies are used continuously for builds and recovery workflows,
- upstream package immutable archived is performed only when explicitly requested.
### Prerequisites
For **upstream WIP recipes specifically**, Red Bear uses a stricter rule:
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.
1. once an upstream recipe or subsystem is still marked WIP, Red Bear treats it as a local project
2. we copy, fix, validate, and ship that work from our local release fork until it is stable enough for us
3. we continue updating our local copy from upstream WIP work when useful, but we do not rely on the
upstream WIP recipe itself as our shipped source of truth
4. once upstream removes the WIP status and the recipe/subsystem becomes a first-class supported
part of Redox, Red Bear reevaluates and should prefer the upstream version over the local copy
That policy exists so the project can pull immutable archived upstream sources regularly and still rebuild
predictably from the Red Bear-owned release fork.
## 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: the `redbear-full` desktop-capable surface carries the Qt6/KDE stack 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 immutable archived to distinguish current in-tree progress from older historical roadmap text.
See [CHANGELOG.md](./CHANGELOG.md) for the running user-visible change log.
The current public roadmap and execution model live in the
[Red Bear OS Implementation Plan](./docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md).
For readers landing on GitHub, the most useful entry points are:
- [Documentation Index](./docs/README.md) — canonical map of current vs historical docs
- [Console to KDE Desktop Plan](./local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md) — **canonical comprehensive implementation plan**: kernel→DRM→Mesa→Wayland→KDE, all blockers, honest assessment
- [Kernel IPC Credential Plan](./local/docs/KERNEL-IPC-CREDENTIAL-PLAN.md) — kernel credential syscalls, IPC, RLIMIT (Phases K1-K2,K4 complete)
- [relibc IPC Assessment and Improvement Plan](./local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md) — IPC-focused companion plan for bounded relibc compatibility layers
- [Script Behavior Matrix](./local/docs/SCRIPT-BEHAVIOR-MATRIX.md) — what the main sync/fetch/apply/build scripts do and do not guarantee
Current subsystem-specific plans also include:
- [USB Implementation Plan](./local/docs/USB-IMPLEMENTATION-PLAN.md)
- [Wi-Fi Implementation Plan](./local/docs/WIFI-IMPLEMENTATION-PLAN.md)
- [Bluetooth Implementation Plan](./local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md)
- [IRQ and Low-Level Controllers Enhancement Plan](./local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md) — canonical plan for PCI interrupt plumbing, IRQ delivery quality, MSI/MSI-X follow-up, and low-level controller runtime proof
Red Bear OS now treats AMD and Intel machines as equal-priority hardware targets. Older AMD-first
language in historical integration notes should be read as earlier sequencing context, not as the
current platform policy.
The tracked desktop-capable target surface is `redbear-full`, 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
status notes.
It is **not** the canonical execution-order source for current subsystem planning. For the current
repo-wide order of implementation — including low-level controllers, USB, Wi‑Fi, and Bluetooth as
first-class subsystem workstreams — use
[docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md](./docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md) together
with the subsystem plans listed above.
| Phase | Status | Notes |
|---|---|---|
| P0 ACPI boot | ✅ Materially complete (historical boot baseline) | In-tree; remaining work tracked in `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| P1 driver infra | ✅ Complete (compile-oriented) | shared driver infrastructure is present, but low-level PCI/IRQ robustness and runtime proof remain governed by `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` |
| P2 DRM / display | 🚧 Partial | redox-drm + bounded AMD display glue build; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); hardware validation still pending |
| P3 POSIX + input | 🚧 In progress | relibc now has strict Redox-target runtime proof for `signalfd` / `timerfd` / `eventfd` through the repaired test runner; broader desktop/runtime hardening still continues |
| 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, blocked by QML gates, and stubs |
There is no distinct first-class **P7** artifact in this older historical numbering. The canonical
current execution plan uses the newer phased/workstream ordering documented in `docs/07`.
## First-class subsystem order and blockers
The current subsystem order is not arbitrary.
- **Low-level controllers / IRQ quality** are first-class because they block reliable driver/runtime validation.
- **USB** is first-class because Bluetooth and wider device support depend on controller and hotplug maturity.
- **Wi-Fi** is first-class because Red Bear still lacks any native wireless driver/control plane.
- **Bluetooth** is first-class because broad support is still incomplete, depends on USB maturity or
another controller path, and currently exists only as one bounded BLE-first experimental slice
rather than broad desktop parity.
The current blocker chain is:
`low-level controllers -> USB -> Bluetooth`
and, separately:
`low-level controllers -> Wi-Fi driver bring-up -> native wireless control plane -> desktop compatibility later`
These subsystems are all intended to be implemented in full, but they must be executed in this order
to avoid building desktop-facing layers on top of missing runtime substrate.
The current total order is: low-level controllers first, then USB, then Wi-Fi, then Bluetooth, and
only after those runtime services are credible should heavier desktop/session compatibility layers
expand on top of them.
For PCI, IRQ, MSI/MSI-X, and IOMMU quality specifically, the canonical current plan is
`local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`.
Current validation language should be read this way:
- compile-visible infrastructure is not the same as runtime proof,
- bounded QEMU/runtime proof is not the same as hardware validation,
- and PCI/IRQ robustness claims should stay evidence-qualified until broader hardware proof exists.
## What's Different from Upstream Redox
| Component | Status | Detail |
|-----------|--------|--------|
| AMD GPU driver (amdgpu) | 🚧 Bounded path builds | redox-drm + Red Bear AMD display glue compile; imported Linux AMD DC/TTM/core remain builds and included in redbear-full (2026-04-29); quirk-aware MSI-X/MSI/legacy IRQ fallback present (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 boot baseline | ✅ Materially complete (historical boot baseline) | x2APIC, MADT, FADT shutdown/reboot, explicit `RSDP_ADDR` forwarding into `acpid`, x86 BIOS-search AML fallback, power methods, and bounded AML-backed power enumeration exist; the explicit AML bootstrap producer contract, shutdown robustness, sleep-state scope, and validation depth still remain open — see `local/docs/ACPI-IMPROVEMENT-PLAN.md` |
| 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 | the active relibc recipe patch chain provides bounded Wayland-facing and IPC-facing compatibility layers, but broad runtime trust and several completeness gaps remain open |
## Project Structure
```
├── config/ # Build configs (TOML) — desktop, minimal, redbear-*
├── recipes/ # Package recipes (~100+ packages, 26 categories)
├── mk/ # Makefile build orchestration
├── src/ # Cookbook Rust tool (repo binary, cook logic)
├── local/ # ← Red Bear OS custom work (survives source provisioning)
│ ├── patches/ # Kernel, base, relibc patches
│ ├── recipes/ # Custom packages (drivers, GPU, system, branding)
│ ├── scripts/ # provision-release.sh, check-upstream-releases.sh
│ ├── Assets/ # Branding (icon, boot background)
│ └── docs/ # Integration documentation
├── docs/ # Architecture guides
├── scripts/ # Helper scripts
└── Makefile # Root build orchestrator
```
## Build
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.
### Build & Run
```bash
# Non-live (harddrive.img for QEMU / development)
make all CONFIG_NAME=redbear-full # Desktop/graphics target
make all CONFIG_NAME=redbear-mini # Text-only console/recovery target
# Clone
git clone https://gitea.redbearos.org/vasilito/RedBear-OS.git
cd RedBear-OS
# Live ISO (for real bare metal)
make live CONFIG_NAME=redbear-full # Full desktop live ISO
make live CONFIG_NAME=redbear-mini # Text-only mini live ISO for recovery
make live CONFIG_NAME=redbear-grub # Text-only mini live ISO with GRUB
# Build and run the desktop target in QEMU
./scripts/run.sh --build
# Or use the helper script
scripts/build-iso.sh redbear-full # Full desktop live ISO
scripts/build-iso.sh redbear-mini # Text-only mini (default)
scripts/build-iso.sh redbear-grub # Text-only + GRUB
# Build a live ISO for bare metal
./scripts/build-iso.sh redbear-full
# QEMU (uses harddrive.img, not live ISO)
make qemu CONFIG_NAME=redbear-full # Boot the desktop target in QEMU
# Build the text-only recovery target
./scripts/run.sh --build --config redbear-mini
```
Live `.iso` outputs are for real bare-metal boot and install workflows. They are not the virtual/QEMU target surface; use `make qemu` and `harddrive.img`-based flows for virtualization.
### Public Scripts
### GRUB Boot Manager (optional)
| Script | Purpose |
|--------|---------|
| `scripts/run.sh` | Build and run in QEMU (`-b` to build, `-c <config>` for target) |
| `scripts/build-iso.sh` | Build a live ISO for bare-metal boot |
| `scripts/build-all-isos.sh` | Build all live ISO targets |
| `scripts/network-boot.sh` | PXE network boot helper |
| `scripts/dual-boot.sh` | Dual-boot installation helper |
Red Bear OS can use GNU GRUB as an alternative boot manager with Linux-compatible CLI:
### Config Targets
```bash
make all CONFIG_NAME=redbear-grub # Build text-only target 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
| Target | Type | Description |
|--------|------|-------------|
| `redbear-full` | Desktop | Wayland + KDE + GPU drivers + D-Bus services |
| `redbear-mini` | Console | Text-only recovery / install target |
| `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).
| Area | Status |
|------|--------|
| Boot (ACPI/x2APIC/SMP) | ✅ Bare-metal proven |
| 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) |
## How It Works
Red Bear OS uses a **userspace driver model** — all drivers run as unprivileged daemons:
```
Kernel (microkernel)
└── schemes: memory, irq, event, pipe, debug
└── Driver daemons (userspace)
├── pcid → PCI enumeration
├── e1000d → Intel ethernet
├── xhcid → USB controller
└── vesad → Display framebuffer
```
## Native hardware listing tools
The kernel provides minimal services (memory, interrupts, IPC). Everything else — filesystems, networking, graphics, input — runs in userspace.
Red Bear configs now include a small native `redbear-hwutils` package that ships `lspci` and
`lsusb`. `lspci` reads the existing `/scheme/pci/.../config` surface, while `lsusb` walks the
native `usb.*` schemes exposed by `xhcid`, so there is no dependency on the unfinished WIP
`pciutils` or `usbutils` ports.
## Documentation
## Networking
- [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
Red Bear ships the existing native Redox wired networking path (`pcid-spawner` → NIC daemon →
`smolnetd`/`dhcpd`/`netcfg`) together with a small Redox-native `netctl` compatibility command and
the `redbear-netctl-console` ncurses client for the bounded Wi‑Fi profile flow. Profiles live under
`/etc/netctl`, the shipped examples live under `/etc/netctl/examples`, live Wi‑Fi actions go
through `/scheme/wifictl`, and the boot service applies the enabled profile with `netctl --boot`.
## Contributing
RTL8125 is wired into the existing native Realtek autoload path by matching `10ec:8125` in the
`rtl8168d` driver config. This keeps the implementation in the Redox userspace driver model rather
than introducing a separate Linux netdevice compatibility layer.
Red Bear OS uses a **full fork** model. Upstream Redox sources are frozen and archived. All custom work lives in `local/`:
## Runtime diagnostics
Red Bear ships `redbear-info` as the canonical runtime integration/debugging command. It is a
passive report over live system surfaces and is intended to help answer questions like:
- which Red Bear integrations are merely installed versus actually active,
- whether the networking stack is up, with current IP, DNS, and default route,
- whether hardware discovery surfaces such as PCI, USB, DRM, and RTL8125 are visible.
Use `redbear-info --verbose` for evidence-backed human output, `redbear-info --json` for machine-
readable diagnostics, and `redbear-info --test` for suggested follow-up commands.
## Release Model (Full Fork)
Red Bear OS is a **full fork** based on frozen Redox OS snapshots. Sources are immutable and never auto-immutable archived from upstream. The current baseline is **0.1.0** (Redox snapshot at `f55acba68`). Build-dependent sources are archived in `sources/redbear-0.1.0/` (216 BLAKE3-verified archives).
Builds are offline by default — no network access during compilation.
```bash
# Build from archived sources (offline by default)
./local/scripts/build-redbear.sh redbear-full
# Check for newer Redox snapshots (read-only, zero side effects)
./local/scripts/check-upstream-releases.sh
# Provision a new release (explicit, human-initiated only)
./local/scripts/provision-release.sh --ref=<redox-tag> --release=0.2.0 --dry-run
```
local/
├── patches/ # Durable changes to upstream source trees
├── recipes/ # Custom packages (drivers, GPU, system)
├── docs/ # Integration and planning docs
└── scripts/ # Build, test, and release tooling
```
The `local/` directory is never touched by any source immutable archived. Recipe patches are symlinked from `local/patches/` — protected from `make clean` and `make distclean`.
## Resources
- [Upstream Redox website](https://www.redox-os.org)
- [Redox Book](https://doc.redox-os.org/book/)
- [Hardware Support](https://doc.redox-os.org/book/hardware-support.html)
- [Contributing](CONTRIBUTING.md)
## AI Policy
We welcome contributions made with the assistance of LLMs and AI tools. If you use AI to help write code, documentation, or patches, that's great — we care about the quality of the result, not how it was produced.
We welcome contributions made with or without AI assistance — we care about **quality**, not how the code was produced.
## License