docs: final stale doc cleanup — 22 archived, 18 active
Archived: IOMMU-SPEC, KERNEL-IPC, KERNEL-SCHEDULER, PROFILE-MATRIX, QUIRKS-IMPROVEMENT, RELIBC-IPC, repo-governance, SCHEDULER-REVIEW, SCRIPT-BEHAVIOR, USB-VALIDATION, XHCID-DEVICE-IMPROVEMENT. Active: all implementation plans + 3 audits + governance docs.
This commit is contained in:
@@ -0,0 +1,255 @@
|
||||
# Red Bear OS — Comprehensive Fix & Improvement Plan
|
||||
|
||||
**Date**: 2026-05-03
|
||||
**Scope**: All subsystems, boot to desktop
|
||||
**Previous audits**: `BOOT-PROCESS-AUDIT-2026-05-03.md`, `BOOT-PROCESS-SECOND-AUDIT-2026-05-03.md`
|
||||
|
||||
---
|
||||
|
||||
## 0. Current State
|
||||
|
||||
```
|
||||
Build: 12/12 patches → base ✅ → base-initfs ✅
|
||||
Boot: UEFI → kernel → init → services → getty/login → ion shell
|
||||
Targets: redbear-mini (console), redbear-full (desktop), redbear-grub (GRUB boot)
|
||||
Hardware: x86_64 only. QEMU-tested. Bare metal untested.
|
||||
```
|
||||
|
||||
### Completed (this session)
|
||||
|
||||
| Phase | Item | Status |
|
||||
|-------|------|--------|
|
||||
| A1 | ACPI shutdown hardening (PM1a validation, timeout, PM1b retry, keyboard reset) | ✅ |
|
||||
| A2 | Persistent logging (/var/log/system.log, 5MB rotation) | ✅ |
|
||||
| B1 | DRM service file in initfs | ✅ |
|
||||
| B2 | USB mass storage service file in initfs | ✅ |
|
||||
| D | Documentation cleanup (9 stale docs archived) | ✅ |
|
||||
| — | Build system atomicity (staging + rollback, normalize_patch, workspace cleanup) | ✅ |
|
||||
| — | Input stack hardening (usbhidd validation, keymapd XKB bridge, init colored output) | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 1. Priority Matrix
|
||||
|
||||
| Priority | Definition |
|
||||
|----------|-----------|
|
||||
| **P0 — Blocking** | System cannot reach login prompt or crashes during boot |
|
||||
| **P1 — Critical** | Core functionality missing; blocks desktop path or basic usability |
|
||||
| **P2 — High** | Significant UX/security gap; required for production readiness |
|
||||
| **P3 — Medium** | Quality-of-life improvement; can be deferred |
|
||||
| **P4 — Low** | Nice-to-have; deferred indefinitely |
|
||||
|
||||
---
|
||||
|
||||
## 2. P0 — Blocking Issues
|
||||
|
||||
**None currently.** The system reaches a login prompt reliably on redbear-mini. Redbear-full builds but has not been boot-tested this session.
|
||||
|
||||
| # | Issue | Fix | Effort |
|
||||
|---|-------|-----|--------|
|
||||
| P0-1 | **Boot redbear-full in QEMU** and verify it reaches login/desktop | Run `make qemu CONFIG_NAME=redbear-full`, collect logs, fix any boot failures | 2h |
|
||||
| P0-2 | **Verify 12-patch chain on clean checkout** | `make distclean && make all CONFIG_NAME=redbear-mini` | 1h |
|
||||
|
||||
---
|
||||
|
||||
## 3. P1 — Critical Gaps
|
||||
|
||||
### P1-1: D-Bus Runtime Validation
|
||||
**Impact**: KWin/Plasma cannot start without working D-Bus. All D-Bus code is "build-verified" only.
|
||||
**Files**: `local/recipes/system/redbear-sessiond/source/`, `config/redbear-full.toml`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Boot redbear-full in QEMU | 30min |
|
||||
| 2 | Verify `dbus-daemon` starts (`ps | grep dbus`) | 15min |
|
||||
| 3 | Verify `redbear-sessiond` starts and registers on bus | 15min |
|
||||
| 4 | Test `dbus-send --system --dest=org.freedesktop.login1 ... ListSessions` | 30min |
|
||||
| 5 | Test `ListSeats`, `GetUser`, `CreateSession` | 1h |
|
||||
| 6 | Test `PowerOff` (now backed by hardened ACPI shutdown) | 30min |
|
||||
| 7 | Fix any startup/runtime failures found | 4h |
|
||||
|
||||
**Acceptance**: `dbus-send` to login1 returns valid session/seat/user data. `PowerOff` triggers ACPI shutdown sequence.
|
||||
|
||||
### P1-2: ion Shell — Job Control
|
||||
**Impact**: Cannot background processes, cannot Ctrl-Z suspend. Every Unix user expects this.
|
||||
**Files**: `recipes/core/ion/source/src/`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Implement signal handling for SIGTSTP/SIGCONT in ion_shell | 1d |
|
||||
| 2 | Add background job table (track PIDs, job numbers) | 1d |
|
||||
| 3 | Implement `fg`, `bg`, `jobs` builtins | 4h |
|
||||
| 4 | Implement `&` operator for backgrounding at command line | 2h |
|
||||
| 5 | Wire Ctrl-Z to send SIGTSTP to foreground process group | 2h |
|
||||
|
||||
**Acceptance**: `sleep 60 &`, `jobs`, `fg %1`, `Ctrl-Z` → `bg` works. `ps` shows proper process states.
|
||||
|
||||
### P1-3: ion Shell — Tab Completion
|
||||
**Impact**: Must type every path and command fully. Painful on any filesystem.
|
||||
**Files**: `recipes/core/ion/source/src/`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Add `liner::Completer` trait implementation to ion | 4h |
|
||||
| 2 | Implement command completion (scan $PATH) | 2h |
|
||||
| 3 | Implement file path completion | 2h |
|
||||
| 4 | Implement partial match + common prefix completion | 1h |
|
||||
|
||||
**Acceptance**: Tab completes commands from $PATH. Tab completes file paths. Double-tab shows options.
|
||||
|
||||
### P1-4: DRM/KMS in Boot Path
|
||||
**Impact**: Only VESA framebuffer available at boot. No GPU acceleration.
|
||||
**Files**: `recipes/core/base-initfs/recipe.toml`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Add `redox-drm` to base-initfs BINS array | 15min |
|
||||
| 2 | Verify service file exists (added in Phase B1) | ✅ done |
|
||||
| 3 | Build and boot redbear-full | 1h |
|
||||
| 4 | Verify framebuffer switches from VESA to DRM at boot | 1h |
|
||||
| 5 | Fix any GPU-specific issues (AMD DC or Intel display) | 4h |
|
||||
|
||||
**Acceptance**: `lspci` shows GPU. `/scheme/drm/card0` exists. Framebuffer output works via redox-drm.
|
||||
|
||||
---
|
||||
|
||||
## 4. P2 — High Priority
|
||||
|
||||
### P2-1: Login /etc/shadow Support
|
||||
**Impact**: Passwords stored in /etc/passwd (not hashed separately). Security gap.
|
||||
**Files**: `recipes/core/userutils/source/src/bin/login.rs`, `redox_users` crate
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Read /etc/shadow for password hash (fall back to /etc/passwd) | 2h |
|
||||
| 2 | Verify SHA-crypt hash verification works (sha-crypt crate already in use) | 1h |
|
||||
| 3 | Update passwd command to write to /etc/shadow | 1h |
|
||||
|
||||
**Acceptance**: Password in /etc/shadow, not /etc/passwd. Login verifies against shadow.
|
||||
|
||||
### P2-2: Login Rate Limiting
|
||||
**Impact**: Unlimited brute-force attempts.
|
||||
**Files**: `recipes/core/userutils/source/src/bin/login.rs`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Track consecutive failures per TTY | 30min |
|
||||
| 2 | Sleep 5 seconds after 3 failures | 15min |
|
||||
| 3 | Log failures to syslog | 15min |
|
||||
|
||||
**Acceptance**: 3 wrong passwords → 5-second delay. Delay doubles for each subsequent failure.
|
||||
|
||||
### P2-3: Network in Initfs
|
||||
**Impact**: No network during early boot. DHCP/networking only available after switch_root.
|
||||
**Files**: `recipes/core/base/source/init.initfs.d/`, `recipes/core/base-initfs/recipe.toml`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Add `e1000d`, `rtl8168d` to base-initfs BINS | 15min |
|
||||
| 2 | Create `60_smolnetd.service` for initfs | 15min |
|
||||
| 3 | Create `61_dhcpd.service` for initfs | 15min |
|
||||
| 4 | Verify netctl boot profile loading works in initfs | 1h |
|
||||
|
||||
**Acceptance**: Network available before switch_root. `ifconfig` shows IP. `ping` works.
|
||||
|
||||
### P2-4: D-Bus Polkit Enforcement
|
||||
**Impact**: redbear-polkit is a facade — no actual privilege checks. KAuth expects real polkit.
|
||||
**Files**: `local/recipes/system/redbear-polkit/source/`
|
||||
|
||||
| Step | Action | Effort |
|
||||
|------|--------|--------|
|
||||
| 1 | Implement `CheckAuthorization` method with actual policy lookup | 3h |
|
||||
| 2 | Define default policies (allow root, ask for user password for admin actions) | 2h |
|
||||
| 3 | Test with KAuth-dependent KDE actions | 2h |
|
||||
|
||||
**Acceptance**: `pkcheck --action-id org.freedesktop.login1.power-off` returns auth result.
|
||||
|
||||
---
|
||||
|
||||
## 5. P3 — Medium Priority
|
||||
|
||||
### P3-1: ion Shell — History Search (Ctrl-R)
|
||||
**Effort**: 1d. Implement incremental reverse search using `liner` library.
|
||||
|
||||
### P3-2: ion Shell — Aliases
|
||||
**Effort**: 2h. Add `alias` builtin, resolve aliases before command lookup.
|
||||
|
||||
### P3-3: fbcond Scrollback Buffer
|
||||
**Effort**: 4h. Add 1000-line ring buffer to framebuffer console. PgUp/PgDn to scroll.
|
||||
|
||||
### P3-4: ACPI Sleep States (S3/S4)
|
||||
**Effort**: 2d. Implement `_S3`/`_S4` AML method invocation. Save/restore device state.
|
||||
|
||||
### P3-5: Thermal Daemon
|
||||
**Effort**: 2d. Read CPU temperature via ACPI thermal zone. Log warnings. Throttle on overheat.
|
||||
|
||||
### P3-6: Battery Status
|
||||
**Effort**: 1d. Read ACPI battery info. Expose via D-Bus org.freedesktop.UPower.
|
||||
|
||||
---
|
||||
|
||||
## 6. P4 — Deferred
|
||||
|
||||
| Item | Reason |
|
||||
|------|--------|
|
||||
| WiFi driver enablement | Requires iwlwifi kernel module port (LinuxKPI), firmware loading |
|
||||
| Bluetooth stack | Requires USB maturity, BlueZ port or native stack |
|
||||
| Secure boot chain | Requires TPM support, measured boot |
|
||||
| Filesystem encryption | Requires LUKS-like block layer |
|
||||
| ZSH port | ion is default; zsh is optional |
|
||||
| RTC write support | Low priority — NTP can adjust kernel clock without hardware RTC write |
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Order
|
||||
|
||||
```
|
||||
Week 1: P0-1 (boot redbear-full) → P0-2 (clean build verify)
|
||||
P1-4 (DRM in boot path)
|
||||
P1-1 (D-Bus runtime validation) — parallel with P1-4
|
||||
|
||||
Week 2: P1-2 (ion job control) → P1-3 (ion tab completion)
|
||||
P2-1 (shadow support) → P2-2 (rate limiting)
|
||||
|
||||
Week 3: P2-3 (network in initfs)
|
||||
P3-1 (ion history search) → P3-2 (ion aliases)
|
||||
|
||||
Week 4: P2-4 (polkit enforcement)
|
||||
P3-3 (fbcond scrollback)
|
||||
|
||||
Week 5-6: P3-4 (sleep states)
|
||||
P3-5 (thermal daemon)
|
||||
P3-6 (battery status)
|
||||
```
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
```
|
||||
Week 1: [P0-1/P0-2] || [P1-1] || [P1-4]
|
||||
Week 2: [P1-2 → P1-3] || [P2-1 → P2-2]
|
||||
Week 3: [P2-3] || [P3-1 → P3-2]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Acceptance Gates
|
||||
|
||||
| Gate | Requirement |
|
||||
|------|-------------|
|
||||
| G1 — Console Boot | redbear-mini reaches login prompt. All 12 patches apply. base + base-initfs build. |
|
||||
| G2 — Desktop Boot | redbear-full reaches login prompt or greeter. D-Bus daemon + sessiond start. |
|
||||
| G3 — Shell Usability | ion supports job control, tab completion, history search, aliases. |
|
||||
| G4 — Security Baseline | Passwords in /etc/shadow. Rate limiting active. Polkit enforces authorization. |
|
||||
| G5 — Hardware Coverage | DRM/KMS active at boot. Network available in initfs. USB storage in initfs. |
|
||||
|
||||
---
|
||||
|
||||
## 9. Total Effort Estimate
|
||||
|
||||
| Priority | Items | Effort |
|
||||
|----------|-------|--------|
|
||||
| P0 | 2 items | 3h |
|
||||
| P1 | 4 items | ~40h (5 days) |
|
||||
| P2 | 4 items | ~20h (2.5 days) |
|
||||
| P3 | 6 items | ~40h (5 days) |
|
||||
| **Total** | **16 items** | **~103h (~13 days with 1 dev, ~1 week with 2 devs)** |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,748 @@
|
||||
# Red Bear OS — Kernel, IPC, and Credential Syscalls Plan
|
||||
|
||||
**Date:** 2026-04-30
|
||||
**Scope:** Kernel architecture, IPC infrastructure, credential syscalls, process isolation
|
||||
**Implementation status:** Phases K1-K2, K4 ✅ complete. Phases K3, K5 deferred.
|
||||
**Status:** This document is the canonical kernel + IPC plan, extending `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This plan defines the implementation roadmap for kernel hardening, IPC improvements, and credential
|
||||
syscall implementation in Red Bear OS. It is the **canonical kernel authority** superseding scattered
|
||||
kernel guidance in other docs.
|
||||
|
||||
**Relationship to existing plans:**
|
||||
|
||||
| Document | Relationship |
|
||||
|----------|-------------|
|
||||
| `CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Parent: CONSOLE-TO-KDE v4.0 (Kernel & Core Infrastructure) |
|
||||
| `IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` | Sibling: IRQ/PCI/MSI-X — not duplicated here |
|
||||
| `RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` | Companion: relibc IPC surface — this plan covers kernel side |
|
||||
| `ACPI-IMPROVEMENT-PLAN.md` | Sibling: ACPI power/shutdown — relevant for §4 (shutdown robustness) |
|
||||
| `CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Consumer: desktop stack depends on kernel work here |
|
||||
|
||||
## 2. Current Architecture Assessment
|
||||
|
||||
### 2.1 Kernel Overview
|
||||
|
||||
The Redox microkernel (`recipes/core/kernel/source/`) is a ~20-40k LoC Rust microkernel. It runs in
|
||||
ring 0 and provides:
|
||||
|
||||
- **12 kernel schemes**: `debug`, `event`, `memory`, `pipe`, `irq`, `time`, `sys`, `proc`, `serio`,
|
||||
`acpi`, `dtb`, `user` (userspace scheme wrapper)
|
||||
- **~35 handled syscalls**: file I/O, memory mapping, process control, futex, time
|
||||
- **Catch-all ENOSYS**: all unhandled syscall numbers return `ENOSYS`
|
||||
|
||||
```
|
||||
recipes/core/kernel/source/src/
|
||||
├── syscall/ # Syscall dispatch: mod.rs (handlers), fs.rs, process.rs, futex.rs, time.rs
|
||||
│ └── mod.rs # Main syscall() dispatch: 35 explicit match arms, _ => ENOSYS
|
||||
├── scheme/ # Kernel schemes: debug, event, memory, pipe, irq, time, sys, proc, serio
|
||||
│ ├── mod.rs # Scheme trait definition, SchemeId, FileHandle types
|
||||
│ ├── proc.rs # Process manager scheme (fork, exec, signal, credential setting)
|
||||
│ └── sys/ # System info scheme: context list, syscall debug, uname
|
||||
├── context/ # Process/thread context management
|
||||
│ ├── context.rs # Context struct: euid, egid, pid, files, signals, addr_space
|
||||
│ └── memory.rs # Address space, grants, mmap implementation
|
||||
├── memory/ # Physical/virtual memory management, page tables
|
||||
└── sync/ # Locking primitives (RwLock, Mutex, CleanLockToken)
|
||||
```
|
||||
|
||||
### 2.2 Syscall Dispatch Architecture
|
||||
|
||||
The kernel's `syscall()` function in `syscall/mod.rs` dispatches based on `a` (syscall number):
|
||||
|
||||
```rust
|
||||
// From recipes/core/kernel/source/src/syscall/mod.rs (line 75)
|
||||
match a {
|
||||
SYS_WRITE2 => file_op_generic_ext(..),
|
||||
SYS_WRITE => sys_write(..),
|
||||
SYS_FMAP => { .. }, // Anonymous or file-backed mmap
|
||||
SYS_READ2 => file_op_generic_ext(..),
|
||||
SYS_READ => sys_read(..),
|
||||
SYS_FPATH => file_op_generic(..),
|
||||
SYS_FSTAT => fstat(..),
|
||||
SYS_DUP => dup(..),
|
||||
SYS_DUP2 => dup2(..),
|
||||
SYS_SENDFD => sendfd(..),
|
||||
SYS_OPENAT => openat(..),
|
||||
SYS_UNLINKAT => unlinkat(..),
|
||||
SYS_CLOSE => close(..),
|
||||
SYS_CALL => call(..), // Scheme IPC: send message to scheme
|
||||
SYS_FEVENT => fevent(..), // Register event on fd
|
||||
SYS_YIELD => sched_yield(..),
|
||||
SYS_NANOSLEEP => nanosleep(..),
|
||||
SYS_CLOCK_GETTIME => clock_gettime(..),
|
||||
SYS_FUTEX => futex(..),
|
||||
SYS_MPROTECT => mprotect(..),
|
||||
SYS_MREMAP => mremap(..),
|
||||
// ... ~15 more file operations (fchmod, fchown, fcntl, flink, frename, ftruncate, fsync, etc.)
|
||||
_ => Err(Error::new(ENOSYS)), // ← CATCH-ALL: all credential syscalls fall here
|
||||
}
|
||||
```
|
||||
|
||||
Syscall numbers come from the external `redox_syscall` crate (crates.io), not from the kernel tree.
|
||||
The kernel consumes them via `use syscall::number::*`.
|
||||
|
||||
### 2.3 Credential Architecture (Current)
|
||||
|
||||
**Kernel Context struct** (`context/context.rs`):
|
||||
|
||||
```rust
|
||||
pub struct Context {
|
||||
// Credential fields (initialized to 0):
|
||||
pub euid: u32, // Effective user ID — used for scheme access control
|
||||
pub egid: u32, // Effective group ID
|
||||
pub pid: usize, // Process ID (set via proc scheme)
|
||||
|
||||
// NOT present in kernel:
|
||||
// ruid, suid — real/saved UID (maintained in userspace redox-rt)
|
||||
// rgid, sgid — real/saved GID (maintained in userspace redox-rt)
|
||||
// supplementary groups — not implemented anywhere
|
||||
|
||||
// Access control interface:
|
||||
pub fn caller_ctx(&self) -> CallerCtx {
|
||||
CallerCtx { uid: self.euid, gid: self.egid, pid: self.pid }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Credential read path** (userspace, no kernel involvement):
|
||||
```
|
||||
getuid() → relibc::platform::redox::getuid()
|
||||
→ redox_rt::sys::posix_getresugid()
|
||||
→ reads local DYNAMIC_PROC_INFO { ruid, euid, suid, rgid, egid, sgid }
|
||||
→ returns cached userspace values (NO kernel syscall)
|
||||
```
|
||||
|
||||
**Credential write path** (through `proc:` scheme):
|
||||
```
|
||||
setresuid(ruid, euid, suid) → relibc::platform::redox::setresuid()
|
||||
→ redox_rt::sys::posix_setresugid(&Resugid { ruid, euid, suid, .. })
|
||||
→ packs 6×u32 into buffer
|
||||
→ this_proc_call(&buf, CallFlags::empty(), &[ProcCall::SetResugid as u64])
|
||||
→ SYS_CALL to proc: scheme
|
||||
→ kernel proc scheme handler (scheme/proc.rs:1269):
|
||||
guard.euid = info.euid;
|
||||
guard.egid = info.egid;
|
||||
```
|
||||
|
||||
**Key finding**: The kernel DOES support credential setting through the `proc:` scheme, using
|
||||
`ProcSchemeAttrs` with `euid`/`egid`/`pid`/`prio`/`debug_name` fields. The `getuid()`/`getgid()`
|
||||
functions work through userspace-cached values in `redox-rt`. `setresuid()`/`setresgid()` work
|
||||
through the proc scheme.
|
||||
|
||||
**What's genuinely broken:**
|
||||
|
||||
| Function | Status | Root Cause |
|
||||
|----------|--------|------------|
|
||||
| `setgroups()` | **ENOSYS stub** | relibc/redox/mod.rs:1205 — `todo_skip!(0, "setgroups({}, {:p}): not implemented")` |
|
||||
| `getgroups()` | /etc/group-based | Works via `getpwuid()` + `getgrent()` iteration — doesn't use kernel groups |
|
||||
| `initgroups()` | No-op | No supplementary group infrastructure |
|
||||
|
||||
### 2.4 IPC Architecture
|
||||
|
||||
**Scheme-based IPC** is the primary IPC mechanism:
|
||||
|
||||
```
|
||||
┌─────────────┐ SYS_CALL(syscall) ┌──────────────┐
|
||||
│ Userspace │ ──────────────────────────→│ Kernel │
|
||||
│ Process A │ open/read/write/fevent │ Scheme │
|
||||
│ │ ←──────────────────────────│ Dispatch │
|
||||
└─────────────┘ result (usize/-errno) └──────┬───────┘
|
||||
│
|
||||
┌─────────────────────┤
|
||||
│ │
|
||||
┌────▼──────┐ ┌──────▼──────┐
|
||||
│ Kernel │ │ Userspace │
|
||||
│ Schemes │ │ Scheme │
|
||||
│ (12) │ │ Daemons │
|
||||
│ │ │ (via user:) │
|
||||
│ debug: │ │ │
|
||||
│ event: │ │ ptyd │
|
||||
│ memory: │ │ pcid │
|
||||
│ pipe: │ │ ext4d │
|
||||
│ irq: │ │ fatd │
|
||||
│ time: │ │ redox-drm │
|
||||
│ sys: │ │ ... │
|
||||
│ proc: │ │ │
|
||||
│ serio: │ │ │
|
||||
└───────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
**IPC primitives available:**
|
||||
|
||||
| Primitive | Mechanism | Kernel/Userspace |
|
||||
|-----------|-----------|-----------------|
|
||||
| `pipe:` scheme | Kernel pipe scheme — bidirectional byte streams | Kernel |
|
||||
| `shm_open()` / `mmap(MAP_SHARED)` | Shared memory via memory scheme grants | Kernel |
|
||||
| `SYS_CALL` + scheme messages | Send/receive typed messages to scheme daemons | Kernel dispatch, userspace handler |
|
||||
| `fevent()` | Register kernel-level events on file descriptors | Kernel |
|
||||
| `sendfd()` | Pass file descriptors between processes | Kernel |
|
||||
| `event:` scheme | Kernel event notification (used by eventfd/signalfd/timerfd) | Kernel |
|
||||
| Signals | `sigprocmask` + `sigaction` via proc: scheme | Kernel delivery, userspace handling |
|
||||
| Futex | Fast userspace mutex via `SYS_FUTEX` | Kernel |
|
||||
|
||||
**Current IPC limitations:**
|
||||
|
||||
| Limitation | Impact |
|
||||
|-----------|--------|
|
||||
| No `SYS_PTRACE` | ptrace not available (handled via proc: scheme paths) |
|
||||
| No `SYS_KILL` | Signal sending via proc: scheme only |
|
||||
| eventfd/signalfd/timerfd recipe-applied | Bounded compatibility layers, not plain-source |
|
||||
| `ifaddrs` synthetic | Only `loopback` + `eth0`, not live enumeration |
|
||||
| POSIX message queues not implemented | `mqueue.h` missing entirely |
|
||||
| SysV message queues not implemented | `sys/msg.h` missing entirely |
|
||||
| No UNIX domain sockets (`AF_UNIX`) path | Socket-based IPC limited |
|
||||
|
||||
### 2.5 Process Model
|
||||
|
||||
Redox uses a **userspace process manager** (`procmgr` via `proc:` scheme):
|
||||
|
||||
- **fork**: Implemented through proc: scheme → kernel creates new Context with cloned address space
|
||||
- **exec**: Replaces address space with new executable image
|
||||
- **spawn**: Combined fork+exec via proc: scheme
|
||||
- **wait/waitpid/waitid**: Recipe-applied patch via proc: scheme (signals child exit)
|
||||
- **Credentials on fork**: Address space cloned (userspace `DYNAMIC_PROC_INFO` inherited)
|
||||
- **Credentials on exec**: `setresuid()` behavior (suid-bit not implemented in kernel)
|
||||
|
||||
The kernel's Context struct tracks:
|
||||
- `owner_proc_id: Option<NonZeroUsize>` — parent process for exit notification
|
||||
- `files: Arc<LockedFdTbl>` — file descriptor table (can be shared)
|
||||
- `addr_space: Option<Arc<AddrSpaceWrapper>>` — address space (can be shared = threads)
|
||||
- `sig: Option<SignalState>` — signal handler configuration
|
||||
|
||||
## 3. Critical Gaps and Blockers
|
||||
|
||||
### 3.1 Credential Syscall Blocker (Priority: P0-CRITICAL)
|
||||
|
||||
The `setgroups()` function is **ENOSYS**. This blocks:
|
||||
- `polkit` — uses `setgroups()` for privilege management
|
||||
- `dbus-daemon` — uses credentials for service activation
|
||||
- `logind` / `redbear-sessiond` — needs credential awareness
|
||||
- `sudo` / `su` — uses `initgroups()` → `setgroups()`
|
||||
- Any program that changes user identity
|
||||
|
||||
**Root cause chain:**
|
||||
1. `redox_syscall` crate (crates.io, upstream) has no `SYS_SETGROUPS`/`SYS_GETGROUPS` numbers
|
||||
2. Kernel has no supplementary group table in Context struct
|
||||
3. No group inheritance on fork/exec
|
||||
4. relibc `setgroups()` is a `todo_skip!()` stub
|
||||
5. `getgroups()` bypasses kernel entirely (reads /etc/group)
|
||||
|
||||
### 3.2 Kernel-Level Access Control Gap (Priority: P1)
|
||||
|
||||
The kernel's `caller_ctx()` provides `{euid, egid, pid}` to scheme handlers, but:
|
||||
|
||||
1. **No consistent enforcement**: Kernel schemes may or may not check caller credentials
|
||||
2. **No ruid/suid tracking**: Cannot distinguish real vs effective identity in kernel
|
||||
3. **All processes start as root** (euid=0, egid=0): No privilege separation at boot
|
||||
4. **No supplementary groups in kernel**: Only egid checked
|
||||
|
||||
### 3.3 IPC Completeness Gaps (Priority: P2)
|
||||
|
||||
| Gap | Priority | Blocked By |
|
||||
|-----|----------|------------|
|
||||
| POSIX message queues (`mqueue.h`) | P2 | Scheme design needed |
|
||||
| SysV message queues (`sys/msg.h`) | P2 | Scheme design needed |
|
||||
| UNIX domain sockets (`AF_UNIX`) | P2 | Kernel or scheme implementation |
|
||||
| Non-synthetic `ifaddrs` | P3 | Network stack enumeration |
|
||||
| eventfd/signalfd/timerfd → plain-source | P3 | Upstream relibc convergence |
|
||||
|
||||
### 3.4 Resource Limits (Priority: P2)
|
||||
|
||||
`SYS_GETRLIMIT` / `SYS_SETRLIMIT` return ENOSYS. This is a microkernel design choice:
|
||||
- Resource limits are typically library-level policy in capability systems
|
||||
- Current approach: limits enforced in userspace daemons
|
||||
- Desktop impact: systemd/logind expect rlimit support for service management
|
||||
|
||||
### 3.5 Shutdown Robustness (Priority: P2)
|
||||
|
||||
ACPI shutdown via `kstop` eventing exists but has gaps:
|
||||
- `acpid` startup has panic-grade `expect` paths
|
||||
- `_S5` derivation gated on PCI timing
|
||||
- DMAR orphaned in `acpid` source
|
||||
- See `local/docs/ACPI-IMPROVEMENT-PLAN.md` for full detail
|
||||
|
||||
## 4. Implementation Plan
|
||||
|
||||
### Phase K1: Kernel Credential Foundation (Week 1-2)
|
||||
|
||||
**Goal**: Add supplementary group support to the kernel and wire `setgroups()`/`getgroups()`.
|
||||
|
||||
#### K1.1 — Add supplementary groups to kernel Context
|
||||
|
||||
```rust
|
||||
// Context struct additions (context/context.rs):
|
||||
pub struct Context {
|
||||
// Existing:
|
||||
pub euid: u32,
|
||||
pub egid: u32,
|
||||
pub pid: usize,
|
||||
|
||||
// NEW: Real/saved IDs (moved from userspace redox-rt to kernel):
|
||||
pub ruid: u32,
|
||||
pub rgid: u32,
|
||||
pub suid: u32,
|
||||
pub sgid: u32,
|
||||
|
||||
// NEW: Supplementary groups
|
||||
pub groups: Vec<u32>, // Or Arc<[u32]> for sharing
|
||||
}
|
||||
```
|
||||
|
||||
**Files modified:**
|
||||
- `recipes/core/kernel/source/src/context/context.rs` — add fields, initialize, clone on fork
|
||||
- `recipes/core/kernel/source/src/scheme/proc.rs` — extend `ProcSchemeAttrs` to include ruid/suid/rgid/sgid/groups
|
||||
- `local/patches/kernel/` — new patch: `P4-credential-fields.patch`
|
||||
|
||||
#### K1.2 — Add `SYS_SETGROUPS` and `SYS_GETGROUPS` to redox_syscall
|
||||
|
||||
The `redox_syscall` crate is upstream (crates.io). Red Bear must either:
|
||||
- **Option A (preferred)**: Contribute upstream PR to add syscall numbers
|
||||
- **Option B**: Vendor fork of `redox_syscall` in `local/` overlay
|
||||
- **Option C**: Define Red Bear-local syscall numbers in kernel directly
|
||||
|
||||
**Recommended: Option A + B fallback**:
|
||||
1. Submit upstream PR to `redox_syscall` adding:
|
||||
- `SYS_SETGROUPS`, `SYS_GETGROUPS`
|
||||
- `SYS_SETUID`, `SYS_SETGID`, `SYS_GETUID`, `SYS_GETGID`
|
||||
- `SYS_GETEUID`, `SYS_GETEGID`
|
||||
- `SYS_SETREUID`, `SYS_SETREGID`
|
||||
- `SYS_GETRESUID`, `SYS_GETRESGID`
|
||||
|
||||
2. While upstream PR is pending, use a local `redox_syscall` patch:
|
||||
- Copy `redox_syscall` crate into `local/vendor/redox_syscall/`
|
||||
- Add syscall number constants
|
||||
- Point kernel Cargo.toml to local path
|
||||
- Patch tracked in `local/patches/kernel/P4-redox-syscall-numbers.patch`
|
||||
|
||||
#### K1.3 — Add kernel syscall handlers
|
||||
|
||||
**New file:** `recipes/core/kernel/source/src/syscall/cred.rs`
|
||||
|
||||
```rust
|
||||
// Credential syscall handlers
|
||||
pub fn setresuid(ruid: u32, euid: u32, suid: u32, token: &mut CleanLockToken) -> Result<usize> {
|
||||
let context_lock = context::current();
|
||||
let mut context = context_lock.write(token.token());
|
||||
|
||||
// Permission check: must be root or match current values
|
||||
if context.euid != 0 {
|
||||
if let Some(ruid) = ruid_opt { /* check ruid == current ruid/euid/suid */ }
|
||||
// ... POSIX permission model
|
||||
}
|
||||
|
||||
// Set values
|
||||
if ruid != u32::MAX { context.ruid = ruid; }
|
||||
if euid != u32::MAX { context.euid = euid; }
|
||||
if suid != u32::MAX { context.suid = suid; }
|
||||
Ok(0)
|
||||
}
|
||||
|
||||
pub fn setgroups(groups: &[u32], token: &mut CleanLockToken) -> Result<usize> {
|
||||
// Requires: euid == 0
|
||||
let context_lock = context::current();
|
||||
let mut context = context_lock.write(token.token());
|
||||
if context.euid != 0 { return Err(Error::new(EPERM)); }
|
||||
context.groups = groups.to_vec();
|
||||
Ok(0)
|
||||
}
|
||||
|
||||
pub fn getgroups(token: &mut CleanLockToken) -> Result<Vec<u32>> {
|
||||
let context_lock = context::current();
|
||||
let context = context_lock.read(token.token());
|
||||
Ok(context.groups.clone())
|
||||
}
|
||||
```
|
||||
|
||||
**Modified file:** `recipes/core/kernel/source/src/syscall/mod.rs`
|
||||
```rust
|
||||
match a {
|
||||
// ... existing arms ...
|
||||
SYS_SETRESUID => setresuid(b as u32, c as u32, d as u32, token),
|
||||
SYS_SETRESGID => setresgid(b as u32, c as u32, d as u32, token),
|
||||
SYS_GETRESUID => getresuid(UserSlice::wo(b, c)?, token),
|
||||
SYS_GETRESGID => getresgid(UserSlice::wo(b, c)?, token),
|
||||
SYS_SETUID => setuid(b as u32, token),
|
||||
SYS_SETGID => setgid(b as u32, token),
|
||||
SYS_GETUID => Ok(getuid(token)),
|
||||
SYS_GETGID => Ok(getgid(token)),
|
||||
SYS_GETEUID => Ok(geteuid(token)),
|
||||
SYS_GETEGID => Ok(getegid(token)),
|
||||
SYS_SETGROUPS => setgroups(UserSlice::ro(b, c)?, token).map(|()| 0),
|
||||
SYS_GETGROUPS => getgroups(UserSlice::wo(b, c)?, token),
|
||||
// ... existing arms ...
|
||||
}
|
||||
```
|
||||
|
||||
#### K1.4 — Wire relibc setgroups()/getgroups() through real syscalls
|
||||
|
||||
**Modified:** `recipes/core/relibc/source/src/platform/redox/mod.rs`
|
||||
```rust
|
||||
// Replace todo_skip!() stub:
|
||||
unsafe fn setgroups(size: size_t, list: *const gid_t) -> Result<()> {
|
||||
if size < 0 || size > NGROUPS_MAX { return Err(Errno(EINVAL)); }
|
||||
let groups = core::slice::from_raw_parts(list, size as usize);
|
||||
syscall::setgroups(groups)?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
// Replace /etc/group-based getgroups:
|
||||
fn getgroups(mut list: Out<[gid_t]>) -> Result<c_int> {
|
||||
let mut buf = [0u32; NGROUPS_MAX as usize];
|
||||
let count = syscall::getgroups(&mut buf)?;
|
||||
for (i, gid) in buf[..count].iter().enumerate() {
|
||||
list[i] = *gid as gid_t;
|
||||
}
|
||||
Ok(count as c_int)
|
||||
}
|
||||
```
|
||||
|
||||
#### K1.5 — Add credential syscall stubs in redox-rt
|
||||
|
||||
**Modified:** `recipes/core/relibc/source/redox-rt/src/sys.rs`
|
||||
```rust
|
||||
pub fn setgroups(groups: &[u32]) -> Result<()> {
|
||||
unsafe {
|
||||
redox_syscall::syscall5(
|
||||
redox_syscall::SYS_SETGROUPS,
|
||||
groups.as_ptr() as usize,
|
||||
groups.len(),
|
||||
0, 0, 0,
|
||||
)
|
||||
.map(|_| ())
|
||||
.map_err(|e| Error::new(e.errno as i32))
|
||||
}
|
||||
}
|
||||
|
||||
pub fn getgroups(buf: &mut [u32]) -> Result<usize> {
|
||||
unsafe {
|
||||
redox_syscall::syscall3(
|
||||
redox_syscall::SYS_GETGROUPS,
|
||||
buf.as_mut_ptr() as usize,
|
||||
buf.len(),
|
||||
0,
|
||||
)
|
||||
.map_err(|e| Error::new(e.errno as i32))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### K1.6 — Patch management
|
||||
|
||||
All kernel and relibc source changes must be mirrored into `local/patches/`:
|
||||
|
||||
```bash
|
||||
local/patches/
|
||||
├── kernel/
|
||||
│ ├── redox.patch # Updated symlink target
|
||||
│ ├── P4-credential-fields.patch # Context struct additions
|
||||
│ ├── P4-credential-syscalls.patch # Syscall handlers + dispatch
|
||||
│ └── P4-redox-syscall-numbers.patch # Local redox_syscall additions
|
||||
├── relibc/
|
||||
│ ├── P4-setgroups-kernel.patch # Setgroups through real syscall
|
||||
│ ├── P4-getgroups-kernel.patch # Getgroups through real syscall
|
||||
│ └── P4-redox-rt-cred-syscalls.patch # redox-rt syscall wrappers
|
||||
```
|
||||
|
||||
### Phase K2: Kernel Access Control Hardening (Week 2-3)
|
||||
|
||||
**Goal**: Enforce credential checks in kernel schemes, add proper privilege separation.
|
||||
|
||||
#### K2.1 — Enforce scheme-level credential checks
|
||||
|
||||
Each kernel scheme handler currently receives `CallerCtx { uid, gid, pid }`. Ensure consistent
|
||||
credential enforcement:
|
||||
|
||||
| Scheme | Current Check | Required Check |
|
||||
|--------|--------------|----------------|
|
||||
| `memory:` | Physical memory access → root only | ✅ Already enforced (euid==0 for phys) |
|
||||
| `irq:` | IRQ registration → root only | ✅ Already enforced |
|
||||
| `proc:` | Process inspection → caller == target OR root | 🔄 Review: ensure consistent |
|
||||
| `sys:` | System info → read-only for all | ✅ Appropriate |
|
||||
| `debug:` | Debug output → should be root-only | 🔄 Review: add check |
|
||||
| `serio:` | PS/2 device → root only | 🔄 Review: add check |
|
||||
| `event:` | Event registration → process-own only | 🔄 Review: ensure isolation |
|
||||
|
||||
#### K2.2 — Bootstrap with non-root init process
|
||||
|
||||
Currently all processes start as euid=0/egid=0. The boot sequence should:
|
||||
1. Kernel bootstrap context starts as root (euid=0, egid=0) — required for init
|
||||
2. Init (`/sbin/init`) runs as root
|
||||
3. Init drops privileges before spawning user services:
|
||||
```rust
|
||||
// In init or service manager:
|
||||
setresuid(1000, 1000, 1000); // Drop to regular user
|
||||
setgroups(&[1000, 27, 100]); // Set supplementary groups
|
||||
// Then spawn child services with restricted permissions
|
||||
```
|
||||
|
||||
#### K2.3 — Add `initgroups()` support
|
||||
|
||||
```rust
|
||||
// In relibc/src/platform/redox/mod.rs:
|
||||
fn initgroups(user: CStr, group: gid_t) -> Result<()> {
|
||||
// 1. Set primary group
|
||||
setgid(group)?;
|
||||
// 2. Parse /etc/group for supplementary groups containing this user
|
||||
let mut groups = vec![group];
|
||||
// ... iterate getgrent() to find user memberships ...
|
||||
// 3. Set supplementary groups via kernel syscall
|
||||
setgroups(&groups)?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Phase K3: IPC Infrastructure Improvements (Week 3-5)
|
||||
|
||||
**Goal**: Complete IPC primitives needed for desktop infrastructure.
|
||||
|
||||
#### K3.1 — POSIX Message Queues (`mqueue.h`)
|
||||
|
||||
**Design decision**: Implement as a userspace scheme daemon (not kernel syscalls).
|
||||
|
||||
```
|
||||
mqd:
|
||||
├── Registers as scheme:mqueue
|
||||
├── Stores queues in memory backed by shm_open() + mmap()
|
||||
├── mq_open() → open scheme:mqueue/{name}
|
||||
├── mq_send() → write to fd
|
||||
├── mq_receive() → read from fd
|
||||
├── mq_notify() → fevent() on fd for async notification
|
||||
├── mq_close() → close fd
|
||||
└── mq_unlink() → unlink scheme:mqueue/{name}
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- New Red Bear package: `local/recipes/system/mqueued/`
|
||||
- Relibc header: `recipes/core/relibc/source/src/header/mqueue/`
|
||||
- Recipe in `local/recipes/system/mqueued/recipe.toml`
|
||||
- Init service: `/usr/lib/init.d/50_mqueued.service`
|
||||
|
||||
#### K3.2 — SysV Message Queues (`sys/msg.h`)
|
||||
|
||||
**Design decision**: Implement as scheme daemon or on top of POSIX message queues.
|
||||
- Recommended: implement directly alongside `mqueued` using shared infrastructure.
|
||||
- Low priority — Qt/KDE do not depend on SysV msg queues.
|
||||
|
||||
#### K3.3 — UNIX Domain Sockets (`AF_UNIX` / `SOCK_STREAM`)
|
||||
|
||||
**Current state**: D-Bus uses abstract sockets on Linux. Redox uses scheme-based communication.
|
||||
- For D-Bus compatibility: `redbear-sessiond` already uses `zbus` with custom transport
|
||||
- For general `AF_UNIX`: implement as `scheme:unix` daemon backed by kernel pipe scheme
|
||||
- Priority: P3 — D-Bus is already working through scheme transport
|
||||
|
||||
#### K3.4 — Non-synthetic Interface Enumeration
|
||||
|
||||
Replace the hardcoded `loopback` + `eth0` model with live network interface enumeration:
|
||||
- Query `smolnetd` or equivalent for active interfaces
|
||||
- Expose through `getifaddrs()` properly
|
||||
- Priority: P3 — needed for NetworkManager-like functionality
|
||||
|
||||
#### K3.5 — eventfd/signalfd/timerfd → plain-source convergence
|
||||
|
||||
Current state: all three are recipe-applied patches. Goal: upstream into relibc mainline.
|
||||
- Monitor upstream relibc for equivalent implementations
|
||||
- When upstream absorbs: shrink/drop Red Bear patch chain
|
||||
- When upstream does NOT absorb after 3+ months: promote to durable Red Bear-maintained
|
||||
- See `local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` Phase I5
|
||||
|
||||
### Phase K4: Resource Limits and Process Management (Week 4-6)
|
||||
|
||||
#### K4.1 — RLIMIT Support
|
||||
|
||||
**Decision**: Enforce resource limits in userspace, not kernel.
|
||||
- The kernel is a microkernel — resource limits are policy
|
||||
- `getrlimit()` / `setrlimit()` → libc stubs with reasonable defaults
|
||||
- Process enforcement → `procmgr` (userspace process manager) via proc: scheme
|
||||
- File descriptor limits → already enforced via `CONTEXT_MAX_FILES` in kernel
|
||||
- Memory limits → userspace `procmgr` can kill processes exceeding limits
|
||||
|
||||
```rust
|
||||
// relibc implementation (userspace, no kernel changes needed):
|
||||
fn getrlimit(resource: c_int, rlim: *mut rlimit) -> Result<()> {
|
||||
match resource {
|
||||
RLIMIT_NOFILE => { rlim.rlim_cur = 1024; rlim.rlim_max = 4096; }
|
||||
RLIMIT_NPROC => { rlim.rlim_cur = 256; rlim.rlim_max = 1024; }
|
||||
RLIMIT_AS => { rlim.rlim_cur = RLIM_INFINITY; rlim.rlim_max = RLIM_INFINITY; }
|
||||
RLIMIT_CORE => { rlim.rlim_cur = 0; rlim.rlim_max = RLIM_INFINITY; }
|
||||
// ... other resource types with reasonable defaults
|
||||
_ => return Err(Errno(EINVAL)),
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
#### K4.2 — PTRACE via proc: scheme
|
||||
|
||||
`SYS_PTRACE` is not implemented as a direct syscall. The Redox model uses the `proc:` scheme
|
||||
for process inspection and manipulation:
|
||||
- Already partially implemented in `scheme/proc.rs`
|
||||
- Memory read/write through proc: scheme file operations
|
||||
- Register read/write through proc: scheme
|
||||
- Signal injection through proc: scheme
|
||||
|
||||
Improvements needed:
|
||||
- Document the proc: scheme ptrace API surface
|
||||
- Ensure all ptrace operations have proc: scheme equivalents
|
||||
- Add `PTRACE_*` constants to redox_syscall for compatibility
|
||||
|
||||
#### K4.3 — clock_settime
|
||||
|
||||
`SYS_CLOCK_SETTIME` returns ENOSYS. Implementation:
|
||||
- Add scheme write path to `/scheme/sys/update_time_offset`
|
||||
- Or implement as direct syscall for precision
|
||||
- Priority: P3 — needed for NTP synchronization
|
||||
|
||||
### Phase K5: Shutdown and Power Management (Week 5-7)
|
||||
|
||||
See `local/docs/ACPI-IMPROVEMENT-PLAN.md` for full ACPI plan. This section covers kernel-specific
|
||||
work only.
|
||||
|
||||
#### K5.1 — Hardened acpid Startup
|
||||
|
||||
- Remove panic-grade `expect` paths in kernel ACPI/AML handling
|
||||
- Add graceful fallback when ACPI tables are missing or malformed
|
||||
- See ACPI-IMPROVEMENT-PLAN.md Wave 1
|
||||
|
||||
#### K5.2 — kstop Shutdown Robustness
|
||||
|
||||
- Current: `_S5` shutdown via `kstop` event exists but gated on PCI timing
|
||||
- Required: deterministic shutdown ordering:
|
||||
1. Notify userspace services of impending shutdown
|
||||
2. Sync filesystems
|
||||
3. Power off via ACPI/FADT
|
||||
- See ACPI-IMPROVEMENT-PLAN.md Wave 2
|
||||
|
||||
#### K5.3 — Sleep State Support
|
||||
|
||||
- S3 (suspend-to-RAM) and S4 (hibernate) are not yet supported
|
||||
- Requires: kernel state serialization, device reinitialization
|
||||
- Priority: P4 — long-term, not blocking desktop
|
||||
|
||||
## 5. Dependency Chain
|
||||
|
||||
```
|
||||
Phase K1 (credential syscalls) ─────────────────────┐
|
||||
│ │
|
||||
├──► polkit compatibility │
|
||||
├──► dbus-daemon credential checks │
|
||||
├──► sudo/su user switching │
|
||||
├──► redbear-sessiond login1 handoff │
|
||||
└──► greeter/session-launch credential drop │
|
||||
│
|
||||
Phase K2 (access control) ────────────────────────────┤
|
||||
│ │
|
||||
├──► Privilege-separated boot sequence │
|
||||
├──► Scheme-level credential enforcement │
|
||||
└──► initgroups() for service launching │
|
||||
│
|
||||
Phase K3 (IPC) ───────────────────────────────────────┤
|
||||
│ │
|
||||
├──► POSIX message queues → needed by some apps │
|
||||
├──► AF_UNIX → broader D-Bus transport options │
|
||||
└──► eventfd/signalfd/timerfd → KDE/Qt runtime │
|
||||
│
|
||||
Phase K4 (limits/ptrace) ─────────────────────────────┤
|
||||
│ │
|
||||
├──► RLIMIT → systemd/logind compatibility │
|
||||
├──► PTRACE → debugging support │
|
||||
└──► clock_settime → NTP synchronization │
|
||||
▼
|
||||
Desktop infrastructure
|
||||
ready for KDE Plasma
|
||||
```
|
||||
|
||||
## 6. Integration with Existing Work
|
||||
|
||||
### 6.1 Already in Progress (do not duplicate)
|
||||
|
||||
| Area | Canonical Plan | Status |
|
||||
|------|---------------|--------|
|
||||
| IRQ / MSI-X / IOMMU | `IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` | Waves 1-6 complete, hardware validation open |
|
||||
| ACPI shutdown / power | `ACPI-IMPROVEMENT-PLAN.md` | Waves 1-2 complete, sleep states deferred |
|
||||
| relibc IPC surface | `RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` | Phases I1-I5, message queues deferred |
|
||||
| D-Bus / sessiond | `DBUS-INTEGRATION-PLAN.md` | Phase 1 complete, Phase 2 in progress |
|
||||
| Greeter / login | `GREETER-LOGIN-IMPLEMENTATION-PLAN.md` | Active, bounded proof passing |
|
||||
| Desktop path | `CONSOLE-TO-KDE-DESKTOP-PLAN.md` | Phase 1-5 model, KWin building |
|
||||
|
||||
### 6.2 This Plan Covers (uniquely)
|
||||
|
||||
| Area | This Plan | Not Covered By |
|
||||
|------|-----------|---------------|
|
||||
| Kernel credential architecture | §3, Phase K1 | Any existing plan |
|
||||
| Kernel access control hardening | §3.2, Phase K2 | Any existing plan |
|
||||
| `setgroups()` / `getgroups()` kernel implementation | Phase K1.2-K1.4 | Only stub noted elsewhere |
|
||||
| Supplementary group infrastructure | Phase K1.1 | Not covered anywhere |
|
||||
| POSIX/SysV message queues | Phase K3.1-K3.2 | Deferred in relibc-IPC plan |
|
||||
| UNIX domain sockets | Phase K3.3 | Not covered |
|
||||
| RLIMIT design decision | Phase K4.1 | Noted as gap only |
|
||||
| PTRACE via proc: scheme | Phase K4.2 | Not covered |
|
||||
| clock_settime implementation | Phase K4.3 | Noted as gap only |
|
||||
|
||||
## 7. Patch Governance
|
||||
|
||||
All kernel and relibc source changes must follow the durability policy (see `local/AGENTS.md`):
|
||||
|
||||
1. **Make changes** in `recipes/core/kernel/source/` or `recipes/core/relibc/source/`
|
||||
2. **Generate patches**: `git diff` in the source tree → `local/patches/<component>/P4-*.patch`
|
||||
3. **Wire patches** into `recipes/core/<component>/recipe.toml` patches list
|
||||
4. **Commit** patches + recipe changes before session end
|
||||
5. **Assume** source trees may be thrown away by `make distclean` or upstream refresh
|
||||
|
||||
### Patch naming convention:
|
||||
```
|
||||
local/patches/kernel/P4-credential-fields.patch
|
||||
local/patches/kernel/P4-credential-syscalls.patch
|
||||
local/patches/kernel/P4-redox-syscall-numbers.patch
|
||||
local/patches/relibc/P4-setgroups-kernel.patch
|
||||
local/patches/relibc/P4-getgroups-kernel.patch
|
||||
local/patches/relibc/P4-redox-rt-cred-syscalls.patch
|
||||
local/patches/relibc/P4-initgroups.patch
|
||||
```
|
||||
|
||||
## 8. Validation and Evidence
|
||||
|
||||
### 8.1 Build Evidence
|
||||
|
||||
| Check | Command |
|
||||
|-------|---------|
|
||||
| Kernel compiles | `make r.kernel` |
|
||||
| relibc compiles | `make r.relibc` |
|
||||
| Full OS builds | `make all CONFIG_NAME=redbear-full` |
|
||||
|
||||
### 8.2 Runtime Evidence
|
||||
|
||||
| Test | Verification |
|
||||
|------|-------------|
|
||||
| `getuid()` returns non-zero after login | `id` command in guest |
|
||||
| `setgroups()` succeeds for root | `sudo -u user id` in guest |
|
||||
| `setresuid()` properly changes euid | `su user -c 'id'` |
|
||||
| `initgroups()` populates groups | `groups` command in guest |
|
||||
| Credentials survive fork | `bash -c 'id'` |
|
||||
| Credentials dropped on exec (if SUID implemented) | TBD |
|
||||
| polkit can query credentials | `pkexec echo ok` |
|
||||
| dbus-daemon starts without errors | `dbus-monitor` |
|
||||
|
||||
### 8.3 Verification Scripts
|
||||
|
||||
Create bounded proof scripts:
|
||||
```bash
|
||||
local/scripts/test-credential-syscalls-qemu.sh # QEMU launcher
|
||||
local/scripts/test-credential-syscalls-guest.sh # In-guest checker
|
||||
```
|
||||
|
||||
## 9. References
|
||||
|
||||
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — Canonical comprehensive plan
|
||||
- `docs/01-REDOX-ARCHITECTURE.md` — Architecture reference
|
||||
- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — IRQ/PCI plan (sibling)
|
||||
- `local/docs/RELIBC-IPC-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` — IPC surface plan (companion)
|
||||
- `local/docs/ACPI-IMPROVEMENT-PLAN.md` — ACPI/shutdown plan (sibling)
|
||||
- `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` — Desktop path plan (consumer)
|
||||
- `recipes/core/kernel/source/src/syscall/mod.rs` — Syscall dispatch (primary implementation target)
|
||||
- `recipes/core/kernel/source/src/context/context.rs` — Context struct (credential fields)
|
||||
- `recipes/core/kernel/source/src/scheme/proc.rs` — Proc scheme (credential setting)
|
||||
- `recipes/core/relibc/source/src/platform/redox/mod.rs` — relibc Redox platform (credential stubs)
|
||||
- `recipes/core/relibc/source/redox-rt/src/sys.rs` — redox-rt credential primitives
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,137 @@
|
||||
# Red Bear OS Profile Matrix
|
||||
|
||||
## Purpose
|
||||
|
||||
This matrix makes the tracked Red Bear profiles explicit so support claims map to a concrete build
|
||||
target instead of a vague feature list.
|
||||
|
||||
## Validation Labels
|
||||
|
||||
- **builds** — configuration and packages are expected to compile
|
||||
- **boots** — image is expected to reach a usable boot state
|
||||
- **validated** — behavior has been tested on the claimed profile
|
||||
- **experimental** — available for bring-up, but not support-promised
|
||||
|
||||
Subsystem plans may add narrower intermediate labels when `boots` is too coarse. In particular, the
|
||||
USB plan uses:
|
||||
|
||||
- **enumerates** — runtime surfaces can discover controllers, ports, or descriptors
|
||||
- **usable** — a specific controller/class path works in a limited real scenario
|
||||
|
||||
## Compile Targets
|
||||
|
||||
> **Phase numbering note:** phase labels below use the v2.0 desktop plan phases from
|
||||
> `local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`. Scripts and older docs may reference the
|
||||
> historical P0–P6 hardware-enablement sequence — those are not the same numbering.
|
||||
|
||||
| Profile | Intent | Key Fragments | Current support language |
|
||||
|---|---|---|---|
|
||||
| `redbear-mini` | Console + storage + wired-network baseline | `minimal.toml`, `redbear-legacy-base.toml`, `redbear-device-services.toml`, `redbear-netctl.toml` | builds / primary validation baseline / DHCP boot profile enabled / input-runtime substrate wired / USB: daemons built via base and targeted for bounded mini-profile validation |
|
||||
| `redbear-grub` | Text-only with GRUB boot manager | `redbear-mini.toml`, `redbear-grub-policy.toml` | builds / live media variant with GRUB chainload for real bare metal / desktop graphics intentionally absent |
|
||||
| `redbear-full` | Desktop/network/session plumbing target | `desktop.toml`, `redbear-legacy-base.toml`, `redbear-legacy-desktop.toml`, `redbear-device-services.toml`, `redbear-netctl.toml`, `redbear-greeter-services.toml` | builds / boots in QEMU / active desktop-capable compile target / support claims remain evidence-qualified |
|
||||
|
||||
## Build Artifacts (ISO Organization)
|
||||
|
||||
All profiles produce outputs under `build/x86_64/`. Each profile gets its own directory:
|
||||
|
||||
| Profile | ISO | harddrive.img | Image size | QEMU RAM | Boots via `make qemu`? |
|
||||
|---------|-----|---------------|------------|----------|------------------------|
|
||||
| `redbear-mini` | `redbear-mini.iso` | `redbear-mini/harddrive.img` | 1.5 GiB | **2 GiB** | ✅ Text login |
|
||||
| `redbear-grub` | `redbear-grub.iso` | `redbear-grub/harddrive.img` | 1.5 GiB | **2 GiB** | ✅ Text login |
|
||||
| `redbear-full` | `redbear-full.iso` | `redbear-full/harddrive.img` | 4.0 GiB | **2 GiB** | ⚠️ Text login only |
|
||||
|
||||
> **⚠️ CRITICAL**: `redbear-full` requires **exactly 2 GiB** of guest RAM in QEMU. With 4 GiB or more, the kernel hangs silently during early SMP/memory initialization (x86_64 only). This is a confirmed kernel bug — see `BOOT-PROCESS-ASSESSMENT.md` Phase 7. The `make qemu` default of `QEMU_MEM=2048` is correct for all profiles.
|
||||
|
||||
### Known QEMU Issues
|
||||
|
||||
| Issue | Profiles affected | Workaround |
|
||||
|-------|-------------------|------------|
|
||||
| **Kernel hang with ≥4 GiB RAM** (nographic mode) | `redbear-full` | Use `-m 2048` or less. `make qemu` default is 2048, safe. |
|
||||
| **Graphical login fallback** — greeter uses text login, not Wayland | `redbear-full` | Set `KWIN_DRM_DEVICES=/dev/dri/card0` in greeter env; verify redox-drm daemon is running |
|
||||
| **Live ISO preload** — `unable to allocate 4078 MiB upfront` | `redbear-full` | Disable live mode (press `l` at bootloader); preload needs chunked allocation |
|
||||
| **EFI EDID unavailable** — `Failed to get EFI EDID` warning | All | Expected in QEMU; not a project issue |
|
||||
| **AHCI DVD I/O error** — empty DVD-ROM port probe | All | Benign; non-blocking |
|
||||
|
||||
### ISO naming convention
|
||||
|
||||
- **Profile ISOs**: `redbear-{profile}.iso` (e.g. `redbear-full.iso`, `redbear-mini.iso`)
|
||||
- **Legacy names** (`redbear-live-mini.iso`, `redbear-live-full.iso`) are **deprecated** and should not be used in new scripts or documentation.
|
||||
- `scripts/build-iso.sh` accepts profile names: `redbear-full`, `redbear-mini`, `redbear-grub`.
|
||||
|
||||
## Profile Notes
|
||||
|
||||
### `redbear-mini`
|
||||
|
||||
- First place to validate repository discipline and profile reproducibility.
|
||||
- Should stay smaller and less assumption-heavy than the graphics profiles.
|
||||
- Enables the shared `wired-dhcp` netctl profile by default for the VM/wired baseline.
|
||||
- Ships the shared firmware/input runtime service prerequisites so the early substrate can be tested on the smallest profile as well.
|
||||
|
||||
### Historical and experimental release fork
|
||||
|
||||
- Experimental release fork such as `redbear-bluetooth-experimental` and `redbear-wifi-experimental`
|
||||
are bounded validation slices layered on top of the tracked compile targets, not additional
|
||||
compile targets.
|
||||
|
||||
### `redbear-grub`
|
||||
|
||||
- Text-only console/recovery target with GRUB boot manager for multi-boot bare-metal workflows.
|
||||
- Inherits the same non-graphics intent as `redbear-mini`, but with GRUB chainload ESP layout.
|
||||
- Should not grow desktop/session assumptions.
|
||||
|
||||
### `redbear-full`
|
||||
|
||||
- Desktop-capable tracked target for the current Red Bear session/network/runtime plumbing surface.
|
||||
- Carries the broader D-Bus, greeter, seat, and desktop-oriented service surface.
|
||||
|
||||
### Historical notes
|
||||
|
||||
- Older names such as `redbear-minimal`, `redbear-desktop`, `redbear-wayland`, `redbear-kde`,
|
||||
`redbear-live`, `redbear-live-mini`, and `redbear-live-full` remain in older docs and some
|
||||
implementation details, but they are not the current supported compile-target surface.
|
||||
|
||||
### `redbear-bluetooth-experimental`
|
||||
|
||||
- Standalone tracked profile for the first in-tree Bluetooth slice instead of a blanket claim about
|
||||
all Red Bear images.
|
||||
- Extends `redbear-mini` so the baseline runtime tooling is already present, then adds only the
|
||||
bounded Bluetooth pieces on top.
|
||||
- Current path under active validation: QEMU/UEFI boot to login prompt plus guest-side `redbear-bluetooth-battery-check`, targeting repeated in-boot reruns, daemon-restart coverage, and one experimental battery-sensor Battery Level read-only workload.
|
||||
- Current support language is intentionally narrow: explicit-startup only, USB-attached transport,
|
||||
BLE-first CLI/scheme surface, one experimental battery-sensor Battery Level read-only workload,
|
||||
and no USB-class autospawn claim yet.
|
||||
|
||||
### `redbear-wifi-experimental`
|
||||
|
||||
- Standalone tracked profile for the current bounded Intel Wi-Fi slice instead of implying that the
|
||||
wider desktop profiles already carry the full driver stack.
|
||||
- Extends `redbear-mini` so the baseline firmware/input/reporting/profile-manager surface stays
|
||||
inherited while the Intel Wi-Fi driver package and bounded validation role remain isolated here.
|
||||
- Includes the Intel driver package (`redbear-iwlwifi`) in addition to the shared firmware,
|
||||
control-plane, reporting, and profile-manager pieces.
|
||||
- Current support language is intentionally narrow: bounded probe/prepare/init/activate/scan/
|
||||
connect/disconnect lifecycle, packaged in-target validation and capture commands, and no claim yet
|
||||
of validated real AP association or end-to-end Wi-Fi connectivity.
|
||||
|
||||
## Bluetooth Note
|
||||
|
||||
- `redbear-bluetooth-experimental` is now the tracked first Bluetooth-specific profile.
|
||||
- Its support language remains experimental and bounded; it should not be used to imply Bluetooth
|
||||
support across the wider Red Bear profile set.
|
||||
- The current bounded BLE workload is one read-only battery-sensor Battery Level interaction; this
|
||||
profile still does not claim generic GATT, write, or notify support.
|
||||
- The current validation claim is QEMU-scoped and packaged-checker-scoped, not a blanket claim
|
||||
about real hardware Bluetooth maturity.
|
||||
|
||||
## USB Note
|
||||
|
||||
- `redbear-mini` is the preferred non-graphics target for bounded USB validation because these
|
||||
proofs do not require the full desktop graphics/session surface.
|
||||
- USB validation is QEMU-only (`test-usb-qemu.sh --check`). No profile makes a real hardware USB
|
||||
support claim.
|
||||
- USB error handling and correctness carry significant Red Bear patches over upstream; see
|
||||
`local/patches/base/redox.patch` and `local/docs/USB-IMPLEMENTATION-PLAN.md` for details.
|
||||
- The in-tree mini image is still assembled through legacy `redbear-minimal*` config files in some
|
||||
places, but the supported compile-target names are `redbear-mini` and `redbear-grub`.
|
||||
- `redbear-bluetooth-experimental` uses USB only as a transport for BLE dongles; it does not make a
|
||||
general USB-class-autospawn claim.
|
||||
@@ -0,0 +1,348 @@
|
||||
# Hardware Quirks Improvement Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
This plan replaces vague “quirks support” follow-up work with a concrete path to:
|
||||
|
||||
1. keep quirks data and reporting honest,
|
||||
2. integrate quirks into real runtime driver behavior,
|
||||
3. reduce duplicated quirk logic,
|
||||
4. leave DMI and USB device quirks in a maintainable state.
|
||||
|
||||
## Current status snapshot
|
||||
|
||||
Completed from this plan:
|
||||
|
||||
- runtime DMI TOML loading in `redox-driver-sys`,
|
||||
- subsystem-gated PCI TOML matching in both the canonical path and `pcid-spawner`,
|
||||
- shipped DMI TOML overrides in the brokered `pcid-spawner` env-var path,
|
||||
- direct canonical `redox-driver-sys` quirk lookup from `pcid-spawner` instead of a separate in-tree PCI quirk engine,
|
||||
- real USB device quirk consumption in `xhcid`,
|
||||
- first real linux-kpi quirk consumption in the Red Bear amdgpu path,
|
||||
- canonical GPU quirk policy moved to the Rust driver boundary in `redox-drm`, so Intel and AMD now consume one shared quirk source for init-time policy,
|
||||
- PCI quirk extraction upgraded from handler-name guessing to explicit handler-body evidence in `local/scripts/extract-linux-quirks.py`.
|
||||
|
||||
Still open after this implementation wave:
|
||||
|
||||
- document the provenance of existing AMD `need_firmware` entries in `quirks.d/10-gpu.toml`,
|
||||
- keep AMD device-specific GPU quirk growth review-gated on Linux-backed evidence,
|
||||
- keep Intel GPU quirk expansion deferred until Red Bear has a real Intel-side firmware/runtime
|
||||
policy surface that can honestly consume additional flags.
|
||||
|
||||
Current naming/source split:
|
||||
|
||||
- PCI vendor/device **names** now come from the shipped `pciids` database (`/usr/share/misc/pci.ids`).
|
||||
- PCI/USB/storage **quirk flags** still come from Red Bear’s canonical quirk path: compiled tables,
|
||||
shipped TOML files, and conservative Linux-source extraction where applicable.
|
||||
- The `extract-linux-quirks.py` script remains a quirk-mining tool, not the source of human-readable
|
||||
PCI device names.
|
||||
|
||||
The runtime-behavior milestone from this plan is now implemented. The remaining work is
|
||||
maintenance, validation depth, and future refinement rather than missing quirks behavior for the
|
||||
shipped paths.
|
||||
|
||||
It is based on the current in-tree state of:
|
||||
|
||||
- `redox-driver-sys` as the canonical quirks library,
|
||||
- `pcid-spawner` as an upstream-owned PCI launch broker that now brokers canonical quirks,
|
||||
- `redox-drm`, `xhcid`, and the amdgpu Redox glue/runtime path as real runtime PCI quirk consumers,
|
||||
- `lspci`, `lsusb`, and `redbear-info` as reporting surfaces.
|
||||
|
||||
## Reassessment Summary
|
||||
|
||||
### What is real today
|
||||
|
||||
- `redox-driver-sys` owns the canonical PCI/USB quirk flag definitions and lookup helpers.
|
||||
- `redox-drm` consumes PCI quirks for interrupt fallback and `DISABLE_ACCEL`.
|
||||
- `xhcid` consumes PCI controller quirks via `PCI_QUIRK_FLAGS` for IRQ mode selection and reset delay.
|
||||
- `linux-kpi` exposes `pci_get_quirk_flags()` / `pci_has_quirk()` for C drivers, and amdgpu now consumes them in its Redox init path.
|
||||
- `lspci` and `lsusb` surface active PCI/USB quirk flags for discovered devices.
|
||||
- `redbear-info --quirks` reports configured TOML entries and DMI rule counts.
|
||||
|
||||
### What is still weak
|
||||
|
||||
- USB quirks now have a first real runtime consumer in `xhcid`, but broader USB-driver adoption is still missing.
|
||||
- The `linux-kpi` bridge now has a first real in-tree C consumer: amdgpu uses it for quirk-aware IRQ expectation logging. Broader C-driver adoption is still missing.
|
||||
- `pcid-spawner` still synthesizes a partial `PciDeviceInfo` instead of reusing a richer canonical PCI object, because it operates as an upstream-owned broker with a narrow interface.
|
||||
|
||||
### What should not be “fixed” in the wrong layer
|
||||
|
||||
- `firmware-loader` should stay a generic scheme service. `NEED_FIRMWARE` belongs in device driver policy, not in the firmware scheme daemon.
|
||||
- `redbear-info` should describe configured and observable state; it should not pretend to prove runtime quirk application.
|
||||
|
||||
## Target Architecture
|
||||
|
||||
### Upstream-preference policy
|
||||
|
||||
When upstream Redox already provides the same functionality, the upstream path wins by default
|
||||
unless the Red Bear-local implementation is materially better. For quirks and driver support,
|
||||
this means the canonical path should converge on `redox-driver-sys` instead of preserving
|
||||
lower-quality duplicate quirk engines as a steady state.
|
||||
|
||||
### Canonical rule
|
||||
|
||||
`redox-driver-sys` remains the authoritative quirks model:
|
||||
|
||||
- flag definitions,
|
||||
- compiled-in tables,
|
||||
- TOML parsing semantics,
|
||||
- DMI matching behavior.
|
||||
|
||||
All other code should either:
|
||||
|
||||
1. call the canonical lookup directly, or
|
||||
2. receive lookup results from a single broker that is guaranteed to use the same semantics.
|
||||
|
||||
### Driver integration rule
|
||||
|
||||
- **Rust PCI drivers using `redox-driver-sys`** should call `info.quirks()` directly.
|
||||
- **C drivers using `linux-kpi`** should call `pci_has_quirk()` / `pci_get_quirk_flags()` directly in probe/init paths.
|
||||
- **Upstream base drivers that cannot depend on `redox-driver-sys`** may continue using brokered quirk bits from `pcid-spawner`, but only if that broker is made semantically identical to the canonical library.
|
||||
- **USB device quirks** should be consumed inside `xhcid` device enumeration/configuration logic, not only in tooling.
|
||||
|
||||
## Concrete Work Plan
|
||||
|
||||
### Wave 1 — Cleanup and truthfulness
|
||||
|
||||
#### Task 1.1: Keep docs and reporting surfaces honest
|
||||
|
||||
Scope:
|
||||
|
||||
- `local/docs/QUIRKS-SYSTEM.md`
|
||||
- `local/recipes/system/redbear-info/source/src/main.rs`
|
||||
- related AGENTS references if needed
|
||||
|
||||
Goals:
|
||||
|
||||
- separate reporting surfaces from real runtime consumers,
|
||||
- remove claims that imply driver integration where only tooling exists,
|
||||
- keep “not yet implemented” items explicit.
|
||||
|
||||
QA:
|
||||
|
||||
- `cargo test` in `local/recipes/system/redbear-info/source`
|
||||
- review `redbear-info --help` text and `--quirks` output strings
|
||||
|
||||
#### Task 1.2: Remove stale equivalence claims from extraction/documentation
|
||||
|
||||
Scope:
|
||||
|
||||
- `local/scripts/extract-linux-quirks.py`
|
||||
- `local/docs/QUIRKS-SYSTEM.md`
|
||||
|
||||
Goals:
|
||||
|
||||
- avoid mapping Linux flags to incorrect Red Bear flags,
|
||||
- clearly mark the supported explicit PCI extraction patterns and the limits of unsupported handlers.
|
||||
|
||||
QA:
|
||||
|
||||
- run the script on a small synthetic USB/PXI input sample,
|
||||
- confirm output omits unsupported PCI flag mappings instead of inventing equivalents.
|
||||
|
||||
Current state:
|
||||
|
||||
- `local/scripts/extract-linux-quirks.py` no longer guesses PCI quirks from handler names.
|
||||
- PCI extraction now maps only explicit handler-body evidence for supported `PCI_DEV_FLAGS_*`
|
||||
assignments plus `pci_d3cold_disable(...)`.
|
||||
- Running the upgraded extractor on Linux 7.0 `drivers/pci/quirks.c` currently yields only a
|
||||
very small high-confidence PCI subset and no directly usable modern Intel/AMD DRM GPU entries.
|
||||
- This is intentional: false negatives are preferred over wrong GPU quirk claims.
|
||||
- The existing AMD `need_firmware` entries in `quirks.d/10-gpu.toml` are manually reviewed policy
|
||||
entries, not extractor-produced Linux facts. Future extraction runs will not refresh those flags
|
||||
automatically.
|
||||
- Intel firmware classes should be treated explicitly: DMC for display power management, GuC for
|
||||
scheduling/power, HuC for media offload, and GSC for newer authentication flows.
|
||||
- Red Bear now has a bounded Intel DMC startup manifest/preload path for the first supported Intel
|
||||
device families, but Intel `need_firmware` must still stay out of the canonical GPU quirk set
|
||||
until the broader Intel runtime policy surface is real and validated.
|
||||
- AMD device-specific GPU quirk growth remains review-gated on explicit Linux-backed evidence.
|
||||
- Intel GPU quirk expansion is deferred until Red Bear has a real Intel-side firmware/runtime
|
||||
policy surface that can honestly consume additional flags.
|
||||
|
||||
### Wave 2 — Unify PCI quirk semantics
|
||||
|
||||
#### Task 2.1: Eliminate semantic drift between `pcid-spawner` and `redox-driver-sys`
|
||||
|
||||
Constraint:
|
||||
|
||||
- `pcid-spawner` is upstream-owned base code, so any convergence work must be implemented as upstream-base changes carried by Red Bear patching until upstream absorbs them.
|
||||
|
||||
Best approach:
|
||||
|
||||
- make `pcid-spawner` consume generated/shared quirk data instead of hand-maintained duplicated tables and flag maps.
|
||||
|
||||
Preferred implementation options, in order:
|
||||
|
||||
1. **Shared generated data module** used by both `redox-driver-sys` and `pcid-spawner`.
|
||||
2. **Protocol extension** where a single canonical broker calculates quirk bits and hands them to drivers.
|
||||
3. Keep duplication only as a short-term fallback if generation is not yet practical.
|
||||
|
||||
Do **not** continue manually editing two separate PCI quirk engines long-term.
|
||||
|
||||
Success criteria:
|
||||
|
||||
- one authoritative source for compiled PCI quirk entries and flag name mapping,
|
||||
- subsystem matching behavior aligned,
|
||||
- explicit decision on whether DMI is brokered by `pcid-spawner` or left to driver-local lookup.
|
||||
|
||||
QA:
|
||||
|
||||
- compare quirk outputs for the same synthetic PCI info through both paths,
|
||||
- verify `PCI_QUIRK_FLAGS` emitted by `pcid-spawner` matches canonical lookup for representative devices.
|
||||
|
||||
#### Task 2.2: Decide DMI ownership clearly
|
||||
|
||||
Decision needed:
|
||||
|
||||
- either `pcid-spawner` becomes DMI-aware and brokers the final PCI quirk bitmask,
|
||||
- or `pcid-spawner` remains PCI/TOML-only and DMI stays driver-local in `redox-driver-sys` consumers.
|
||||
|
||||
Recommendation:
|
||||
|
||||
- near term: document the split clearly,
|
||||
- medium term: move toward one brokered result for upstream base drivers.
|
||||
|
||||
QA:
|
||||
|
||||
- one design note added to the docs explaining the chosen ownership model.
|
||||
|
||||
### Wave 3 — Real driver integration
|
||||
|
||||
#### Task 3.1: Integrate USB device quirks in `xhcid`
|
||||
|
||||
Best integration points:
|
||||
|
||||
- after device descriptor read,
|
||||
- before SetConfiguration,
|
||||
- before enabling LPM/U1/U2 or USB3-specific behavior,
|
||||
- after reset paths where extra delay or reset-after-probe is needed.
|
||||
|
||||
Minimum runtime behaviors to wire first:
|
||||
|
||||
- `NO_SET_CONFIG`
|
||||
- `NEED_RESET`
|
||||
- `NO_LPM`
|
||||
- `NO_U1U2`
|
||||
- `BAD_DESCRIPTOR`
|
||||
|
||||
Success criteria:
|
||||
|
||||
- `xhcid` calls `lookup_usb_quirks()` for enumerated devices,
|
||||
- these flags alter runtime behavior in concrete branches,
|
||||
- tooling and runtime logic agree on the same device-level quirks.
|
||||
|
||||
QA:
|
||||
|
||||
- unit/integration tests for selector logic where possible,
|
||||
- manual logging proof that a known vendor/product entry triggers the expected path.
|
||||
|
||||
#### Task 3.2: Consume linux-kpi quirks in `amdgpu`
|
||||
|
||||
Best integration points:
|
||||
|
||||
- probe path,
|
||||
- IRQ mode selection,
|
||||
- firmware gating,
|
||||
- memory/power-management setup.
|
||||
|
||||
First flags to consume:
|
||||
|
||||
- `NO_MSI`
|
||||
- `NO_MSIX`
|
||||
- `NEED_FIRMWARE`
|
||||
- `NO_ASPM`
|
||||
- `NEED_IOMMU`
|
||||
|
||||
Success criteria:
|
||||
|
||||
- at least one real C driver uses `pci_has_quirk()` in production code,
|
||||
- runtime logs show quirk-informed decision making.
|
||||
|
||||
Current state:
|
||||
|
||||
- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` now queries linux-kpi PCI quirks in the real Redox runtime path,
|
||||
- logs now show the active quirk bitmask plus the implied IRQ fallback policy,
|
||||
- firmware policy has been pulled back to the Rust-side driver boundary so the C backend does not
|
||||
re-enforce `NEED_FIRMWARE` independently.
|
||||
|
||||
QA:
|
||||
|
||||
- `grep` shows real in-tree call sites in amdgpu,
|
||||
- build passes for linux-kpi + amdgpu recipe path.
|
||||
|
||||
#### Task 3.3: Keep firmware policy in drivers, not firmware-loader
|
||||
|
||||
Action:
|
||||
|
||||
- when a driver has `NEED_FIRMWARE`, the driver should gate initialization until the firmware load succeeds.
|
||||
- `firmware-loader` remains a transport/provider only.
|
||||
|
||||
Success criteria:
|
||||
|
||||
- docs stop implying that firmware-loader interprets quirk flags,
|
||||
- driver init paths own the policy decision.
|
||||
|
||||
QA:
|
||||
|
||||
- driver code path shows firmware gating tied to quirks or explicit device rules.
|
||||
|
||||
Current state:
|
||||
|
||||
- `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` now reads the canonical
|
||||
`info.quirks()` policy during init, rejects `DISABLE_ACCEL`, and explicitly warns if
|
||||
`NEED_FIRMWARE` appears on Intel instead of silently ignoring quirk policy.
|
||||
- `local/recipes/gpu/redox-drm/source/src/main.rs` now makes firmware preload expectations explicit
|
||||
at the Rust-side driver boundary, reports whether preload is quirk-required, and summarizes
|
||||
missing candidate blobs when preload cannot satisfy the current policy.
|
||||
- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` still consumes linux-kpi quirks for
|
||||
runtime expectations, but it no longer owns the final firmware gating decision.
|
||||
|
||||
### Wave 4 — DMI completion
|
||||
|
||||
#### Task 4.1: DMI TOML runtime loading
|
||||
|
||||
Scope:
|
||||
|
||||
- `toml_loader.rs` parses `[[dmi_system_quirk]]`,
|
||||
- matching uses live DMI info served by `acpid` at `/scheme/acpi/dmi`,
|
||||
- resulting PCI quirk overrides flow through the canonical `redox-driver-sys` DMI path.
|
||||
|
||||
Success criteria:
|
||||
|
||||
- `50-system.toml` entries are no longer config-only,
|
||||
- runtime DMI TOML behavior is testable and documented through the live `acpid` DMI scheme.
|
||||
|
||||
QA:
|
||||
|
||||
- tests for TOML parsing,
|
||||
- one mock DMI input path proving a TOML DMI rule applies flags.
|
||||
|
||||
#### Task 4.2: ACPI blacklist/override layer
|
||||
|
||||
Current state:
|
||||
|
||||
- `acpid` now supports narrow `[[acpi_table_quirk]]` skip rules, optionally gated by the same
|
||||
DMI-style `match.*` fields used elsewhere.
|
||||
- The implementation is intentionally limited to table suppression during ACPI table load; it is
|
||||
not a broad AML patching or firmware replacement framework.
|
||||
|
||||
## Suggested Immediate Deliverables
|
||||
|
||||
If work resumes right away, the next concrete implementation sequence should be:
|
||||
|
||||
1. clean remaining stale quirks docs/reporting text,
|
||||
2. write a design note for canonical PCI quirk ownership,
|
||||
3. integrate `lookup_usb_quirks()` into `xhcid` enumeration/configuration,
|
||||
4. add first real `pci_has_quirk()` use in `amdgpu`,
|
||||
5. validate and extend shipped DMI TOML coverage as needed.
|
||||
|
||||
## Exit Criteria For The Next Quirks Milestone
|
||||
|
||||
The next milestone is complete when all are true:
|
||||
|
||||
- `pcid-spawner` and `redox-driver-sys` no longer drift semantically,
|
||||
- `xhcid` consumes USB device quirks at runtime,
|
||||
- at least one real C driver consumes linux-kpi quirks,
|
||||
- docs distinguish clearly between reporting, infrastructure, and true runtime behavior,
|
||||
- DMI TOML entries are either runtime-applied or removed from shipped config.
|
||||
@@ -0,0 +1,165 @@
|
||||
# Red Bear OS relibc IPC Assessment and Improvement Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
This document is the IPC-focused companion to
|
||||
`local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md`.
|
||||
|
||||
Its job is to describe the current IPC-facing relibc surface honestly, especially where the active
|
||||
Red Bear build depends on recipe-applied compatibility layers rather than plain-source upstream
|
||||
relibc.
|
||||
|
||||
## Evidence model
|
||||
|
||||
This document uses the same terms as the canonical relibc plan:
|
||||
|
||||
- **plain-source-visible**
|
||||
- **recipe-applied**
|
||||
- **test-present**
|
||||
- **runtime-unrevalidated in this pass**
|
||||
|
||||
Do not collapse those into one generic "implemented" label.
|
||||
|
||||
## Current IPC inventory
|
||||
|
||||
| Surface | Plain source | Active build | Notes |
|
||||
|---|---|---|---|
|
||||
| `shm_open()` / `shm_unlink()` | yes | yes | provided through `sys_mman` in the live source tree |
|
||||
| named POSIX semaphores | no | yes | added by `P3-semaphore-fixes.patch` on top of `shm_open()` / `mmap()` |
|
||||
| `eventfd` | no | yes | added by `P3-eventfd-mod.patch` through `/scheme/event/eventfd/...` |
|
||||
| `signalfd` | no | yes | added by `P3-signalfd.patch` through `/scheme/event` plus signal-mask handling |
|
||||
| `timerfd` | no | yes | added by `P3-timerfd-relative.patch` through `/scheme/time/{clockid}` |
|
||||
| `waitid()` | no | yes | added by `P3-waitid.patch` |
|
||||
| `ifaddrs` / `net_if` support used by IPC-adjacent consumers | no | yes | added by `P3-ifaddrs-net_if.patch`; currently synthetic |
|
||||
| SysV shm (`sys/shm.h`) | no | yes | activated via `P3-sysv-shm-impl.patch` in recipe (2026-04-29) |
|
||||
| SysV sem (`sys/sem.h`) | no | yes | activated via `P3-sysv-sem-impl.patch` in recipe (2026-04-29) |
|
||||
| POSIX message queues (`mqueue.h`) | no | no | still TODO in the live source tree |
|
||||
| SysV message queues (`sys/msg.h`) | no | no | still TODO in the live source tree |
|
||||
|
||||
## Observed limitations
|
||||
|
||||
### Named POSIX semaphores
|
||||
|
||||
The active patch chain implements named semaphores by storing a `Semaphore` inside shared memory
|
||||
opened through `shm_open()` and mapped with `mmap()`. That is a useful bounded compatibility path,
|
||||
but it should still be described as a Red Bear recipe-applied layer, not a plain-source upstream
|
||||
relibc completion.
|
||||
|
||||
### fd-event APIs
|
||||
|
||||
`eventfd`, `signalfd`, and `timerfd` are present in the active build, but they are all scheme-backed
|
||||
compatibility layers:
|
||||
|
||||
- `eventfd` depends on `/scheme/event/eventfd/...`
|
||||
- `signalfd` depends on `/scheme/event` and blocks the supplied mask with `sigprocmask()`
|
||||
- `timerfd` depends on `/scheme/time/{clockid}` and currently rejects unsupported flag combinations
|
||||
|
||||
These are real compatibility layers, but they should still be described as bounded until broader
|
||||
consumer/runtime proof is recorded.
|
||||
|
||||
### Deferred SysV shm/sem work
|
||||
|
||||
SysV shm/sem carriers were activated in recipe (2026-04-29). Message queues remain deferred follow-up work.
|
||||
|
||||
### Interface enumeration used by networking-adjacent consumers
|
||||
|
||||
The current `P3-ifaddrs-net_if.patch` replaces `ENOSYS`, but it does so with a synthetic two-entry
|
||||
model:
|
||||
|
||||
- `loopback`
|
||||
- `eth0`
|
||||
|
||||
That is enough for some bounded consumers, but it should not be described as live full interface
|
||||
enumeration.
|
||||
|
||||
## Downstream pressure
|
||||
|
||||
### Qt / KDE
|
||||
|
||||
Qt and KDE remain the strongest pressure on relibc IPC semantics.
|
||||
|
||||
They do not only need headers to exist. They need the active compatibility layers to behave well
|
||||
enough for:
|
||||
|
||||
- shared-memory consumers,
|
||||
- named semaphore consumers,
|
||||
- direct `eventfd` / `timerfd` users,
|
||||
- and process-control paths such as `waitid()`.
|
||||
|
||||
### Wayland-facing consumers
|
||||
|
||||
Wayland-facing pressure is strongest on the fd-event side of the IPC story:
|
||||
|
||||
- `eventfd`
|
||||
- `signalfd`
|
||||
- `timerfd`
|
||||
|
||||
That is a different pressure profile from the SysV and named-semaphore side.
|
||||
|
||||
## Fresh verification in this pass
|
||||
|
||||
This pass revalidated the active concrete-wave IPC-facing surface through the relibc test recipe:
|
||||
|
||||
- `sys_eventfd/eventfd`
|
||||
- `sys_signalfd/signalfd`
|
||||
- `sys_timerfd/timerfd`
|
||||
- `waitid`
|
||||
- `semaphore/named`
|
||||
- `semaphore/unnamed`
|
||||
|
||||
These are bounded relibc-target proofs. They improve confidence in the active fd-event and named
|
||||
semaphore surface. SysV shm/sem are now active in the recipe (2026-04-29); message queues remain deferred.
|
||||
|
||||
## Improvement plan
|
||||
|
||||
### Phase I1 — Keep IPC claims aligned with the active build surface
|
||||
|
||||
- document patch-applied IPC layers as patch-applied
|
||||
- stop describing them as plain-source-visible unless they move into the live source tree
|
||||
- keep this doc aligned with `recipes/core/relibc/recipe.toml`
|
||||
|
||||
### Phase I2 — Decide the support contract for bounded IPC layers
|
||||
|
||||
For each major IPC area, choose one of these paths explicitly:
|
||||
|
||||
- bounded compatibility layer with honest documentation,
|
||||
- or broader semantics work with explicit proof targets.
|
||||
|
||||
This is especially important for:
|
||||
|
||||
- SysV shm,
|
||||
- SysV sem,
|
||||
- named semaphores,
|
||||
- and `ifaddrs`-driven interface discovery.
|
||||
|
||||
### Phase I3 — Add proof where current docs only imply confidence
|
||||
|
||||
Highest-value areas:
|
||||
|
||||
- the fd-event slice used by Wayland-facing consumers,
|
||||
- shared-memory and named-semaphore behavior used by Qt/KDE,
|
||||
- and the currently synthetic interface-discovery path.
|
||||
|
||||
### Phase I4 — Triage message queues directly
|
||||
|
||||
Message queues are still genuine absences, not just bounded implementations.
|
||||
|
||||
This doc should keep them visible until Red Bear either:
|
||||
|
||||
- implements them,
|
||||
- proves they are unnecessary for the intended consumer set,
|
||||
- or explicitly documents them as deferred/non-goals.
|
||||
|
||||
### Phase I5 — Converge with upstream deliberately
|
||||
|
||||
When upstream relibc absorbs equivalent IPC functionality, prefer the upstream path and shrink the
|
||||
Red Bear patch chain. Until then, keep the active IPC carrier set explicit and documented.
|
||||
|
||||
## Bottom line
|
||||
|
||||
The current Red Bear relibc IPC story is **material patch-applied compatibility, not plain-source
|
||||
completion**.
|
||||
|
||||
That is still valuable progress, but the repo should describe it honestly: several important IPC
|
||||
surfaces exist in the active build, several of them are still bounded, and message queues remain a
|
||||
real missing area.
|
||||
@@ -0,0 +1,50 @@
|
||||
# P1-P8 Scheduler & Relibc Stability Review
|
||||
|
||||
**Date:** 2026-04-30
|
||||
**Scope:** Comprehensive review of P1-P8 kernel scheduler and relibc changes for stability, robustness, and clean code
|
||||
|
||||
## HIGH Severity — Fixed This Session
|
||||
|
||||
| # | File | Issue | Fix |
|
||||
|---|------|-------|-----|
|
||||
| 1 | `pthread_mutex.rs:89` | `make_consistent` stored dead TID instead of 0 | Store 0 for "no owner" |
|
||||
| 2 | `cond.rs:106` | `.unwrap()` suppressed EOWNERDEAD/ENOTRECOVERABLE | Changed to `.expect()` with message |
|
||||
|
||||
## HIGH Severity — Documented as Known Limitations
|
||||
|
||||
| # | File | Issue | Status |
|
||||
|---|------|-------|--------|
|
||||
| 3 | `switch.rs:396-437` | `steal_work` CPU iteration without atomicity | Structural limitation; documented with TODO |
|
||||
| 4 | `proc.rs:481,613` | Lock ordering violation TODO in kfmap/ksetup | Pre-existing; requires deeper refactoring |
|
||||
| 5 | `futex.rs:821-844` | PI futex CAS loop with `entry().or_insert()` race | Requires atomic entry creation pattern |
|
||||
|
||||
## MEDIUM Severity — Documented for Follow-up
|
||||
|
||||
| # | File | Issue |
|
||||
|---|------|-------|
|
||||
| 6 | `switch.rs:171` | TODO: Better memory orderings for CONTEXT_SWITCH_LOCK |
|
||||
| 7 | `futex.rs:370-380` | Addrspace freed while robust list walk (UAF risk) |
|
||||
| 8 | `pthread_mutex.rs:140` | `mutex_owner_id_is_live` O(n) scan |
|
||||
| 9 | `pthread_mutex.rs:37-39` | SPIN_COUNT = 0 — no adaptive spinning |
|
||||
| 10 | `barrier.rs` | No pthread_barrier_destroy — memory leak |
|
||||
| 11 | `sched/mod.rs` | All sched_* functions return ENOSYS (honest stubs) |
|
||||
| 12 | `pthread/mod.rs:553` | pthread_setname_np allocates format! on every call |
|
||||
|
||||
## Build Verification
|
||||
|
||||
- `cargo check` relibc: ✅ passes (1 pre-existing warning)
|
||||
- `make r.kernel`: ✅ passes
|
||||
- P8 patches in recipe: 5 of 8 wired (3 not yet wired — initial-placement, load-balance, work-stealing)
|
||||
|
||||
## Honest Status Assessment
|
||||
|
||||
| Phase | Status | Notes |
|
||||
|-------|--------|-------|
|
||||
| P0 | ✅ Complete | Barrier SMP, sigmask, pthread_kill |
|
||||
| P1 | ✅ Complete | Robust mutexes, sched API (honest ENOSYS) |
|
||||
| P2 | ✅ Complete | RT scheduling, SchedPolicy |
|
||||
| P3 | 🚧 Partial | PerCpuSched + wiring done; stealing/balancing deferred |
|
||||
| P4 | ✅ Complete | Futex sharding + REQUEUE + PI + robust |
|
||||
| P5 | ✅ Complete | setpriority, affinity, thread naming, schedparam |
|
||||
| P6 | 🚧 Partial | Cache-affine done; NUMA deferred |
|
||||
| P7-P8 | ✅ Complete | Futex REQUEUE/PI/robust deliverable |
|
||||
@@ -0,0 +1,114 @@
|
||||
# Red Bear OS Script Behavior Matrix
|
||||
|
||||
## Purpose
|
||||
|
||||
This document centralizes what the main repository scripts do and do not handle under the Red Bear
|
||||
release fork model.
|
||||
|
||||
The goal is to remove guesswork from the sync/fetch/apply/build workflow.
|
||||
|
||||
## Matrix
|
||||
|
||||
| Script | Primary role | What it handles | What it does **not** guarantee |
|
||||
|---|---|---|---|
|
||||
| `local/scripts/provision-release.sh` | Refresh top-level upstream repo state | fetches upstream, reports conflict risk, rebases repo commits, reapplies build-system release fork via `apply-patches.sh` | does not automatically solve every subsystem release fork conflict; does not by itself make upstream WIP recipes safe shipping inputs |
|
||||
| `local/scripts/apply-patches.sh` | Reapply durable Red Bear release fork | applies build-system patches, relinks recipe patch symlinks, relinks local recipe release fork into `recipes/` | does not fully rebase stale patch carriers; does not validate runtime behavior; does not decide WIP ownership for you |
|
||||
| `local/scripts/build-redbear.sh` | Build Red Bear profiles from upstream base + local release fork | applies release fork, builds cookbook if needed, validates profile naming, launches the actual image build; only allows upstream recipe immutable archived when passed `--upstream` | does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation |
|
||||
| `scripts/fetch-all-sources.sh` | Fetch mainline recipe source inputs for builds | downloads mainline/upstream recipe sources, reports status/preflight, and supports config-scoped fetches while leaving local release fork in place | does not mean fetched upstream WIP source is the durable shipping source of truth |
|
||||
| `local/scripts/fetch-sources.sh` | Fetch mainline recipe sources for browsing and patching | when passed `--upstream`, fetches `recipes/*` source trees so the upstream-managed side is locally available for reading, editing, and patch preparation | does not decide whether upstream should replace the local release fork |
|
||||
| `local/scripts/build-redbear-wifictl-redox.sh` | Build `redbear-wifictl` for the Redox target with the repo toolchain | prepends `prefix/x86_64-unknown-redox/sysroot/bin` to `PATH` and runs `cargo build --target x86_64-unknown-redox` in the `redbear-wifictl` crate | does not prove runtime Wi-Fi behavior; only closes the target-build environment gap for this crate |
|
||||
| `local/scripts/test-iwlwifi-driver-runtime.sh` | Exercise the bounded Intel driver lifecycle inside a target runtime | validates bounded probe/prepare/init/activate/scan/connect/disconnect/retry surfaces for `redbear-iwlwifi` on a live target runtime | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end connectivity |
|
||||
| `local/scripts/test-wifi-control-runtime.sh` | Exercise the bounded Wi-Fi control/profile lifecycle inside a target runtime | validates `/scheme/wifictl` control nodes, bounded connect/disconnect behavior, and profile-manager/runtime reporting surfaces on a live target runtime | does not prove real AP association or end-to-end connectivity |
|
||||
| `local/scripts/test-wifi-baremetal-runtime.sh` | Exercise bounded Intel Wi-Fi runtime lifecycle on a target system | validates driver probe, control probe, bounded connect/disconnect, profile-manager start/stop via the `wifi-open-bounded` profile, Wi-Fi lifecycle reporting, and writes `/tmp/redbear-phase5-wifi-capture.json` on the target | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end hardware connectivity |
|
||||
| `local/scripts/test-wifi-passthrough-qemu.sh` | Launch Red Bear with VFIO-passed Intel Wi-Fi hardware | boots a Red Bear guest with a passed-through Intel Wi-Fi PCI function, auto-runs the in-guest bounded Wi-Fi validation command, and can copy the packaged capture bundle back to a host-side file during `--check` | depends on host VFIO setup and still does not by itself guarantee real AP association or end-to-end Wi-Fi connectivity |
|
||||
| `local/scripts/test-bluetooth-runtime.sh` | Compatibility guest entrypoint for the bounded Bluetooth Battery Level slice | runs the packaged `redbear-bluetooth-battery-check` helper inside a Redox guest or target runtime | does not run on the host and does not expand the Bluetooth support claim beyond the packaged checker’s bounded scope |
|
||||
| `local/scripts/test-bluetooth-qemu.sh` | Launch or validate the bounded Bluetooth Battery Level slice in QEMU | boots `redbear-bluetooth-experimental`, auto-runs the packaged checker during `--check`, reruns it in one boot, and reruns it again after a clean reboot | does not by itself guarantee that the current QEMU proof passes; does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior |
|
||||
| `local/scripts/test-drm-display-runtime.sh` | Run the bounded DRM/KMS display checker in a target runtime | invokes the packaged `redbear-drm-display-check` helper for AMD or Intel, proving scheme/card reachability, connector/mode enumeration, and bounded direct modeset proof over the Red Bear DRM ioctl surface when requested | does not prove render command submission, fence semantics, or hardware rendering |
|
||||
| `local/scripts/test-amd-gpu.sh` | AMD wrapper for the bounded DRM/KMS display checker | runs `test-drm-display-runtime.sh --vendor amd` | still only display-path evidence |
|
||||
| `local/scripts/test-intel-gpu.sh` | Intel wrapper for the bounded DRM/KMS display checker | runs `test-drm-display-runtime.sh --vendor intel` | still only display-path evidence |
|
||||
| `local/scripts/test-msix-qemu.sh` | Bounded MSI-X proof in QEMU | validates that the current virtio-net guest path reaches MSI-X-capable interrupt delivery and emits normalized `IRQ_DRIVER`, `IRQ_MODE`, `IRQ_REASON`, and `IRQ_LOG` output for the bounded guest/runtime proof | does not prove broad hardware MSI-X reliability or per-device fallback behavior outside the bounded guest path |
|
||||
| `local/scripts/test-iommu-qemu.sh` | Bounded IOMMU first-use proof in QEMU | validates guest-visible AMD-Vi initialization and bounded event/drain behavior through the current `iommu` runtime path | does not prove real-hardware interrupt remapping quality or full DMA-remapping correctness |
|
||||
| `local/scripts/test-xhci-irq-qemu.sh` | Bounded xHCI interrupt-mode proof in QEMU | validates that the xHCI guest path reaches an interrupt-driven mode under the current bounded runtime checker and emits normalized `IRQ_DRIVER`, `IRQ_MODE`, `IRQ_REASON`, and `IRQ_LOG` output | does not prove full USB topology maturity or broad hardware interrupt robustness |
|
||||
| `local/scripts/test-lowlevel-controllers-qemu.sh` | Aggregate bounded low-level controller proof wrapper | runs MSI-X, xHCI IRQ, IOMMU first-use, PS/2/serio, and monotonic timer proofs in one sequence, defaulting to `redbear-mini` while automatically upgrading only the IOMMU leg to `redbear-full` because that runtime currently ships `/usr/bin/iommu`; if the required `redbear-full` image is absent, that single IOMMU leg is explicitly skipped rather than aborting the rest of the bounded wrapper | does not replace the individual proof helpers and does not prove real-hardware controller quality |
|
||||
| `local/scripts/prepare-wifi-vfio.sh` | Prepare or restore an Intel Wi-Fi PCI function for passthrough | binds a chosen PCI function to `vfio-pci` or restores it to a specified host driver | does not verify guest Wi-Fi functionality and must be used carefully on a host with a safe detachable target device |
|
||||
| `local/scripts/validate-wifi-vfio-host.sh` | Check whether a host looks ready for Wi-Fi VFIO testing | validates PCI presence, current driver, UEFI firmware, Red Bear image presence, QEMU/expect availability, VFIO module state, and IOMMU group visibility; exits non-zero when blockers are found | does not bind devices or prove the guest Wi-Fi stack works |
|
||||
| `local/scripts/run-wifi-passthrough-validation.sh` | End-to-end host-side passthrough validation wrapper | prepares VFIO, runs the packaged in-guest Wi-Fi validation path, captures the guest JSON artifact to the host, writes a host-side metadata sidecar, and restores the host driver afterwards | still depends on real VFIO/hardware support and does not itself guarantee end-to-end Wi-Fi connectivity |
|
||||
| `local/scripts/package-wifi-validation-artifacts.sh` | Bundle Wi-Fi validation evidence into one archive | packages common capture/log artifacts from bare-metal or VFIO validation runs into a single tarball | does not create missing artifacts or validate their contents |
|
||||
| `local/scripts/summarize-wifi-validation-artifacts.sh` | Summarize Wi-Fi validation evidence quickly | extracts key runtime signals from a capture JSON or packaged tarball for fast triage | does not replace full artifact review or prove runtime correctness |
|
||||
| `local/scripts/finalize-wifi-validation-run.sh` | One-shot post-run Wi-Fi triage helper | runs the packaged analyzer on a capture JSON and then packages the chosen artifacts into a tarball | still depends on a real target run having produced the capture/artifacts first |
|
||||
|
||||
The packaged companion command for those scripts is `redbear-phase5-wifi-check`, which performs the
|
||||
bounded in-target Wi-Fi lifecycle checks from inside the guest/runtime itself.
|
||||
|
||||
The packaged Bluetooth companion command is `redbear-bluetooth-battery-check`, which is intended to
|
||||
perform the bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including
|
||||
repeated helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup
|
||||
checks within the current slice boundary.
|
||||
|
||||
The packaged DRM display companion command is `redbear-drm-display-check`, which is intended to
|
||||
perform bounded DRM/KMS display-side checks from inside the guest/runtime itself. It now covers
|
||||
direct connector/mode enumeration and bounded direct modeset proof over the Red Bear DRM ioctl
|
||||
surface, and explicitly does not claim render or hardware-accelerated graphics completion.
|
||||
|
||||
The packaged evidence companion is `redbear-phase5-wifi-capture`, which collects the bounded driver,
|
||||
control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus `lspci`
|
||||
and active-profile contents — into a single JSON artifact.
|
||||
|
||||
The packaged link-oriented companion is `redbear-phase5-wifi-link-check`, which focuses on whether
|
||||
the target runtime is exposing interface/address/default-route signals in addition to the bounded
|
||||
Wi-Fi lifecycle state.
|
||||
|
||||
For Redox-target Rust builds of Wi-Fi components such as `redbear-wifictl`, a missing
|
||||
`x86_64-unknown-redox-gcc` on `PATH` should first be treated as a host toolchain/path issue if the
|
||||
repo already contains `prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-redox-gcc`.
|
||||
|
||||
## Policy Mapping
|
||||
|
||||
### Resilience / offline-first package sourcing
|
||||
|
||||
Default Red Bear behavior is local-first:
|
||||
|
||||
- use locally available package/source trees and release fork state for normal builds,
|
||||
- treat upstream immutable archived as an explicit operator action only (`--upstream`, dedicated fetch/sync),
|
||||
- do not fail policy-level expectations just because upstream network access is temporarily broken.
|
||||
|
||||
This is required so builds and recovery workflows remain operable during upstream outages or
|
||||
connectivity failures.
|
||||
|
||||
### Upstream sync
|
||||
|
||||
Use `local/scripts/provision-release.sh` when the goal is to immutable archived the top-level upstream Redox base.
|
||||
|
||||
This is a repository sync operation, not a guarantee that every local subsystem release fork is already
|
||||
rebased cleanly.
|
||||
|
||||
### Overlay reapplication
|
||||
|
||||
Use `local/scripts/apply-patches.sh` when the goal is to reconstruct Red Bear’s release fork on top of a
|
||||
fresh upstream tree.
|
||||
|
||||
This is the core durable-state recovery path.
|
||||
|
||||
### Build execution
|
||||
|
||||
Use `local/scripts/build-redbear.sh` when the goal is to build a tracked Red Bear profile from the
|
||||
current upstream base plus local release fork. Add `--upstream` only when you explicitly want Redox/upstream
|
||||
recipe sources immutable archived during that build.
|
||||
|
||||
### Source immutable archived
|
||||
|
||||
Use `scripts/fetch-all-sources.sh` and `local/scripts/fetch-sources.sh --upstream` when the goal is to
|
||||
immutable archived recipe source inputs, but do not confuse fetched upstream WIP source with a trusted shipping
|
||||
source.
|
||||
|
||||
## WIP Rule in Script Terms
|
||||
|
||||
If a subsystem is still upstream WIP, the scripts should be interpreted this way:
|
||||
|
||||
- fetching upstream WIP source is allowed and useful through the explicit upstream fetch commands or
|
||||
`--upstream` where a wrapper requires it,
|
||||
- syncing upstream WIP source is allowed and useful through the explicit upstream sync command,
|
||||
- but shipping decisions should still prefer the local release fork until upstream promotion and reevaluation happen.
|
||||
|
||||
That means “script fetched it successfully” is not the same as “Red Bear should now ship upstream’s
|
||||
WIP version directly.”
|
||||
@@ -0,0 +1,137 @@
|
||||
# Red Bear OS USB Validation Runbook
|
||||
|
||||
This runbook is the canonical operator path for exercising the USB stack on Red Bear OS.
|
||||
|
||||
It does not claim that USB is broadly solved. Its job is to make the current QEMU-validated USB
|
||||
workload reproducible and honest.
|
||||
|
||||
## Goal
|
||||
|
||||
Produce one or both of the following:
|
||||
|
||||
- a successful USB stack validation via `redbear-usb-check` inside the guest
|
||||
- a repeatable QEMU/UEFI validation log via `./local/scripts/test-usb-qemu.sh --check`
|
||||
- a repeatable bounded xHCI lifecycle log via `./local/scripts/test-xhci-device-lifecycle-qemu.sh --check`
|
||||
|
||||
## Path A - Host-side QEMU validation
|
||||
|
||||
Use this when the host supports the repo's normal x86_64 QEMU/UEFI flow.
|
||||
|
||||
### On the host
|
||||
|
||||
Build the tracked mini profile first:
|
||||
|
||||
```bash
|
||||
./local/scripts/build-redbear.sh redbear-mini
|
||||
```
|
||||
|
||||
Then run the automated QEMU harness:
|
||||
|
||||
```bash
|
||||
./local/scripts/test-usb-qemu.sh --check
|
||||
./local/scripts/test-xhci-device-lifecycle-qemu.sh --check
|
||||
```
|
||||
|
||||
What that harness does today:
|
||||
|
||||
1. boots `redbear-mini` in QEMU with `qemu-xhci`, USB keyboard, USB tablet, and USB mass storage
|
||||
2. captures the full boot log over serial
|
||||
3. checks for xHCI interrupt-driven mode in the log
|
||||
4. checks for USB HID driver spawn
|
||||
5. checks for USB SCSI driver spawn
|
||||
6. checks for BOS descriptor processing (or graceful fallback for USB 2 devices)
|
||||
7. checks that no crash-class errors appear in the log
|
||||
|
||||
What the lifecycle harness does today:
|
||||
|
||||
1. boots `redbear-mini` in QEMU with `qemu-xhci` and no pre-attached USB devices
|
||||
2. logs into the guest over serial, then uses the QEMU monitor to hotplug a USB keyboard
|
||||
3. requires xHCI attach and completion logs plus USB HID driver spawn evidence
|
||||
4. uses one-shot guest-side `/tmp/xhcid-test-hook` commands to inject a bounded
|
||||
post-`SET_CONFIGURATION` failure and a delayed attach-commit timing case
|
||||
5. hot-unplugs the keyboard and requires detach evidence
|
||||
6. hotplugs and hot-unplugs a USB storage device and requires attach/detach plus SCSI driver spawn evidence
|
||||
7. fails on panic-class or teardown-class xHCI errors in the captured log
|
||||
|
||||
### Artifact to preserve
|
||||
|
||||
- the full terminal log from `./local/scripts/test-usb-qemu.sh --check`
|
||||
- the full terminal log from `./local/scripts/test-xhci-device-lifecycle-qemu.sh --check`
|
||||
|
||||
## Path B - Interactive guest validation
|
||||
|
||||
Use this when you want to inspect the runtime manually inside the guest.
|
||||
|
||||
### On the host
|
||||
|
||||
```bash
|
||||
./local/scripts/test-usb-qemu.sh redbear-mini
|
||||
```
|
||||
|
||||
### Inside the guest
|
||||
|
||||
Run the packaged checker directly:
|
||||
|
||||
```bash
|
||||
redbear-usb-check
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```
|
||||
redbear-usb-check: found N usb scheme entries: [...]
|
||||
redbear-usb-check: xhci.0 -> M ports
|
||||
redbear-usb-check: port 1 -> vendor:product [device name]
|
||||
redbear-usb-check: port 2 -> vendor:product [device name] [SS]
|
||||
redbear-usb-check: xhci controllers: ["xhci.0"]
|
||||
redbear-usb-check: all checks passed
|
||||
```
|
||||
|
||||
The checker walks `/scheme/usb/` and `/scheme/xhci/` to verify that the xHCI controller is
|
||||
enumerated, ports have devices attached, and device descriptors are readable.
|
||||
|
||||
## What this validates
|
||||
|
||||
- xHCI controller initialization
|
||||
- USB device enumeration and descriptor fetching
|
||||
- BOS/SuperSpeed capability detection
|
||||
- HID class driver spawning (keyboard/tablet)
|
||||
- SCSI class driver spawning (mass storage)
|
||||
- bounded xHCI hotplug attach/detach lifecycle behavior for HID and storage devices in QEMU
|
||||
- No panic or crash-class errors in USB daemons
|
||||
|
||||
## What this does not validate
|
||||
|
||||
- Real hardware USB controllers (QEMU qemu-xhci only)
|
||||
- Hub topology (direct-attached devices only in the default harness)
|
||||
- USB 3 SuperSpeed data paths
|
||||
- Isochronous or streaming transfers
|
||||
- Broad hot-plug stress testing on real hardware
|
||||
- USB device mode / OTG / USB-C
|
||||
|
||||
## Existing USB test scripts
|
||||
|
||||
| Script | What it tests |
|
||||
|--------|---------------|
|
||||
| `test-usb-qemu.sh --check` | Full USB stack (xHCI + HID + SCSI + bounded sector-0 readback + BOS + no crashes) |
|
||||
| `test-xhci-device-lifecycle-qemu.sh --check` | Bounded xHCI hotplug lifecycle proof for HID + storage attach/detach |
|
||||
| `test-usb-storage-qemu.sh` | USB mass storage autospawn + bounded sector-0 readback + crash pattern check |
|
||||
| `test-xhci-irq-qemu.sh --check` | xHCI interrupt delivery mode (MSI/MSI-X/INTx) |
|
||||
| `test-usb-maturity-qemu.sh` | Sequential wrapper for the bounded USB maturity checks |
|
||||
|
||||
In-guest quick checks:
|
||||
- `lsusb` — walks `/scheme/usb.*`, reads descriptors, shows vendor:product + quirks
|
||||
- `redbear-info --verbose` — reports USB controller count and integration status
|
||||
- `redbear-usb-check` — scheme tree walk with pass/fail exit code
|
||||
|
||||
## Compile-target note
|
||||
|
||||
Red Bear has exactly three compile targets:
|
||||
|
||||
- `redbear-mini`
|
||||
- `redbear-full`
|
||||
- `redbear-grub`
|
||||
|
||||
Older names such as `redbear-desktop`, `redbear-wayland`, `redbear-kde`, `redbear-minimal`,
|
||||
`redbear-live-mini`, and `redbear-live-full` may still appear in historical notes or
|
||||
implementation details, but they are not the supported compile-target surface.
|
||||
@@ -0,0 +1,360 @@
|
||||
# xhcid Device-Level Improvement Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the implementation sequence for hardening `xhcid` at the device level in
|
||||
Red Bear OS.
|
||||
|
||||
It is a focused companion to `local/docs/USB-IMPLEMENTATION-PLAN.md`. The USB plan remains the
|
||||
subsystem-wide authority; this document narrows scope to the `xhcid` device lifecycle,
|
||||
configuration, teardown, PM behavior, enumerator robustness, and bounded proof coverage.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/device_enumerator.rs`
|
||||
- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/mod.rs`
|
||||
- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/scheme.rs`
|
||||
- `recipes/core/base/source/drivers/usb/xhcid/src/xhci/irq_reactor.rs`
|
||||
- bounded QEMU validation scripts under `local/scripts/`
|
||||
- canonical USB documentation under `local/docs/`
|
||||
|
||||
Out of scope:
|
||||
|
||||
- generic USB redesign
|
||||
- unrelated class-driver feature work
|
||||
- hardware-validation claims beyond what the repo can currently prove
|
||||
|
||||
## Repo-Fit Note
|
||||
|
||||
Technical implementation targets live in upstream-owned source under
|
||||
`recipes/core/base/source/...`, but durable Red Bear preservation belongs in
|
||||
`local/patches/base/`. This plan names the technical work locations, not a recommendation to leave
|
||||
work stranded only in upstream-owned trees.
|
||||
|
||||
## Current Audited Findings
|
||||
|
||||
The current `xhcid` tree has already improved materially:
|
||||
|
||||
- lifecycle gating exists through `PortLifecycle` and `PortOperationGuard`
|
||||
- `configure_endpoints_once()` is now transactional relative to earlier behavior
|
||||
- detach waits before removing published state
|
||||
- a bounded QEMU lifecycle proof exists
|
||||
|
||||
Remaining risks:
|
||||
|
||||
- partial attach visibility still exists around publication timing
|
||||
- detach can still depend on bounded-but-incomplete purge semantics
|
||||
- suspend/resume is still mainly software gating
|
||||
- rollback failure is not yet a fully hardened degraded-state path
|
||||
- enumerator logic still relies on timing- and assumption-heavy behavior
|
||||
- proof coverage is still QEMU-bounded and misses key interleavings
|
||||
|
||||
## Design Invariants
|
||||
|
||||
The implementation should satisfy these invariants:
|
||||
|
||||
1. No half-attached device is publicly usable.
|
||||
2. No new work is admitted after detach begins.
|
||||
3. Detach always reaches a bounded terminal outcome.
|
||||
4. Failed configure leaves either the old config intact or the device explicitly
|
||||
degraded/reset-required.
|
||||
5. PM transitions reflect actual usable state, not only software policy.
|
||||
6. Enumerator behavior is bounded and diagnosable, not panic-driven.
|
||||
7. Validation claims match what scripts actually prove.
|
||||
|
||||
## Phase 1 — Proof-First Expansion
|
||||
|
||||
### Goal
|
||||
|
||||
Make the current blind spots reproducible before changing behavior.
|
||||
|
||||
### Work
|
||||
|
||||
- extend `test-xhci-device-lifecycle-qemu.sh`
|
||||
- extend `test-usb-qemu.sh`
|
||||
- extend `test-xhci-irq-qemu.sh`
|
||||
- add bounded injection hooks in `xhcid` for configure-failure and attach/detach timing cases
|
||||
|
||||
### Required Cases
|
||||
|
||||
- repeated attach/detach
|
||||
- detach during storage startup
|
||||
- transfer-during-detach surrogate
|
||||
- configure failure injection
|
||||
- suspend/resume admission checks
|
||||
- rapid event ordering cases
|
||||
|
||||
### Per-File Focus
|
||||
|
||||
#### `local/scripts/test-xhci-device-lifecycle-qemu.sh`
|
||||
|
||||
- add repeated HID/storage attach-detach loops
|
||||
- add detach-during-driver-start for storage
|
||||
- add storage attach long enough to exercise startup/read activity before unplug
|
||||
- require explicit attach-entered, attach-finished, detach-completed evidence
|
||||
|
||||
#### `local/scripts/test-usb-qemu.sh`
|
||||
|
||||
- separate boot progress from proof failure
|
||||
- keep result lines distinct for xHCI init, HID spawn, SCSI spawn, bounded readback, and crash scan
|
||||
- add repeated full-stack run mode or bounded loop count if needed for ordering-sensitive regressions
|
||||
|
||||
#### `local/scripts/test-xhci-irq-qemu.sh`
|
||||
|
||||
- verify interrupt-mode evidence still holds under actual attached-device pressure, not only empty-controller boot
|
||||
|
||||
#### `xhci` test hooks
|
||||
|
||||
- add bounded test-only failure hooks in `scheme.rs` / `mod.rs` for:
|
||||
- fail after `CONFIGURE_ENDPOINT`
|
||||
- fail after `SET_CONFIGURATION`
|
||||
- optional delay before final attach commit
|
||||
- current bounded implementation uses one-shot guest-side commands written to
|
||||
`/tmp/xhcid-test-hook`, consumed by `xhcid` on the next matching lifecycle point
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- scripts are syntax-clean
|
||||
- new cases fail meaningfully on current gaps
|
||||
- failures identify the specific missed milestone
|
||||
|
||||
## Phase 2 — Atomic Attach Publication
|
||||
|
||||
### Goal
|
||||
|
||||
Prevent half-built devices from becoming publicly reachable.
|
||||
|
||||
### Work
|
||||
|
||||
- refactor `Xhci::attach_device`
|
||||
- split attach staging from published `PortState`
|
||||
- narrow lifecycle exposure so scheme paths cannot reach a device before final commit
|
||||
- make attach cleanup direct for prepublication failure
|
||||
|
||||
### Key Targets
|
||||
|
||||
- `xhci/mod.rs::Xhci::attach_device`
|
||||
- `xhci/mod.rs::PortLifecycle::*`
|
||||
- `xhci/device_enumerator.rs::DeviceEnumerator::run`
|
||||
|
||||
### Per-File Focus
|
||||
|
||||
#### `xhci/mod.rs`
|
||||
|
||||
- stop inserting into `port_states` before all attach substeps complete
|
||||
- keep slot, input context, EP0 ring, quirks, and descriptors in a private staging carrier
|
||||
- commit published `PortState` in one final block
|
||||
- keep prepublication cleanup separate from `detach_device()` where possible
|
||||
|
||||
#### `xhci/device_enumerator.rs`
|
||||
|
||||
- ensure duplicate connect handling still treats `EAGAIN` or equivalent as "already published" rather than "half-built staging state"
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- no public state before attach commit
|
||||
- attach failure leaves no published device and no child driver
|
||||
|
||||
## Phase 3 — Bounded Detach and Purge
|
||||
|
||||
### Goal
|
||||
|
||||
Make teardown bounded, dominant, and safe against stale completions.
|
||||
|
||||
### Work
|
||||
|
||||
- bound `PortLifecycle::begin_detaching()`
|
||||
- reject all new work immediately once detach starts
|
||||
- purge or tombstone pending transfer/reactor state
|
||||
- separate graceful drain from forced teardown
|
||||
- preserve correct slot-disable/remove ordering
|
||||
- ensure child-driver shutdown cannot wedge detach
|
||||
|
||||
### Key Targets
|
||||
|
||||
- `xhci/mod.rs`
|
||||
- `xhci/irq_reactor.rs`
|
||||
- transfer bookkeeping in `xhci/scheme.rs`
|
||||
|
||||
### Per-File Focus
|
||||
|
||||
#### `xhci/mod.rs`
|
||||
|
||||
- add timeout or bounded wait to detach drain logic
|
||||
- distinguish graceful drain from forced teardown
|
||||
- keep `port_states.remove(...)` after terminal teardown outcome
|
||||
|
||||
#### `xhci/irq_reactor.rs`
|
||||
|
||||
- add per-port invalidation or tombstone behavior so stale completions cannot target removed state
|
||||
|
||||
#### `xhci/scheme.rs`
|
||||
|
||||
- ensure operation-entry helpers fail immediately once detach starts
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- detach cannot hang forever
|
||||
- no stale completion can target removed device state
|
||||
- unload-under-activity proof passes
|
||||
|
||||
## Phase 4 — Configure Rollback Hardening
|
||||
|
||||
### Goal
|
||||
|
||||
Make configuration changes fully transactional and recoverable.
|
||||
|
||||
### Work
|
||||
|
||||
- formalize stage/program/commit boundaries
|
||||
- ensure snapshots cover all mutated controller-facing state
|
||||
- promote rollback failure into explicit degraded-state handling
|
||||
- define deterministic behavior for post-`SET_CONFIGURATION` failure
|
||||
- keep alternate/config bookkeeping coherent after rollback
|
||||
- quarantine or reset on unrecoverable ambiguity
|
||||
|
||||
### Key Targets
|
||||
|
||||
- `xhci/scheme.rs::configure_endpoints_once`
|
||||
- `restore_configure_input_context`
|
||||
- `configure_endpoints`
|
||||
- `set_configuration`
|
||||
- `set_interface`
|
||||
|
||||
### Per-File Focus
|
||||
|
||||
#### `xhci/scheme.rs`
|
||||
|
||||
- keep endpoint/ring state staged until commit
|
||||
- verify snapshots cover every mutated slot/endpoint field
|
||||
- treat rollback failure as a first-class degraded state
|
||||
- ensure post-failure descriptor and alternate bookkeeping still reflect live state
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- injected configure failure preserves old state or explicitly degrades/resets device
|
||||
- no staged endpoint state leaks into live software state
|
||||
|
||||
## Phase 5 — Real PM Sequencing
|
||||
|
||||
### Goal
|
||||
|
||||
Replace software-only PM gating with meaningful quiesce/resume semantics.
|
||||
|
||||
### Work
|
||||
|
||||
- define richer PM transition states
|
||||
- quiesce before suspend
|
||||
- tie resume to controller/device validity
|
||||
- define PM interaction with detach
|
||||
- define PM interaction with configure
|
||||
- add bounded PM proof cases
|
||||
|
||||
### Key Targets
|
||||
|
||||
- `xhci/scheme.rs::suspend_device`
|
||||
- `xhci/scheme.rs::resume_device`
|
||||
- `xhci/scheme.rs::ensure_port_active`
|
||||
- supporting helpers in `xhci/mod.rs`
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- suspend blocks new I/O only after quiesce starts
|
||||
- resume only returns success from a genuinely usable state
|
||||
- PM/detach/configure interleavings are deterministic
|
||||
|
||||
## Phase 6 — Enumerator Cleanup and Timing Hardening
|
||||
|
||||
### Goal
|
||||
|
||||
Remove panic-style and magic-delay behavior from the enumerator path.
|
||||
|
||||
### Work
|
||||
|
||||
- remove panic-class assumptions from `DeviceEnumerator::run`
|
||||
- replace fixed sleeps with bounded readiness checks
|
||||
- make duplicate/out-of-order event handling explicit
|
||||
- align enumerator decisions with the new attach/detach state machine
|
||||
- improve logging for reset/attach/detach milestones
|
||||
|
||||
### Key Targets
|
||||
|
||||
- `xhci/device_enumerator.rs`
|
||||
- supporting interactions in `xhci/mod.rs`
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- no ordinary event path panics
|
||||
- no unnecessary fixed sleep remains
|
||||
- rapid event-order tests pass in QEMU
|
||||
|
||||
## Phase 7 — Final Validation, Docs, and Preservation
|
||||
|
||||
### Goal
|
||||
|
||||
Close the loop with evidence, canonical docs, and durable patch carriers.
|
||||
|
||||
### Work
|
||||
|
||||
- rerun the full bounded proof matrix on a rebuilt image
|
||||
- run source-level verification (`lsp_diagnostics`, `cargo check`, `cargo test`)
|
||||
- update canonical docs:
|
||||
- `local/docs/USB-IMPLEMENTATION-PLAN.md`
|
||||
- `local/docs/USB-VALIDATION-RUNBOOK.md`
|
||||
- immutable archived durable patch carriers under `local/patches/base/`
|
||||
- delete only clearly stale, superseded docs after link sweep
|
||||
|
||||
### Exit Criteria
|
||||
|
||||
- all bounded USB/xHCI proofs pass on a fresh image
|
||||
- changed files are diagnostics-clean
|
||||
- canonical docs match actual proof scope
|
||||
- patch carrier is immutable archived and reapplicable
|
||||
|
||||
## Validation Matrix
|
||||
|
||||
Required final proofs:
|
||||
|
||||
- `bash ./local/scripts/test-xhci-device-lifecycle-qemu.sh --check <tracked-target>`
|
||||
- `bash ./local/scripts/test-usb-qemu.sh --check <tracked-target>`
|
||||
- `bash ./local/scripts/test-xhci-irq-qemu.sh --check`
|
||||
- `bash ./local/scripts/test-usb-maturity-qemu.sh <tracked-target>`
|
||||
|
||||
Required source checks:
|
||||
|
||||
- `lsp_diagnostics` on all changed files
|
||||
- `cargo check` / `cargo test` for `xhcid`
|
||||
- `cargo check` for any touched class daemon or helper crate
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
1. proof/harness expansion
|
||||
2. atomic attach publication
|
||||
3. bounded detach and purge
|
||||
4. configure rollback hardening
|
||||
5. PM sequencing
|
||||
6. enumerator cleanup
|
||||
7. docs, patch preservation, stale-doc cleanup
|
||||
|
||||
## Canonical Doc Authority
|
||||
|
||||
Authoritative docs after cleanup:
|
||||
|
||||
- `local/docs/USB-IMPLEMENTATION-PLAN.md`
|
||||
- `local/docs/USB-VALIDATION-RUNBOOK.md`
|
||||
|
||||
This xhcid plan is a focused implementation document beneath those subsystem-level authorities.
|
||||
|
||||
## Completion Standard
|
||||
|
||||
This work is complete only when:
|
||||
|
||||
- all seven phases are done in order
|
||||
- no changed-file diagnostics remain
|
||||
- `xhcid` builds/tests cleanly
|
||||
- bounded QEMU proof matrix passes on a rebuilt image
|
||||
- canonical docs are synchronized
|
||||
- durable patch carrier is immutable archived
|
||||
- remaining gaps, if any, are explicitly documented as future or hardware-only work
|
||||
@@ -0,0 +1,99 @@
|
||||
# Red Bear OS Repository Governance
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the repository-discipline rules for Red Bear OS so profile work stays
|
||||
reproducible, reviewable, and upstream-friendly.
|
||||
|
||||
## Core Rules
|
||||
|
||||
### 1. Keep Red Bear work isolated
|
||||
|
||||
- Put Red Bear-specific source, recipes, scripts, and docs under `local/` whenever possible.
|
||||
- Prefer patch files and symlinks over direct edits to upstream-managed source trees.
|
||||
- Treat mainline Redox areas as upstream surfaces first, not as the default place for Red Bear
|
||||
customization.
|
||||
|
||||
### 2. Profiles are the support surface
|
||||
|
||||
Tracked Red Bear profiles are:
|
||||
|
||||
- `redbear-mini`
|
||||
- `redbear-full`
|
||||
- `redbear-grub`
|
||||
- `redbear-bluetooth-experimental`
|
||||
- `redbear-wifi-experimental`
|
||||
|
||||
Every user-visible feature should name which profile(s) it belongs to.
|
||||
|
||||
### 3. Validation claims must be explicit
|
||||
|
||||
- `builds` means the package or profile compiles.
|
||||
- `boots` means the image reaches a real bootable system state.
|
||||
- `validated` means behavior has been tested on the claimed profile.
|
||||
- `experimental` means present for bring-up but not support-promised.
|
||||
|
||||
Do not describe compile-only work as supported hardware or a working desktop path.
|
||||
|
||||
### 4. Prefer shared fragments over duplicated profile logic
|
||||
|
||||
- Shared profile file wiring belongs in reusable `config/redbear-*.toml` fragments.
|
||||
- Avoid copy-pasting identical service definitions or file payloads across multiple Red Bear
|
||||
profiles.
|
||||
- Keep profile-specific behavior in the profile file only when the runtime behavior is actually
|
||||
different.
|
||||
|
||||
### 5. Build helpers must match tracked profiles
|
||||
|
||||
If a profile is tracked in git, helper scripts and docs should either support it directly or state
|
||||
why it is intentionally excluded.
|
||||
|
||||
### 6. Resilience policy: local-first package sources
|
||||
|
||||
- Red Bear builds must remain resilient when access to upstream Redox infrastructure is degraded or
|
||||
unavailable.
|
||||
- Local package/source copies are the default operational source of truth for builds.
|
||||
- Upstream fetch/immutable archived is opt-in and must be explicitly requested by the operator (for example via
|
||||
an explicit `--upstream` workflow).
|
||||
- After an explicit upstream immutable archived, local durable release fork (`local/patches`, `local/recipes`) stay
|
||||
authoritative until a conscious reevaluation/promotion decision is made.
|
||||
|
||||
## Profile Intent
|
||||
|
||||
### `redbear-mini`
|
||||
|
||||
Primary validation baseline: console, storage, package flow, and wired networking.
|
||||
|
||||
### `redbear-bluetooth-experimental`
|
||||
|
||||
First bounded Bluetooth validation profile: explicit-startup, USB-attached, BLE-first, and
|
||||
experimental only.
|
||||
|
||||
### `redbear-full`
|
||||
|
||||
Desktop-capable tracked target for the current Red Bear session/network/runtime plumbing surface,
|
||||
including graphics-path bring-up beneath the tracked KWin direction.
|
||||
|
||||
### `redbear-grub`
|
||||
|
||||
Text-only console/recovery target with GRUB boot manager for bare-metal multi-boot workflows.
|
||||
|
||||
### `redbear-wifi-experimental`
|
||||
|
||||
Bounded Intel Wi-Fi validation profile layered on the mini baseline.
|
||||
|
||||
## Change Checklist
|
||||
|
||||
For any substantial Red Bear change, record:
|
||||
|
||||
- objective
|
||||
- profile impact
|
||||
- files touched
|
||||
- validation level (`builds`, `boots`, `validated`, `experimental`)
|
||||
- known limitations
|
||||
|
||||
## Upstream Sync Discipline
|
||||
|
||||
- Rebase/sync through `local/scripts/provision-release.sh`.
|
||||
- Keep Red Bear-specific diffs easy to audit.
|
||||
- Update profile docs when config inheritance or package composition changes.
|
||||
Reference in New Issue
Block a user