RedBear-OS/local/docs/STUBS-FIX-PROGRESS.md

# Stubs Fix Progress — Red Bear OS

**Tracking document for the v6.0 stubs → real code rewrite work.**

**Started:** 2026-06-09
**Driver:** Red Bear OS Build System
**Reference Kernel:** `local/reference/linux-7.1/` (READ-ONLY)
**Project Policies:** zero tolerance for stubs, no `unimplemented!()` / `todo!()` in non-test code, no workarounds, real implementations only.

---

## Overview

The four audit documents identified ~517 TODO/FIXME markers, 11 `unimplemented!()` calls, and 7 missing protocol implementations across the low-level driver stack. This document tracks the work to fix all of them.

| Audit Document | Lines | Scope |
|----------------|-------|-------|
| `local/docs/STUBS-AUDIT-AND-REWRITE-PLAN.md` | 935 + 50 progress rows | Comprehensive — 20 drivers, all subsystems |
| `local/docs/USB-STUBS-AUDIT.md` | 501 | USB stack — xhcid, usbhubd, usbctl, usbhidd, usbscsid, ucsid |
| `local/docs/HID-STUBS-AUDIT.md` | 419 | HID — usbhidd, i2c-hidd, intel-thc-hidd, ps2d, inputd, evdevd, xhcid glue |
| `local/docs/LOWLEVEL-STUBS-AUDIT.md` | 1091 | ACPI/PCI/IRQ/IOMMU/boot/init — 8 components, 50+ row coverage matrix |
| `local/docs/BOOT-AND-HW-ENABLEMENT-ASSESSMENT.md` | 1559 | Kernel→initfs→init→display→Wayland→KDE chain |
| `local/docs/DESKTOP-SERVICES-ASSESSMENT.md` | 1572 | D-Bus, session, audio, network |
| `local/docs/CONFIG-AND-INIT-ASSESSMENT.md` | 1106 | Config, init.d, recipes, layering |
| `local/docs/GPU-MESA-KDE-CHAIN-ASSESSMENT.md` | 1379 | Mesa → libdrm → redox-drm → Qt6 → KF6 → KWin → SDDM |

---

## Red Bear source forks and patches

Per `local/AGENTS.md` "NO OVERLAY-STYLE PATCHES — SCOPED POLICY (AMENDED 2026)" two-rule model:

- **Rule 1 (in-tree Red Bear components)** — direct edits in `local/sources/<component>/` and `local/recipes/<category>/<name>/recipe.toml`. No fork. No patches.
- **Rule 2 (big external projects)** — Red Bear edits live as external patches in `local/patches/<component>/*.patch`, applied on top of upstream git/tar source by `cookbook_apply_patches` at build time.

| Component | Storage | Initial commit | Rationale |
|---|---|---|---|
| `base` | `local/sources/base/` | (pre-existing) | Userspace drivers (acpid, pcid, xhcid, etc.) — Rule 1 |
| `bootloader` | `local/sources/bootloader/` | (pre-existing) | UEFI bootloader — Rule 1 |
| `installer` | `local/sources/installer/` | (pre-existing) | ext4 + GRUB installer — Rule 1 |
| `kernel` | `local/sources/kernel/` | (pre-existing) | Microkernel — Rule 1 |
| `redox-drm` | `local/sources/redox-drm/` | `bd787d3` + Gap 3/5/8 fixes | DRM/KMS scheme daemon — Rule 1 (Red Bear-internal) |
| `redoxfs` | `local/sources/redoxfs/` | (pre-existing) | RedoxFS — Rule 1 |
| `relibc` | `local/sources/relibc/` | (pre-existing) | C library — Rule 1 |
| `userutils` | `local/sources/userutils/` | (pre-existing) | User utilities — Rule 1 |
| `libdrm` | `local/patches/libdrm/*.patch` | `5f5eec1c4` | DRM/KMS userspace library — Rule 2 (external patches) |
| `mesa` | `local/patches/mesa/*.patch` | `bfbf128d5` | Mesa 3D graphics library — Rule 2 (external patches) |
| `pipewire` | `local/patches/pipewire/*.patch` | `8ff9da2ff` | PipeWire audio server — Rule 2 (external patches) |
| `wireplumber` | `local/patches/wireplumber/*.patch` | `722f0c452` | WirePlumber session manager — Rule 2 (external patches) |

## Final State (2026-06-09, end of session)

**`cargo check` status:** 17+ modified base packages compile cleanly with 0 errors (xhcid, pcid, acpid, intel-thc-hidd, e1000d, usbscsid, nvmed, ps2d, inputd, i2c-hidd, usbhidd, ixgbed, rtl8168d, virtio-netd, common, init, vesad).
**`cargo test` status:** 9 ps2d unit tests pass; 43 redbear-hid-core unit tests pass.

**QEMU boot validation:**
- `local/scripts/test-redbear-full-qemu.sh` (297 lines, executable) — comprehensive QEMU boot test launcher
- 3 boot logs captured: `redbear-full-boot-20260609-125114.log` (75s, 96 lines), `redbear-full-boot-20260609-150550.log` (300s, 204 lines), `redbear-full-boot-post-virtio-blkd-fix-20260609-181340.log` (post-fix)
- 2 analysis docs: `REDBEAR-FULL-BOOT-RESULTS.md`, `REDBEAR-FULL-BOOT-EXTENDED-RESULTS.md`, `REDBEAR-FULL-BOOT-POST-VIRTIO-BLKD-FIX-RESULTS.md`
- **Reached in 300s capture**: PCI enumeration, pcid-spawner, nvmed (multi-queue), virtio-blkd, ahcid
- **Real bug found and fixed**: `virtio-blkd` panicked on `assert_eq!(*status, 0)` when boot drive is read-only (commit `cffacf59`)
- **Did NOT reach**: D-Bus, KWin, SDDM, login prompt (would need redbear-full ISO + further fixes)

**Gitea branches:** All work on `0.2.3` (no local-only branches).

---

## P1: Phase 1 Unblockers — ✅ DONE (5/5)

| Fix | Commit | Description |
|-----|--------|--------------|
| xhcid MSI-X | `eb59807b` | Enable MSI-X interrupts, remove polling fallback |
| xhci event ring growth | (in `c25c7e74` inputd commit + later) | Implement real `grow_event_ring()` |
| PCI multi-bus | `270a27a3` | Full MCFG parsing, recursive PCI-PCI bridge |
| ACPI GPE | `fa204528` | FADT GPE base parsing, SCI handler, AML method dispatch |
| ACPI Notify | `da327cae` | Notify opcode in AML interpreter dispatches to device's _LNN/_ENN |

## P2: Phase 2-3 Fixes — ✅ DONE (5/5)

| Fix | Commit | Description |
|-----|--------|--------------|
| intel-thc-hidd HID | `98d7ecb4` | Real HID report thread replaces sleep loop |
| PS/2 sets 2/3 + Intellimouse2 | `e34c6184` | Adds scancode set 2/3, 4-byte mouse packets |
| usbscsid UAS | `c131fb13` | Replaces empty uas mod with real UasProtocol |
| NVMe multi-queue | `4b0db467` | Per-CPU I/O queues with MSI-X |
| e1000d stats | `494b671c` | Read+clear cycle for GORC/GOTCL/etc. |

## P3: Architectural Refactor — ✅ DONE (4/4)

| Fix | Commit | Description |
|-----|--------|--------------|
| redbear-hid-core | `7b82f4d` (new crate) | 2664 LoC, 43 unit tests, descriptor parser, usage mapper, quirks |
| usbhidd wiring | `e1f9b2a2` | Wire usbhidd to use redbear-hid-core |
| i2c-hidd wiring | `d7284b50` | Wire i2c-hidd to use redbear-hid-core (preserves boot fallback) |
| intel-thc-hidd wiring | (no separate commit — was already done in P2) | HID decoding path already used redbear-hid-core |

## P4: Driver Wiring — ✅ DONE (4/4)

| Fix | Commit | Description |
|-----|--------|--------------|
| usbhidd wire to runtime | `f6b5d759` | Wire descriptor parsing, set_protocol/get_protocol/set_report/get_idle |
| intel-thc-hidd wire | (already done) | decode path is called |
| i2c-hidd wire | (already done) | descriptor parsing and translation |
| usbscsid wire UAS | `bebfe9ad` | UAS dispatch, protocol constants |
| nvmed wire | `78ad2539` | per-queue submission, MSI-X, queue count selection |
| acpid wire | `720870d4`, `9894ed7b` | EC burst, EC constants, thermal accessors, TOML loaders |

## P5: Phase 1 Implementation Work — ✅ DONE

| Fix | Commit | Description |
|-----|--------|--------------|
| Move libxkbcommon + xkeyboard-config | (main repo commits) | Now in local/recipes/, in redbear-full.toml |
| Replace 5 *-stub recipes | `8c35e8b4b`, `a6ad6b0a8`, `c8aa0d37d`, `0e3cbbd2d`, `77bd48332` | libepoxy, libxcvt, libdisplay-info, lcms2, libudev all real |
| Fix dual pcid-spawner | `c975cfb1` | init.d requires_weak switched to driver-manager |
| Fix vesad handoff | `048b7000` | Real `display.vesa → drm/card0` handoff |
| Fix pcid todo!() | `17b6ec76` | Real PCI config fallback + DMI device matching |
| Implement init expect(TODO) | `0df7977d` | Real getns/register_scheme + auto-restart + poweroff/reboot |
| Enable all 12 KWin features | `82acea3c8` | All KWin features enabled |
| Replace 4 SDDM TODO:IMPLEMENT | (in main repo) | Real session/auth/VT/display logic |
| Port minimal PAM | `67c59641f` | pam-redbear proxies to redbear-authd |
| Implement real sessiond | `385f32704` | kill_session, kill_user, power_off, reboot |
| Add 7 KDE D-Bus services | `3ce812bef` | All D-Bus session service files in build |
| Drop *-stub references | `a63762b08` | redbear-full.toml clean |
| Generate /etc/machine-id | `917baf7ef` | Built at compile time, no runtime generation |
| Remove firmware upstream pull | `106f1fc32` | Manual archive reference, no silent wget |
| Implement UPower + UDisks2 | `a9fa0310a` | Real D-Bus interfaces |
| Wire notifications+statusnotifier | (in main repo) | service files added to redbear-full.toml |
| Replace wifictl StubBackend | `a68b49569` | Real iwlwifi/netstack backend |
| Add pipewire + wireplumber | `4c2402af7`, `9dfe7ce03` | recipes + D-Bus activation in config |

## P6: GPU/Mesa/KDE Build Chain — assessment complete (8 chains identified)

The GPU/MESA/KDE assessment document is at `local/docs/GPU-MESA-KDE-CHAIN-ASSESSMENT.md` (note: file write tool failed during one of the agent runs; the comprehensive content is preserved in the model context and was provided as an assistant message. The file may need to be re-written by a subsequent session using heredoc.)

The assessment identified 9 hard build-chain breaks and 16+ stubs in the Mesa/KDE path. Top priorities:
- libdrm patches missing
- mesa missing radeonsi
- KWin: 7 of 12 features disabled (now all enabled by `82acea3c8`)
- SDDM: Qt version mismatch
- QML gate (kirigami QML_OFF_OFF_OFF_OFF_OFF_OFF no-ops)
- redbear-compositor is a bounded scaffold missing xdg-shell, xdg-output, etc.

---

## P1: Phase 1 Unblockers (Boot, ACPI, IRQ, USB) — ✅ DONE

The audit identified that the current xhcid driver hardcodes `(None, InterruptMethod::Polling)` at `main.rs:181`, xhci's event ring growth is a stub at `irq_reactor.rs:535-538`, pcid's MCFG parsing only handles the first host bridge at `main.rs:299`, and acpid lacks GPE and Notify handling. None of these are blocking a QEMU boot, but all of them are required for real-hardware validation and for stable USB HID + storage on real silicon.

### Fix 1.1: xhcid MSI-X interrupts — ✅ DONE
- **Commit:** `eb59807b` (xhcid: enable MSI-X interrupts; remove polling fallback)
- **Status:** Implemented `get_int_method()` and wired into the Xhci struct
- **Verification:** `cargo check -p xhcid` clean

### Fix 1.2: xhci event ring growth — ✅ DONE
- **Status:** Real `grow_event_ring()` implementation replaces the stub
- **Verification:** `cargo check -p xhcid` clean

### Fix 1.3: PCI multi-bus enumeration — ✅ DONE
- **Commit:** `270a27a3` (pcid: implement multi-bus PCI enumeration from MCFG)
- **Status:** Full MCFG parsing, multi-bus enumeration, recursive PCI-PCI bridge discovery
- **Verification:** `cargo check -p pcid` clean

### Fix 1.4: ACPI GPE handling — ✅ DONE
- **Commit:** `fa204528` (acpid: implement GPE handling (SCI dispatch + AML method invocation))
- **Status:** FADT GPE base parsing, SCI handler, AML method dispatch per GPE bit
- **Verification:** `cargo check -p acpid` clean

### Fix 1.5: ACPI Notify handling — ✅ DONE
- **Commit:** `da327cae` (acpid: implement AML Notify handling for device-specific event dispatch)
- **Status:** Notify opcode in AML interpreter dispatches to device's _LNN/_ENN method
- **Verification:** `cargo check -p acpid` clean

---

## P2: Phase 2-3 Fixes (Storage, Network, HID) — ✅ DONE

The audit identified 5 medium-priority fixes that unblock Phase 2 (DRM/KMS) and Phase 3 (KDE Plasma Wayland).

### Fix 2.1: intel-thc-hidd HID report decoding — ✅ DONE
- **Commit:** `98d7ecb4` (intel-thc-hidd: implement HID report decoding + evdev translation)
- **Status:** Replaces `loop { sleep(5s) }` with real HID report thread, parses descriptors, translates to evdev
- **Verification:** `cargo check -p intel-thc-hidd` clean

### Fix 2.2: PS/2 scancode sets 2/3 + Intellimouse2 — ✅ DONE
- **Commit:** `e34c6184` (ps2d: implement scancode sets 2/3 and Intellimouse2 protocol)
- **Status:** Adds scancode set 2 and 3 mappers, extended keys, Intellimouse2 4-byte packet handling
- **Verification:** `cargo test -p ps2d --lib` returns **9 passed** (3 original + 6 new)

### Fix 2.3: USB Attached SCSI (UAS) — ✅ DONE
- **Commit:** `c131fb13` (usbscsid: implement USB Attached SCSI (UAS) protocol)
- **Status:** Replaces empty `mod uas { // TODO }` with real UasProtocol: 4-stream setup, IU send/receive, sense data
- **Verification:** `cargo check -p usbscsid` clean

### Fix 2.4: NVMe multi-queue — ✅ DONE
- **Commit:** `4b0db467` (nvmed: implement multi-queue I/O with MSI-X)
- **Status:** Reads "Number of Queues" feature, allocates per-CPU I/O queues, MSI-X per queue, per-queue completion
- **Verification:** `cargo check -p nvmed` clean

### Fix 2.5: e1000d statistical counters — ✅ DONE
- **Commit:** `494b671c` (e1000d: implement statistical counter clearing)
- **Status:** Reads GORC/GOTCL/GOTCH/TOTL/TOTH/TPR/TPT/BPRC/MPRC with read-then-clear sequence
- **Verification:** `cargo check -p e1000d` clean

---

## P3: Architectural Refactor (HID Core Extraction) — ✅ CRATE DONE, DRIVER INTEGRATION QUEUED

The audit identified that the three HID drivers (usbhidd, i2c-hidd, intel-thc-hidd) all duplicate HID report parsing and usage-to-evdev mapping. A shared `redbear-hid-core` crate will replace this with a single canonical implementation.

### Fix 3.1: redbear-hid-core crate — ✅ DONE
- **New crate:** `local/recipes/drivers/redbear-hid-core/`
- **Commit:** `7b82f4d` (redbear-hid-core: initial implementation)
- **Code:** 2664 LoC across 8 source files
- **Tests:** 43 unit tests, all passing
- **Modules:**
  - `descriptor.rs` (428 LoC) — HID Report Descriptor parser
  - `item.rs` (328 LoC) — HID Item parser (Main/Global/Local)
  - `usage_table.rs` (351 LoC) — usage page → evdev code mapping
  - `translate.rs` (206 LoC) — HID Report → evdev events
  - `quirks.rs` (978 LoC) — HID quirk table
  - `report.rs` (126 LoC) — parsed HID Report
  - `test_fixtures.rs` (225 LoC) — synthetic Report Descriptors for tests
  - `lib.rs` (22 LoC) — re-exports
- **Usage pages covered:**
  - 0x01 Generic Desktop (Pointer, Mouse, Keyboard, X, Y, Wheel)
  - 0x07 Keyboard/Keypad (all 0x00-0xE7 mapped to KEY_*)
  - 0x09 Button (BTN_MOUSE / BTN_LEFT-RIGHT)
  - 0x0C Consumer (Volume, Play/Pause)
  - 0x0D Digitizer (Touchscreen, Touchpad)
  - 0x01 Game Controller (X, Y, Z, Rx, Ry, Rz, Hat Switch)
- **Quirks supported:** Invert, Notouch, MultiInput, SkipOutput, NoEmpty

### Fix 3.2: usbhidd → redbear-hid-core — QUEUED
- **Target:** `local/sources/base/drivers/input/usbhidd/`
- **Work:**
  - Replace hardcoded KEY_* array with dynamic Report Descriptor parsing via redbear-hid-core
  - Wire usage → evdev translation through the new crate

### Fix 3.3: i2c-hidd → redbear-hid-core — QUEUED
- **Target:** `local/sources/base/drivers/input/i2c-hidd/`
- **Work:**
  - Replace boot-protocol-only code with full Report Protocol parsing
  - Wire usage → evdev translation through the new crate

### Fix 3.4: intel-thc-hidd → redbear-hid-core — QUEUED
- **Target:** `local/sources/base/drivers/input/intel-thc-hidd/`
- **Work:**
  - Wire HID report decoding through the new crate
  - (Depends on Fix 2.1 which is DONE)

---

## P4: Network Driver Hardening

The audit identified gaps in MSI-X support, PHY handling, and modern virtio-net features.

### Fix 4.1: ixgbed MSI-X
- **Target:** `local/sources/base/drivers/net/ixgbed/`
- **Work:**
  - Enable MSI-X for the queue pairs
  - Set up per-queue interrupts

### Fix 4.2: RTL8168 PHY
- **Target:** `local/sources/base/drivers/net/rtl8168d/`
- **Work:**
  - PHY link state detection
  - Auto-negotiation
  - Speed/duplex configuration

### Fix 4.3: virtio-net control queue
- **Target:** `local/sources/base/drivers/net/virtio-netd/`
- **Work:**
  - Use the control virtqueue for MAC address setting
  - Implement the modern virtio-net 1.1 control queue

### Fix 4.4: RTL8139 PHY
- **Target:** `local/sources/base/drivers/net/rtl8139d/`
- **Work:**
  - PHY link state detection
  - Auto-negotiation

---

## P5: ACPI Completeness

The audit identified missing ACPI features: Embedded Controller, Thermal, Battery, Wake.

### Fix 5.1: ACPI Embedded Controller
- **Target:** `local/sources/base/drivers/acpid/ec.rs`
- **Work:**
  - EC transactions (read/write/query)
  - EC interrupts (SCI on EC events)
  - Used by many laptops for fan control, hotkeys, etc.

### Fix 5.2: ACPI Thermal
- **Target:** `local/sources/base/drivers/acpid/`
- **Work:**
  - Parse \_TZ (thermal zone) objects
  - Read \_TMP, \_TC1, \_TC2, \_TSP, \_PSV, \_CRT
  - Notify on critical temperature

### Fix 5.3: ACPI Battery
- **Target:** `local/sources/base/drivers/acpid/`
- **Work:**
  - Parse battery device (PNP0C0A)
  - Read \_BST (Battery Status) and \_BIF (Battery Information)
  - Notify on status change

### Fix 5.4: ACPI Wake
- **Target:** `local/sources/base/drivers/acpid/`
- **Work:**
  - Parse \_PRW (Power Resources for Wake)
  - Implement S1, S3 (suspend to RAM) transitions
  - Resume from S3 on wake event

---

## P6: Storage Driver Hardening (not started)

### Fix 6.1: AHCI NCQ
- **Target:** `local/sources/base/drivers/storage/ahcid/`
- **Work:**
  - Native Command Queuing for SATA SSDs
  - Read LOG_PAGE_LOG_DIRECTORY for drive capabilities

### Fix 6.2: NVMe TRIM/DISCARD
- **Target:** `local/sources/base/drivers/storage/nvmed/`
- **Work:**
  - Implement Dataset Management command for SSD TRIM

---

## P7: Audio Driver Hardening (not started)

### Fix 7.1: AC'97 full duplex
- **Target:** `local/sources/base/drivers/audio/ac97d/`
- **Work:**
  - PCM capture (record) in addition to playback
  - Mixer controls

### Fix 7.2: Intel HDA codec
- **Target:** `local/sources/base/drivers/audio/ihdad/`
- **Work:**
  - Full codec initialization
  - HDMI/DP audio support
  - Multiple streams per codec

---

## P8: Graphics Driver Hardening (not started)

### Fix 8.1: Intel iHD real implementation
- **Target:** `local/sources/base/drivers/graphics/ihdgd/`
- **Work:**
  - Use linux-kpi for full i915 compat
  - Real connector enumeration
  - Atomic modeset
  - GPU command submission

### Fix 8.2: virtio-gpu virgl
- **Target:** `local/sources/base/drivers/graphics/virtio-gpud/`
- **Work:**
  - 3D resource creation via virgl
  - Mature 3D support for QEMU

---

## Risk Assessment

What's the impact of shipping as-is?
- QEMU works (poll-mode USB, single-queue NVMe, no multi-touch)
- Real hardware has degraded USB, no touchpad (intel-thc-hidd stub), no power button, no lid switch, no thermal protection

What's the minimum to ship Red Bear OS 0.3.0?
- P1: xhcid MSI-X, xhci event ring growth, PCI multi-bus
- P2: intel-thc-hidd HID, PS/2 set 2/3, NVMe multi-queue
- P3: redbear-hid-core

What's the minimum to ship Red Bear OS 0.4.0 (KDE Plasma Wayland)?
- All of P1, P2, P3
- P4: ixgbed MSI-X, RTL8168 PHY
- P5: ACPI thermal (for laptop safety)

What's the minimum to ship Red Bear OS 0.5.0 (real-hardware KDE)?
- All of P1, P2, P3, P4
- P5: full ACPI completeness
- P6: AHCI NCQ, NVMe TRIM

---

## Verification Strategy

For each fix:
1. `cargo check -p <package>` returns 0 errors
2. (If applicable) `cargo test -p <package>` returns all tests passed
3. (If applicable) QEMU bare-metal boot
4. (If applicable) Real-hardware smoke test

Cross-cutting:
- `cargo check --workspace` clean across all of `local/sources/base/`
- `cargo check --workspace` clean across all of `local/recipes/`
- All four audit documents are updated to mark the fixed items

---

## Open Questions

1. **MSI-X vector cap**: should we cap at 32, 64, or 128? Modern xHCI supports up to 1024 vectors.
2. **Event ring max size**: 4096 TRBs? 8192? More?
3. **NVMe queue count**: cap at 64, 128, or 256?
4. **redbear-hid-core license**: MIT, Apache-2.0, or dual-licensed? Project preference is MIT.
5. **HID quirks table**: how many quirks to include initially? 50? 100? 500?
6. **ps2d set 3 priority**: is it actually used by any current hardware?

---

**Document version:** v6.0, end-of-session 2026-06-09. Mesa, libdrm, PipeWire, WirePlumber Red Bear source forks were migrated to external patches (Rule 2) in June 2026; see `local/AGENTS.md` for the current policy.