RedBear-OS/docs/01-REDOX-ARCHITECTURE.md

01 — Redox OS Architecture Overview

Status note (2026-04-15): This file is primarily an architecture reference, not the canonical current-state status document for Red Bear OS. Use docs/07-RED-BEAR-OS-IMPLEMENTATION-PLAN.md and the current subsystem plans under local/docs/ for project execution order and current implementation truth.

1. Microkernel Design

Redox is a pure microkernel written in Rust (~20-40k LoC). Only essential services live in kernel space:

• Process and thread management
• Memory management (address spaces, page tables, grants)
• IPC via schemes (packet-based, io_uring-like SQE/CQE format)
• Context switching and scheduling
• Minimal kernel schemes: debug, event, memory, pipe, irq, time, sys, proc, serio

Everything else — drivers, filesystems, display server, networking — runs in userspace as separate processes with isolated address spaces. Crashes are contained; no kernel panics from driver bugs.

Syscall Interface

The syscall ABI is intentionally unstable. Stability is provided by libredox and relibc. On x86_64, syscalls use int 0x80 with registers:

eax = syscall number
ebx, ecx, edx, esi, edi = arguments
eax = return value

Key syscalls: open, close, read, write, seek, fmap, funmap, dup, fork, execve, clone, mmap, munmap, mprotect, setrens, yield.

Userspace-ification Trend

Redox is actively moving POSIX functionality out of the kernel:

• fork/exec → userspace via thisproc: scheme
• Signal handling → userspace with kernel-shared page for low-cost sigprocmask
• Process manager → planned userspace daemon

This reduces TCB and allows faster iteration without kernel changes.

2. The Scheme System — Everything is a URL

Inspired by Plan 9. Every resource is accessed through a scheme — a named service providing file-like operations (open, read, write, fmap).

How Schemes Work

User program:  open("/scheme/orbital:myapp/800/600/Title")
    ↓
Kernel:        Routes to "orbital" scheme daemon
    ↓
Orbital:       Creates window, returns file handle
    ↓
User program:  write(fd, pixel_data)  // renders to window

Kernel Schemes

Scheme	Purpose
debug	Debug output
event	epoll-like event notification
irq	Interrupt → message conversion
pipe	Pipe implementation
memory	Physical memory mapping
time / itimer	Timers
proc / thisproc	Process context
sys	System information
serio	PS/2 driver (kernel-space due to protocol constraints)

Userspace Schemes (Daemons)

Category	Schemes	Daemon
Storage	disk.*	ided, ahcid, nvmed
Filesystem	file	redoxfs
Network	ip, tcp, udp, icmp	smolnetd
Display	display.vesa, display.virtio-gpu, orbital	vesad, virtio-gpud, orbital
IPC	chan, shm, uds_stream, uds_dgram	ipcd
Audio	audio	audiorw
Input	input	inputd
USB	usb.*	usbhidd
Misc	rand, null, zero, log, pty, sudo	various

Scheme Registration

A daemon registers a scheme by:

1. File::create(":myscheme") — creates root scheme
2. Opens needed resources (/scheme/irq/{irq}, /scheme/event)
3. setrens(0, 0) — moves to null namespace (security sandbox)
4. Registers FDs with event scheme for async I/O
5. Loops: block on event → handle request → respond

Namespace Isolation

• Root namespace: all processes start here
• Null namespace: process can only use existing FDs, cannot open new resources
• Namespaces inherited by children
• Enables sandboxing and privilege separation

3. Driver Model

All drivers are userspace daemons that access hardware through:

• iopl syscall — sets I/O privilege level for port I/O
• /scheme/memory/physical — maps physical memory (writeback, uncacheable, write-combining)
• /scheme/irq — converts hardware interrupts to messages

Current Drivers

Storage: ided (IDE), ahcid (SATA), nvmed (NVMe), usbscsid (USB SCSI)

Network: e1000d (Intel GigE), rtl8168d (Realtek 8168/8169/8125 path), ixgbed (Intel 10G), virtio-netd (VirtIO)

The native wired stack in this tree is userspace end to end: pcid-spawner autoloads NIC daemons, drivers expose network.* schemes through driver-network, smolnetd provides the ip/tcp/ udp/icmp/netcfg schemes, and dhcpd plus config files under /etc/net/ supply runtime addressing. Red Bear additionally ships a small native netctl compatibility command for profile- driven wired setup.

Audio: ac97d, ihdad (Intel HD Audio), sb16d (Sound Blaster)

Display: vesad (VESA framebuffer), virtio-gpud (VirtIO 2D)

Other: pcid (PCI enumeration), acpid (ACPI), usbhidd (USB HID), inputd (input multiplexor)

GPU Driver Status

• Broad hardware-validated GPU acceleration is not yet available as a general support claim.
• BIOS VESA and UEFI GOP framebuffers remain the default proven display path.
• Experimental Intel modesetting exists.
• Red Bear also carries compile/integration-oriented AMD and Intel DRM work in its local overlay, but that should not be read as broad hardware-validated acceleration support yet.

4. Orbital Display Server

Orbital is Redox's display server, window manager, and compositor — all in one userspace daemon.

Window Creation (via Scheme)

// Open a window through the orbital scheme
let window = File::create("orbital:myapp/800/600/My Title")?;

// Read input events
let mut event = [0u8; 32];
window.read(&mut event)?;

// Write pixel data (RGBA)
window.write(&pixel_data)?;
window.sync_all()?;

Supported Toolkits

• SDL1.2, SDL2 — games and emulators
• winit — Rust GUI abstraction (has Orbital backend)
• softbuffer — software rendering
• Iced, egui, Slint — via winit/softbuffer

Graphics Stack

Application
    ↓ (SDL2 / winit / liborbital)
Orbital (display server + compositor)
    ↓ (scheme: display.vesa or display.virtio-gpu)
vesad / virtio-gpud (display driver daemon)
    ↓ (scheme: memory + irq)
Hardware (framebuffer / VirtIO GPU)

Rendering is software-only via LLVMpipe (Mesa CPU OpenGL emulation). No GPU acceleration pipeline exists yet.

5. relibc — C Library

relibc is a POSIX-compatible C library written in Rust. Provides:

• Standard C library functions
• POSIX syscalls (section 2 + 3)
• Linux/BSD extensions

Targets: Redox (via redox-rt), Linux (direct syscalls). Architectures: i586, x86_64, aarch64, riscv64gc.

Known POSIX Gaps (blocking Wayland)

These were the specific missing features originally identified from libwayland's redox.patch. Today, most exist in-tree in relibc, but downstream Wayland consumers still carry compatibility patches, so this table is a current-state summary rather than an untouched historical claim.

Missing API	Used By	Status
signalfd / SFD_CLOEXEC	libwayland event loop	Implemented in-tree; downstream libwayland still patched around usage
timerfd / TFD_CLOEXEC / TFD_TIMER_ABSTIME	libwayland timers	Implemented in-tree; downstream libwayland still patched around usage
eventfd / EFD_CLOEXEC	libwayland server	Implemented in-tree; downstream libwayland still patched around usage
F_DUPFD_CLOEXEC	libwayland fd management	Implemented in-tree
MSG_CMSG_CLOEXEC	libwayland socket recv	Implemented in-tree
MSG_NOSIGNAL	libwayland connection	Implemented in-tree; downstream libwayland still omits flag
open_memstream	libdrm, libwayland	Implemented in-tree; downstream libwayland still bypasses usage

6. Build System (This Repository)

This repository is the build system — it orchestrates fetching, building, and packaging components from ~100+ Git repositories into a bootable Redox image.

Key Directories

Directory	Purpose
config/	Build configurations (desktop, server, wayland, x11, minimal)
recipes/	Package recipes (source + build instructions)
recipes/core/	Essential: kernel, bootloader, relibc, init
recipes/gui/	Orbital, orbterm, orbutils
recipes/libs/	Libraries: mesa, cairo, pango, SDL, etc.
recipes/wip/	Work-in-progress packages (wayland/, kde/, gnome/, etc.)
mk/	Makefile infrastructure
src/	Build system source (cookbook tool in Rust)

Config System

Configs are TOML files that include each other:

wayland.toml → desktop.toml → desktop-minimal.toml → minimal.toml → base.toml

Each config selects packages and overrides init scripts. For example, wayland.toml overrides the orbital init to launch cosmic-comp instead of orblogin.

Build Flow

make all
  → downloads cross-toolchain (Clang/LLVM for x86_64-unknown-redox)
  → fetches recipe sources (git/tar)
  → applies patches (redox.patch files)
  → builds each recipe (cargo, meson, cmake, make, custom)
  → stages into sysroot
  → creates RedoxFS image
  → produces harddrive.img / redox-live.iso

7. Existing Wayland/X11 Support

X11 (Working)

Config: config/x11.toml

• X.org with dummy video driver inside Orbital
• GTK3, MATE desktop, Mesa EGL
• DRI3 enabled
• Software rendering only

Wayland (Experimental, WIP)

Config: config/wayland.toml

• 21 Wayland recipes in recipes/wip/wayland/
• cosmic-comp: partially working, performance issues, no keyboard input
• smallvil (Smithay): ported, basic compositor running
• wlroots: not compiled or tested
• sway: not compiled or tested
• hyprland: not compiled or tested
• niri: needs Smithay port
• xwayland: partially patched, needs wayland-client fixes

Key Blockers for Wayland

1. Downstream Wayland compatibility patches remain (libwayland/redox.patch still bypasses some interfaces even though relibc-side APIs now exist in-tree)
2. No GPU acceleration (only software rendering)
3. Input/runtime integration remains incomplete (evdevd, udev-shim, and libinput exist, but compositor input is not fully validated)
4. DRM/KMS runtime validation remains incomplete (redox-drm exists in-tree, but full Wayland/driver runtime integration is still open)
5. cosmic-comp: keyboard/input integration and performance issues remain