# 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 |
|----------------|-------|-------|
| | 935 + 50 progress rows | Comprehensive — 20 drivers, all subsystems |
| | 501 | USB stack — xhcid, usbhubd, usbctl, usbhidd, usbscsid, ucsid |
| | 419 | HID — usbhidd, i2c-hidd, intel-thc-hidd, ps2d, inputd, evdevd, xhcid glue |
| | 1091 | ACPI/PCI/IRQ/IOMMU/boot/init — 8 components, 50+ row coverage matrix |
| | 1559 | Kernel→initfs→init→display→Wayland→KDE chain |
| | 1572 | D-Bus, session, audio, network |
| | 1106 | Config, init.d, recipes, layering |
| | 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).

## Final State (2026-06-10, v6.0-impl2 addendum)

The v6.0-impl2 session continued the desktop path from the build-system and
doc-tree side. It did not change source code; it validated and shipped the
external-patch chain so the build system can actually use the patches.

**libdrm external-patch chain — verified end-to-end:**

- The 5 libdrm patches that v6.0-impl produced (against the now-deleted
  `local/sources/libdrm/` fork) were regenerated as 3 byte-equivalent patches
  against fresh upstream libdrm 2.4.125:
  - `00-xf86drm-redox-header.patch` (186 lines) — creates `xf86drm_redox.h`
  - `01-virtgpu-drm-header.patch` (138 lines) — creates `virtgpu_drm.h`
  - `02-redox-dispatch.patch` (806 lines) — 4 helper functions + 8 `__redox__`
    branches in `xf86drm.c` (5276 → 5869 lines)
- All 3 verified: apply cleanly to fresh upstream, idempotent on rebuild
  (cookbook helper's `git apply --reverse --check` correctly detects
  already-applied), byte-equivalent to old fork
- `local/recipes/libs/libdrm/recipe.toml` had two latent bugs from the v6.0-impl
  Rule 2 migration:
  1. `pkgconf` typo (real recipe is `pkg-config`) — fixed, `repo cook-tree
     libdrm` now resolves deps
  2. `[source].script` no-op — moved to `[build].script` with
     `template = "custom"` so `cookbook_apply_patches` actually runs

**Wayland re-enabling** (per project policy "Enable wayland throughout"):

- 4 KF6 packages flipped from `WITH_WAYLAND=OFF` → `ON`:
  kf6-kio, kf6-kidletime, kf6-kguiaddons, kf6-kwindowsystem
- `local/recipes/libs/libxkbcommon/recipe.toml`:
  `-Denable-wayland=false` → `true`; added `libwayland` + `wayland-protocols`
  to dependencies
- `local/recipes/kde/kf6-kded6/recipe.toml`: removed the binary-rename
  wrapper (`kded6-wrapper.sh`, deleted) and replaced it with a
  `sed`-injected `Environment=QT_QPA_PLATFORM=offscreen` line in the kded6
  systemd service file. This is the canonical Phase E approach recommended in
  `local/docs/WAYLAND-IMPLEMENTATION-PLAN.md`.
- `local/recipes/libs/libdrm/recipe.toml`: `-Dintel=enabled` (Intel GPU
  backend now builds iris + crocus). `recipes/libs/libpciaccess/recipe.toml`
  (libpciaccess 0.19, meson, BLAKE3 `2bd8a8cc...`) created; the dangling
  `recipes/libs/pciaccess-stub` symlink removed.

**Mesa recipe — complete** (build verification pending):

- `recipes/libs/mesa/recipe.toml`: `template = "custom"`, calls
  `cookbook_apply_patches` for `local/patches/mesa/`, sets
  `-Dplatforms=wayland`, `-Degl=enabled`, `-Dgbm=enabled`,
  `-Dgallium-drivers=swrast,virgl,iris,crocus`, and adds
  `-lwayland-client -lwayland-server -lwayland-egl -lwayland-drm` to LDFLAGS.
  Depends on libdrm (with the 3 regenerated patches) + libwayland +
  wayland-protocols.

**Documentation tree cleanup:**

- `local/docs/` trimmed from 45 files (+ 30 archived) to 18 canonical files
  matching the PLANNING NOTES section of `local/AGENTS.md`
- 65 files deleted (stale assessments, superseded plans, empty stubs, the
  entire `local/docs/archived/` folder, the 4 historical `docs/0*-*.md`
  files, and `local/recipes/qt/qtbase/recipe.toml.bak`)
- 4 files restored from `archived/` to `local/docs/` (canonical per
  `local/AGENTS.md` PLANNING NOTES)
- 22 unique broken cross-references fixed across 9 canonical docs
- `docs/README.md` fully rewritten as a clean canonical index;
  `docs/AGENTS.md` reduced to the 3-doc canonical structure
- Net: −31,315 lines

**Next concrete step for v6.0-impl3:**

`repo cook mesa` end-to-end. All recipe + patch work is done; the build
verification is the next invocation. The plan's Phase 3 (Mesa EGL Wayland) is
recipe-complete; the next milestone is the cook itself.

---

## 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 (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-impl3, 2026-06-10. 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. v6.0-impl2 updates: the 5 libdrm patches (generated against the deleted fork) were regenerated as 3 byte-equivalent patches against fresh upstream libdrm 2.4.125; the `pkgconf` typo in `local/recipes/libs/libdrm/recipe.toml` was fixed; the recipe's broken `[source].script` no-op was moved to `[build].script` with `template = "custom"` so `cookbook_apply_patches` actually runs. Wayland re-enabling: 4 KF6 packages flipped to `WITH_WAYLAND=ON`, libxkbcommon flipped to `-Denable-wayland=true`, kded6 wrapper replaced with `Environment=QT_QPA_PLATFORM=offscreen` in the systemd service file. Doc tree trimmed from 75 files to 18 canonical in `local/docs/`. redbear-compositor extended with `zwp_linux_explicit_synchronization_v1` (Phase 3.4, no-tearing) and `wp_presentation` (Phase 3.3, vblank timing) — 3 files (+349/-10), 2 new integration tests pass. v6.0-impl3 update: attempted `repo cook mesa` end-to-end. Found and fixed 2 recipe `rev` mismatches (ninja-build, sddm). Discovered that the relibc-install cross-compile toolchain prefix is stale (pre-dates the `utimensat` commit) and that the relibc P3-*.patch carriers in `recipes/core/relibc/` are broken symlinks to a deleted `local/patches/relibc/` directory. Per the user's "relibc is our internal project. We work on it directly without patches" policy, added `getloadavg` directly to the relibc source as a Rule 1 in-tree fork (not a patch), deleted the 33 broken P3-*.patch symlinks, and refreshed the relibc-install prefix with the fresh libc. Mesa build now blocked by libpciaccess 0.19 which has no Redox backend (upstream `#error "Unsupported OS"`).

v6.0-impl12 update (2026-06-11): **Mesa 24.0 BUILT successfully on x86_64-unknown-redox.** The `mesa.pkgar` artifact (169 MB) is in `repo/x86_64-unknown-redox/` with `libEGL.so.1.0.0`, `libgbm.so.1.0.0`, `libGLESv2.so.2.0.0`, `libGLESv1_CM.so.1.1.0`, `libOSMesa.so.8.0.0` all present. This is the gate the entire desktop path has been waiting for. Three mesa patches added in `local/patches/mesa/`:
- `04-sys-ioccom-stub-header.patch` — provides a minimal Linux UAPI `sys/ioccom.h` in mesa's include tree (relibc doesn't ship one; the macros are pure compile-time encodings; runtime dispatch goes through libdrm's `drmIoctl` shim → `scheme:drm/`).
- `05-vk-sync-wchar-include.patch` — adds `<wchar.h>` to `src/vulkan/runtime/vk_sync.h` so the `wchar_t` in win32 sync function pointer types resolves. relibc's `<vulkan/vulkan_core.h>` chain doesn't transitively pull `<wchar.h>` like glibc does.

Mesa recipe fix in `recipes/libs/mesa/recipe.toml`: dropped the stale `-lwayland-drm` from LDFLAGS. Per upstream libwayland 1.24, the standalone `libwayland-drm.so` was removed from the project in 2018 and merged into Mesa as a bundled static `libwayland_drm` library (see `src/egl/wayland/wayland-drm/meson.build` lines 23-50 and `src/egl/meson.build:132` `link_for_egl += libwayland_drm`). The `-lwayland-drm` was a stale flag from a non-Redox mesa recipe.

libwayland recipe change in `local/recipes/wayland/libwayland/recipe.toml`: the recipe uses `-Dscanner=false` (necessary because the Redox-target scanner binary has `/lib/ld64.so.1` as its ELF interpreter and can't be exec'd on the build host), which means libwayland doesn't install `wayland-scanner.pc`. Mesa's `meson.build:1995` does `dependency('wayland-scanner', native: true)` and needs a host-runnable path. The recipe now stages a `wayland-scanner.pc` that points to `/usr/bin/wayland-scanner` (the host binary), plus a symlink in `usr/bin/wayland-scanner` so the cookbook auto-extract populates mesa's sysroot.

Cumulative across v6.0-impl5/6/7/8/9/10/11/12:
- 9 cookbook + recipe files changed
- 2 vendored gnu-config files
- 8 durable build artifacts now in repo: `pkg-config`, `libdrm`, `libgmp`, `gcc13` (131 MB) + `gcc13.cxx` (42 MB), `libpciaccess`, `wayland-protocols`, **and `mesa` (169 MB)**
- 2 new mesa external patches (Rule 2) for sys/ioccom and wchar_t
- 1 in-tree fork source committed (libpciaccess, Rule 1)
- All changes staged, none committed (per "do not commit" instruction)

Phase 3 of the v6.0 console-to-KDE plan is **COMPLETE** (recipe + build verification). The desktop path can now proceed to the Qt6 → KF6 → KWin → SDDM chain.