diff --git a/README.md b/README.md index 76b993880..87583762c 100644 --- a/README.md +++ b/README.md @@ -1,267 +1,129 @@

-Red Bear OS + Red Bear OS

Red Bear OS

-Microkernel operating system in Rust — based on Redox OS + A microkernel operating system written in Rust, derived from Redox OS

-MIT License -Microkernel -Rust + MIT + x86_64 + Status

--- -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 ` 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= --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