Add low-level infrastructure reassessment and updated plan v1.0

2026-05-21 05:36:35 +03:00
parent 5715f86dc6
commit 7e21799845
1 changed files with 692 additions and 0 deletions
@@ -0,0 +1,692 @@
+# Red Bear OS — Low-Level Infrastructure Reassessment & Updated Plan
+
+**Version**: 1.0 (2026-05-21)
+**Supersedes**: Fragmentary assessments in `COMPREHENSIVE-SYSTEM-ASSESSMENT-AND-IMPROVEMENT-PLAN.md` §2–§4 for ACPI/IRQ/PCI/driver topics
+**Canonical adjacent plans** (remain authoritative for subsystem detail):
+- `ACPI-IMPROVEMENT-PLAN.md` — ACPI waves W0–W7
+- `IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — PCI/IRQ/MSI-X waves W1–W6
+- `BOOT-PROCESS-HARDWARE-DETECTION-PLAN.md` — Boot detection waves W0–W6
+- `SMP-SCHEDULER-IMPROVEMENT-PLAN.md` — SMP bottlenecks B1–B7
+
+---
+
+## 1. Executive Summary
+
+This document is a **code-grounded reassessment** of four interdependent low-level subsystems: ACPI/acpid, IRQ/PCI, enumeration/driver binding, and driver infrastructure. It is based on direct source inspection (file paths and line numbers provided throughout), cross-referenced against existing plans.
+
+### Bottom-line verdict
+
+| Subsystem | Verdict | Blocking Bare Metal? |
+|-----------|---------|---------------------|
+| **ACPI boot** | Boot-baseline complete, not release-grade | Partial — shutdown timing fragile |
+| **ACPI shutdown** | S5 derivation works, timing-dependent on PCI | Yes — pre-PCI shutdown degrades weakly |
+| **ACPI thermal/fan** | Discovery exists, no runtime backend | No — thermal safety gap |
+| **ACPI C-states** | Discovery exists, **no kernel cpuidle** | **Yes** — root cause of heat |
+| **IRQ delivery** | Architecturally strong, QEMU-proven only | Partial — no HW validation |
+| **MSI/MSI-X** | Code complete, **IOMMU validation stubbed** | **Yes** — `iommu_validate_msi_irq()` returns `true` |
+| **PCI enumeration** | Userspace-only (correct), pcid complete | No |
+| **Driver binding** | Manual class-code matching, no ACPI _HID/_CID | Partial — limited device coverage |
+| **redox-driver-sys** | Production quality, zero stubs | No |
+| **linux-kpi** | Structurally complete for GPU+Wi-Fi | No |
+| **GPU drivers** | Compile-only, synthetic EDID everywhere | **Yes** — no real display detection |
+| **Wi-Fi** | Compile+host-test only | Yes — no HW validation |
+| **USB** | xhcid only, no EHCI/UHCI/OHCI | **Yes** — legacy USB keyboards unreachable |
+
+### What changed since last assessment (2026-05-20)
+
+1. **Critical stub discovered**: `iommu_validate_msi_irq()` at `kernel/src/scheme/irq.rs:231` unconditionally returns `true` — this was not flagged as a blocking item in the IRQ enhancement plan (all 6 waves marked "complete").
+2. **Critical stub discovered**: `aml_physmem.rs:195` and `:274` fabricate zero values on physical memory access failure — affects all AML runtime evaluation.
+3. **Dual AML interpreter architecture** identified as a maintenance risk — kernel `acpi_ext` crate and userspace `acpi` crate parse DSDT/SSDT independently.
+4. **APIC timer disabled** (`local_apic.rs:81`) — not flagged in any existing plan as a blocker.
+5. **Synthetic EDID used in all GPU drivers** — blocks real display detection on bare metal.
+6. **40 total TODOs** in ACPI code (16 kernel + 24 userspace) — higher than previously documented.
+
+---
+
+## 2. ACPI / acpid Reassessment
+
+### 2.1 Architecture
+
+The ACPI subsystem has **three operational levels**:
+
+```
+Bootloader → KernelArgs.hwdesc_base (RSDP pointer)
+    │
+    ▼
+Kernel ACPI (src/acpi/ + src/scheme/acpi.rs + src/arch/x86_shared/sleep.rs)
+    ├── RSDP→RSDT/XSDT→SDT enumeration (MADT, SRAT, SLIT, HPET)
+    ├── Export via /scheme/kernel.acpi/{rxsdt, kstop, sleep}
+    └── Kernel-side AML interpreter (acpi_ext crate) for S3/S5 sleep
+    │
+    ▼
+Userspace acpid (drivers/acpid/src/)
+    ├── Reads rxsdt, loads SDTs from physical memory
+    ├── Userspace AML interpreter (acpi crate) — SEPARATE from kernel's
+    ├── Exports /scheme/acpi/{dmi, tables, symbols, thermal, fan, cstates}
+    └── Shutdown via kstop pipe + PM1a/PM1b write
+```
+
+### 2.2 What Is Working
+
+| Component | File | Evidence |
+|-----------|------|----------|
+| RSDP discovery + dual checksum | `acpi/rsdp.rs` | ACPI 1.0 + 2.0+ validation, 62 lines |
+| MADT parsing (10 entry types) | `acpi/madt/mod.rs` | Types 0x0–0xA + aarch64 GICC/GICD, 340 lines |
+| x2APIC support | `acpi/madt/mod.rs` | Types 0x9/0xA, `P20–P22` patches |
+| IOAPIC init from MADT | `device/ioapic.rs` | GSI resolution, source overrides, affinity, 502 lines |
+| LAPIC/x2APIC | `device/local_apic.rs` | MSR + MMIO dual path, 312 lines |
+| SRAT/SLIT NUMA | `acpi/srat.rs`, `acpi/slit.rs` | Affinity + distance matrix |
+| HPET timer | `acpi/hpet.rs` | Init from ACPI tables |
+| Kernel scheme export | `scheme/acpi.rs` | rxsdt, kstop, sleep — 398 lines |
+| acpid SDT loading | `acpid/src/acpi.rs:162–217` | Page-span handling, PhysmapGuard |
+| acpid FADT parsing | `acpid/src/acpi.rs:965–1122` | ACPI 2.0 extended fields |
+| acpid EC handler | `acpid/src/ec.rs` | Full protocol (RD_EC/WR_EC/BE_EC/BD_EC/QR_EC), 317 lines |
+| acpid S5 derivation | `acpid/src/acpi.rs:754–813` | FADT + AML \__S5, cached |
+| acpid DMI | `acpid/src/dmi.rs` | SMBIOS 32/64-bit entry points, 350 lines |
+| acpid thermal/fan/cstate discovery | `thermal.rs`, `fan.rs`, `cstate.rs` | AML-backed \__TZ, \__PR namespace |
+| hwd ACPI backend | `hwd/backend/acpi.rs` | \__CID/\__HID device discovery, 119 lines |
+
+### 2.3 Critical Stubs
+
+| Location | Line | Issue | Severity |
+|----------|------|-------|----------|
+| `acpid/src/aml_physmem.rs` | 195 | `read_phys_or_fault()` returns `T::zero()` on failure — **fabricates data** | 🔴 CRITICAL |
+| `acpid/src/aml_physmem.rs` | 274 | `map_physical_region()` falls back to **zero page** on failure — writes lost | 🔴 CRITICAL |
+| `kernel/src/arch/x86_shared/sleep.rs` | 257–276 | `read_pci_u8/u16/u32` always return **0**; `write_pci_*` are no-ops | 🔴 CRITICAL |
+| `kernel/src/arch/x86_shared/sleep.rs` | 275 | `nanos_since_boot()` returns **0** — broken AML timing | 🟠 HIGH |
+| `kernel/src/arch/x86_shared/sleep.rs` | 294–298 | `acquire()`/`release()` for AML mutexes are **no-ops** | 🟠 HIGH |
+| `acpid/src/acpi.rs` | 545 | `Dmar::init(&this)` **commented out** — "TODO (hangs on real hardware)" | 🟠 HIGH |
+| `hwd/backend/legacy.rs` | 13 | `LegacyBackend::probe()` is a **TODO no-op** | 🟠 HIGH |
+| `acpid/src/acpi.rs` | 820–822 | `set_global_s_state(state)` returns `Ok` for any state != 5 | 🟡 MEDIUM |
+
+### 2.4 Architectural Risks
+
+1. **Dual AML interpreters**: Kernel `sleep.rs` uses `acpi_ext` crate; userspace `acpid` uses `acpi` crate. They parse the same DSDT/SSDT independently with different handler implementations. Bug fixes in one do not affect the other.
+2. **RSDP_ADDR contract**: acpid AML init requires `RSDP_ADDR` environment variable (from `hwd` via `KernelArgs.hwdesc_base`). x86 has BIOS fallback; non-x86 paths are unresolved.
+3. **S5 derivation timing**: Depends on AML readiness which depends on PCI registration. Pre-PCI shutdown falls back gracefully but the degraded contract is weak.
+4. **DMAR orphaned**: 533 lines of Intel VT-d parsing code exist but are not wired into startup.
+
+### 2.5 TODO Inventory
+
+- **Kernel ACPI**: 16 TODOs (`madt` arch variants, `hpet` x86 assumption, `spcr` type support, `scheme/acpi` context switch, `gtdt`)
+- **Userspace acpid**: 24 TODOs (`acpi.rs`: 10, `dmar/`: 9, `main.rs`: 3, `scheme.rs`: 1, `aml_physmem.rs`: 1)
+- **Total**: 40 TODOs
+
+### 2.6 Alignment with ACPI-IMPROVEMENT-PLAN.md
+
+| Wave | Plan Status | Code Reality | Delta |
+|------|-------------|--------------|-------|
+| W0 Contracts | ~80% | Truth statement accurate | — |
+| W1 Startup hardening | ~60% | P19 patch removed panic-grade expects; remaining `expect()` in firmware-origin paths | Underdocumented |
+| W2 AML ordering/shutdown | ~50% | S5 derivation improved (P24); explicit error types exist; timing still coupled to PCI | Underdocumented |
+| W3 Honest power surface | Open | Battery/AC probing exists but not trustworthy; thermal/fan discovery real but no backend action | — |
+| W4 Physmem/EC/fault handling | ~40% | **Two critical stubs at lines 195, 274 not flagged in plan** | **New finding** |
+| W5 Ownership cleanup | Open | DMAR still orphaned; dual interpreters unresolved | — |
+| W6 Consumer integration | ~60% | kstop→sessiond path works | — |
+| W7 Validation closure | Open | No bare-metal validation matrix executed | — |
+
+---
+
+## 3. IRQ / PCI Reassessment
+
+### 3.1 Architecture
+
+```
+PCI Device → MSI/MSI-X message (address 0xFEE0_0xxx + data)
+    │
+    ▼
+APIC (local or I/O) → Vector delivery to target CPU
+    │
+    ▼
+Kernel IDT → generic_irq handler (vec 32–255)
+    │
+    ▼
+scheme/irq.rs → irq_trigger(irq, token)
+    ├── iommu_validate_msi_irq(irq)  ← STUB: returns true unconditionally
+    ├── increment COUNTS[irq]
+    ├── walk HANDLES for matching fd
+    └── trigger EVENT_READ
+    │
+    ▼
+Userspace driver → IrqHandle::wait() returns with count
+```
+
+### 3.2 What Is Working
+
+| Component | File | Evidence |
+|-----------|------|----------|
+| IDT (256 entries) | `arch/x86_shared/idt.rs` | 224 generic vectors, legacy IRQ bindings, IPI handlers, 374 lines |
+| 8259 PIC | `arch/x86_shared/device/pic.rs` | Master/slave init, mask, ack, ISR query, 98 lines |
+| I/O APIC | `arch/x86_shared/device/ioapic.rs` | MADT-parsed, GSI resolution, affinity reprogramming, 502 lines |
+| LAPIC/x2APIC | `arch/x86_shared/device/local_apic.rs` | MMIO + MSR dual path, IPI, EOI, ESR, 312 lines |
+| IRQ dispatch | `arch/x86_shared/interrupt/irq.rs` | PIC/APIC switching, spurious accounting, 352 lines |
+| IRQ scheme | `scheme/irq.rs` | Registration, delivery, affinity, per-CPU listing, 650 lines |
+| MSI kernel code | `arch/x86_shared/device/msi.rs` | Message composition, validation, capability parsing, 183 lines |
+| Vector allocator | `arch/x86_shared/device/vector.rs` | CAS bitmap for 224 vectors, 53 lines |
+| redox-driver-sys IRQ | `redox-driver-sys/src/irq.rs` | MSI-X table mapping, vector allocation, affinity, 491 lines, **zero TODOs** |
+| redox-driver-sys PCI | `redox-driver-sys/src/pci.rs` | Config space, BAR probing, MSI-X enable, 1446 lines, **zero TODOs** |
+| pcid daemon | `drivers/pcid/src/` | Enumeration, scheme:pci, driver spawn, ~1400 lines total |
+| driver-manager | `driver-manager/src/main.rs` | PciBus + AcpiBus binding, boot timeline, 553 lines |
+
+### 3.3 Critical Stubs
+
+| Location | Line | Issue | Severity |
+|----------|------|-------|----------|
+| `kernel/src/scheme/irq.rs` | 231 | `iommu_validate_msi_irq(_irq) -> bool { true }` — **zero IOMMU validation** | 🔴 CRITICAL |
+| `kernel/src/arch/x86_shared/device/local_apic.rs` | 81 | `//self.setup_timer();` — **APIC timer disabled** | 🟠 HIGH |
+| `kernel/src/arch/x86_shared/interrupt/irq.rs` | 307 | `println!("Local apic timer interrupt");` — debug artifact | 🟡 MEDIUM |
+| `kernel/src/arch/x86_shared/device/ioapic.rs` | 329–331 | `.unwrap()` on cpuid — panic risk | 🟡 MEDIUM |
+| `drivers/pcid/src/driver_interface/irq_helpers.rs` | — | "FIXME for cpu_id >255 need IOMMU IRQ remapping" | 🟠 HIGH |
+| `drivers/pcid/src/driver_interface/irq_helpers.rs` | — | "FIXME allow allocating multiple interrupt vectors" | 🟠 HIGH |
+
+### 3.4 Patch-Backed Code
+
+The following kernel code does **not exist in upstream** — it is entirely Red Bear patches:
+
+- `msi.rs` (+183 lines) — added by `P8-msi.patch` (281 lines, 12 hunks)
+- `vector.rs` (+53 lines) — added by `P8-msi.patch`
+- IOAPIC affinity — `P9-ioapic-irq-affinity.patch`
+- IRQ affinity wiring — `P10-irq-affinity-wiring.patch`
+- x2APIC ICR fix — `P20-x2apic-icr-mode-fix.patch`
+- x2APIC SMP fix — `P21-x2apic-smp-fix.patch`
+- x2APIC MADT fallback — `P22-x2apic-madt-fallback.patch`
+
+**Risk**: If upstream kernel rebases, these patches must be rebased. The MSI/MSI-X subsystem is entirely patch-dependent.
+
+### 3.5 Alignment with IRQ Enhancement Plan
+
+The plan reports all 6 Waves as **✅ Complete**. Code inspection confirms the Waves addressed panic hardening and code quality. However, **6 priority areas remain entirely open** and the plan does not flag:
+
+- `iommu_validate_msi_irq()` stub (CRITICAL — not mentioned)
+- APIC timer disabled (not mentioned)
+- Single-vector-per-device limit (mentioned as FIXME but not prioritized)
+
+---
+
+## 4. Enumeration / Driver Binding Reassessment
+
+### 4.1 Current Flow
+
+```
+pcid enumerates PCI bus → /scheme/pci/{segment}--{bus}--{device}.{function}/
+    │
+    ▼
+driver-manager (or pcid-spawner legacy) reads /scheme/pci/
+    │
+    ▼
+For each device: query config space (vendor, device, class, subclass)
+    │
+    ▼
+Match against driver config (PCI class/vendor/device ID lookup)
+    │
+    ▼
+Spawn driver daemon with PCID_CLIENT_CHANNEL env var
+    │
+    ▼
+Driver opens /scheme/pci/{addr}/config and /scheme/irq/{irq}
+```
+
+### 4.2 Limitations
+
+1. **No ACPI _HID/_CID matching**: Non-PCI devices (ACPI-enumerated GPIO, I2C, etc.) are not bound through the driver-manager.
+2. **No modalias generation**: Drivers are matched by simple class-code or vendor/device ID — no automatic alias generation from PCI class/subclass/prog-if.
+3. **LegacyBackend is a stub**: `hwd/backend/legacy.rs:13` — "TODO: handle driver spawning from legacy backend" — any non-ACPI, non-DTB platform gets no hardware discovery.
+4. **Initfs transitional**: `hwd` and `acpid` live on initfs boot path, not under stable rootfs service contract.
+
+### 4.3 Alignment with Boot-Process-Hardware-Detection-Plan.md
+
+| Wave | Plan Status | Code Reality |
+|------|-------------|--------------|
+| W0 Boot stage definitions | ✅ Done | Config-only |
+| W1 ACPI bus in driver-manager | ✅ Done | `AcpiBus` exists |
+| W2 Resource parser (_CRS, _PRT) | ✅ Done | Parsed |
+| W2b ACPI device binding | ✅ Done | Wired |
+| W2c GPIO/I2C configs | Partial | Runtime _CRS evaluation **not started** |
+| W3 Service rewiring | ✅ Done | Stage targets wired |
+| W4 Dead /etc/pcid.d/ removal | ✅ Done | Removed |
+| W5 Deferred probing | ✅ Already had | Scheme-aware |
+| W6 USB topology enumeration | **Not started** | Depends on xHCI IRQ stability |
+
+---
+
+## 5. Driver Infrastructure Reassessment
+
+### 5.1 redox-driver-sys
+
+**Status: ✅ Production quality, zero stubs, zero TODOs**
+
+- **Schemes**: memory (physical mapping, cache type control), irq (registration, wait, affinity), pci (enumeration, config space, BARs, MSI-X)
+- **Quirks**: 3-layer (compiled-in 11 entries + TOML runtime + DMI/SMBIOS 8 rules), 22 PCI flags, 21 USB flags
+- **MSI-X**: Full `MsixTable` with validated x86 message programming, vector allocation, CPU round-robin
+- **DMA**: `DmaBuffer` (phys-contiguous), `IommuDmaAllocator` (MAP/UNMAP protocol)
+- **Tests**: 30+ unit tests in `pci.rs`
+
+### 5.2 linux-kpi
+
+**Status: ✅ Structurally complete for GPU + Wi-Fi, 119 tests passing, zero stubs**
+
+- **17 Rust modules**, **32 C headers**
+- **Full implementations**: pci (777 lines), net (809), wireless (1002), mac80211 (959), irq (228), firmware (277), drm_shim (374)
+- **No `todo!()`/`unimplemented!()`** in any audited module
+- **C header coverage**: pci.h, skbuff.h, interrupt.h, firmware.h, netdevice.h, ieee80211.h, nl80211.h, cfg80211.h, mac80211.h, drm*.h, atomic.h, spinlock.h, mutex.h, workqueue.h, timer.h, wait.h, list.h, slab.h, mm.h, io.h, types.h, errno.h, compiler.h, export.h, printk.h, module.h, refcount.h, jiffies.h, kernel.h, idr.h, bug.h
+
+### 5.3 firmware-loader
+
+**Status: ✅ Production quality**
+
+- `scheme:firmware` daemon with `SchemeSync` impl
+- MANIFEST generation (BLAKE3), `--probe`, `--request-nowait`
+- Path traversal prevention, 64MB blob cap, cache with source signature validation
+- AMD GPU: 17 firmware keys expected; Intel: per-generation DMC firmware
+
+### 5.4 GPU Drivers
+
+| Driver | Status | Key Gap |
+|--------|--------|---------|
+| redox-drm (AMD) | 🟡 Compiles, 616 lines | `synthetic_edid()` fallback — no real DDC/I²C |
+| redox-drm (Intel) | 🟡 Compiles, 693 lines | `synthetic_edid()` fallback — no real DDC/I²C |
+| redox-drm (VirtIO) | 🟡 Compiles | `synthetic_edid()` fallback |
+| amdgpu (C port) | 🟡 Compiles, ~1487 lines | Hardcoded 4 connector descriptors, no real HPD |
+
+**All three GPU drivers use `synthetic_edid()`** at `redox-drm/src/kms/connector.rs:35` — a hardcoded 128-byte EDID 1.4 block for 1920×1080@60Hz. This blocks real display detection on bare metal.
+
+### 5.5 Wi-Fi
+
+**Status: 🟡 Compiles + host-tested, zero hardware validation**
+
+- `redbear-iwlwifi`: C transport layer (~2450 lines) + Rust daemon (~1550 lines)
+- 8 host tests pass
+- Commands time out without real firmware — by design
+- No Intel Wi-Fi device ever exercised
+
+### 5.6 USB
+
+**Status: 🟡 xhcid builds + QEMU proofs pass, bare-metal incomplete**
+
+- xhcid: Red Bear patched, QEMU IRQ delivery proven
+- usbscsid: USB mass storage with inline quirks (214 storage quirks)
+- usbhubd: Hub port management
+- **Gap**: No EHCI, UHCI, or OHCI drivers — legacy USB keyboards on companion controllers are unreachable on bare metal
+
+---
+
+## 6. Cross-Cutting Critical Gaps (Updated Priority)
+
+### Gap 1 — IOMMU MSI Validation (CRITICAL)
+**File**: `kernel/src/scheme/irq.rs:231`
+```rust
+fn iommu_validate_msi_irq(_irq: u8) -> bool {
+    true
+}
+```
+Every MSI/MSI-X interrupt bypasses IOMMU remapping validation. This is a security and correctness gap. The hook exists but has zero logic.
+
+**Root cause**: IOMMU daemon (`iommu`) provides AMD-Vi runtime but no Intel VT-d. The validation function needs remapping table data from the IOMMU daemon, or validation must move to userspace via a scheme call.
+
+**Action**: Implement real validation against IOMMU remapping tables, or explicitly document that MSI/MSI-X without IOMMU is only safe on trusted buses.
+
+### Gap 2 — AML Physical Memory Stubs (CRITICAL)
+**Files**: `acpid/src/aml_physmem.rs:195`, `:274`
+- `read_phys_or_fault()` returns `T::zero()` on failure — fabricates data
+- `map_physical_region()` falls back to zero page — silent data loss
+
+**Impact**: Any AML method accessing a physical memory region that fails to map will see fabricated zeroes. This can cause:
+- Incorrect battery/thermal readings
+- Silent EC communication failures
+- Wrong power state transitions
+
+**Action**: Propagate `Result<T>` errors to AML evaluation callers instead of fabricating values.
+
+### Gap 3 — Kernel Sleep Path PCI Stubs (CRITICAL)
+**File**: `kernel/src/arch/x86_shared/sleep.rs:257–276`
+- `read_pci_u8/u16/u32` always return 0
+- `write_pci_*` are no-ops
+
+**Impact**: Any AML code using PCI config space access in the kernel S3/S5 sleep path gets fabricated values. This is only safe if the sleep path guarantees no PCI-dependent AML methods are evaluated.
+
+**Action**: Either wire real PCI config space access in the kernel sleep path, or explicitly scope the kernel AML interpreter to exclude PCI-dependent methods.
+
+### Gap 4 — APIC Timer Disabled (HIGH)
+**File**: `kernel/src/arch/x86_shared/device/local_apic.rs:81`
+- `setup_timer()` commented out
+- System uses PIT fallback for all timer interrupts
+
+**Impact**: No per-CPU timer interrupts (all CPUs share PIT on BSP), no TSC deadline mode for modern CPUs, potential timer skew on SMP.
+
+**Action**: Re-enable APIC timer with calibration against PIT or TSC. Required for per-CPU timer distribution.
+
+### Gap 5 — Synthetic EDID in All GPU Drivers (HIGH)
+**File**: `redox-drm/src/kms/connector.rs:35`
+- All three drivers (AMD, Intel, VirtIO) use hardcoded EDID
+- No real DDC/I²C display detection
+
+**Impact**: Display will not work on bare metal with non-1080p panels, multi-monitor setups, or displays with non-standard timings.
+
+**Action**: Implement I²C-over-DDC EDID retrieval in `redox-drm`, or at minimum implement a real connector detection path that queries HPD + DDC before falling back to synthetic.
+
+### Gap 6 — Dual AML Interpreters (HIGH)
+**Files**: `kernel/src/arch/x86_shared/sleep.rs` (acpi_ext crate) + `acpid/src/acpi.rs` (acpi crate)
+- Two independent parsers for the same DSDT/SSDT
+- Different handler implementations (kernel has PCI stubs, userspace has physmem stubs)
+- Bug fixes in one do not affect the other
+
+**Impact**: Maintenance risk, correctness divergence, two surfaces for AML security issues.
+
+**Action**: Converge on a single canonical interpreter. Recommendation: userspace (acpid) since all drivers are userspace per project model. Kernel sleep path should delegate to userspace or use a shared, read-only AML namespace.
+
+### Gap 7 — No EHCI/UHCI/OHCI Drivers (HIGH)
+**Impact**: Legacy USB keyboards on companion controller paths unreachable on bare metal. Only xHCI-native USB devices work.
+
+**Action**: Implement EHCI driver (highest priority — covers most USB 2.0 controllers with xHCI companion). UHCI/OHCI are lower priority (very old hardware).
+
+### Gap 8 — No C-State Kernel Backend (HIGH)
+**Impact**: CPUs run at full frequency constantly on bare metal. Thermal throttling only.
+
+**Action**: Implement `cpuidle`/`cpufreq` kernel backend using MWAIT or HLT. Discovery exists in acpid (`cstate.rs`) but kernel has no idle driver.
+
+### Gap 9 — DMAR Orphaned (MEDIUM)
+**File**: `acpid/src/acpi.rs:545`
+- 533 lines of Intel VT-d parsing code
+- `Dmar::init()` commented out — "hangs on real hardware"
+
+**Action**: Either fix the hang and assign a runtime owner (iommu daemon), or remove the orphaned code until ready.
+
+### Gap 10 — >256 CPU MSI Remapping (MEDIUM)
+**File**: `drivers/pcid/src/driver_interface/irq_helpers.rs`
+- 8-bit APIC destination field limits MSI target selection
+- IOMMU interrupt remapping required for >256 CPUs
+
+**Action**: Gated on IOMMU maturity (Gap 1).
+
+---
+
+## 7. Updated Execution Plan
+
+### Phase 1: Critical Stub Removal (2–3 weeks)
+**Goal**: Remove all CRITICAL-severity stubs before any hardware validation.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 1.1 | Fix `read_phys_or_fault()` zero-return | `acpid/src/aml_physmem.rs:195` | 2 days | — |
+| 1.2 | Fix `map_physical_region()` zero-page fallback | `acpid/src/aml_physmem.rs:274` | 2 days | — |
+| 1.3 | Fix kernel sleep path PCI read stubs | `kernel/src/arch/x86_shared/sleep.rs:257–276` | 3 days | — |
+| 1.4 | Document kernel PCI stub scope | `sleep.rs` | 1 day | — |
+| 1.5 | Remove `println!` debug artifact | `kernel/src/arch/x86_shared/interrupt/irq.rs:307` | 1 hour | — |
+
+**Gate**: All CRITICAL stubs removed + `cargo check` clean on affected modules.
+
+### Phase 2: IOMMU + MSI Validation (3–4 weeks)
+**Goal**: Make MSI/MSI-X delivery trustworthy.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 2.1 | Implement `iommu_validate_msi_irq()` real logic | `kernel/src/scheme/irq.rs:231` | 1 week | — |
+| 2.2 | Wire IOMMU remapping table read into kernel | `iommu` daemon ↔ `scheme/irq` | 1 week | — |
+| 2.3 | QEMU validation: MSI-X with IOMMU enabled | `test-msix-qemu.sh` | 2 days | — |
+| 2.4 | Fix or remove orphaned DMAR code | `acpid/src/acpi.rs:545` | 2 days | — |
+
+**Gate**: `test-msix-qemu.sh` passes with IOMMU enabled + no `iommu_validate_msi_irq()` stub.
+
+### Phase 3: Timer + CPU Power (2–3 weeks)
+**Goal**: Enable per-CPU timers and basic CPU idle.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 3.1 | Re-enable APIC timer with calibration | `kernel/src/arch/x86_shared/device/local_apic.rs:81` | 3 days | — |
+| 3.2 | Implement kernel cpuidle backend (MWAIT/HLT) | New file: `kernel/src/arch/x86_shared/cpuidle.rs` | 1 week | — |
+| 3.3 | Wire acpid C-state discovery to kernel idle | `acpid/src/cstate.rs` → kernel | 3 days | — |
+| 3.4 | QEMU validation: timer + idle | `test-timer-qemu.sh` | 2 days | — |
+
+**Gate**: `test-timer-qemu.sh` passes with APIC timer + CPU idle active.
+
+### Phase 4: Display Detection (4–6 weeks)
+**Goal**: Replace synthetic EDID with real display detection.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 4.1 | Implement I²C-over-DDC EDID retrieval | `redox-drm/src/kms/ddc.rs` (new) | 2 weeks | — |
+| 4.2 | Wire HPD interrupt to connector detection | `redox-drm/src/drivers/amd/mod.rs`, `intel/mod.rs` | 1 week | — |
+| 4.3 | Replace `synthetic_edid()` with real → fallback | `redox-drm/src/kms/connector.rs:35` | 3 days | — |
+| 4.4 | QEMU validation: EDID readback | `test-drm-display-runtime.sh` | 2 days | — |
+| 4.5 | Bare-metal validation: AMD GPU display | `test-amd-gpu.sh` | 1 week | — |
+| 4.6 | Bare-metal validation: Intel GPU display | `test-intel-gpu.sh` | 1 week | — |
+
+**Gate**: Real EDID retrieved from at least one display on bare metal (AMD or Intel).
+
+### Phase 5: USB Legacy Controllers (3–4 weeks)
+**Goal**: Enable USB keyboard on non-xHCI paths.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 5.1 | Implement EHCI host controller driver | `local/recipes/drivers/ehcid/` (new) | 2 weeks | — |
+| 5.2 | Wire EHCI into driver-manager PCI binding | `driver-manager/src/main.rs` | 3 days | — |
+| 5.3 | QEMU validation: EHCI keyboard | `test-usb-qemu.sh` | 2 days | — |
+| 5.4 | UHCI/OHCI assessment | — | 1 week | — |
+
+**Gate**: USB keyboard works via EHCI in QEMU.
+
+### Phase 6: AML Convergence (3–4 weeks)
+**Goal**: Resolve dual AML interpreter risk.
+
+| # | Task | File | Effort | Owner |
+|---|------|------|--------|-------|
+| 6.1 | Evaluate kernel sleep.rs → userspace delegation | `kernel/src/arch/x86_shared/sleep.rs` | 1 week | — |
+| 6.2 | Implement kernel→userspace S3/S5 sleep RPC | `scheme/kernel.acpi/sleep` → `acpid` | 1 week | — |
+| 6.3 | Remove kernel `acpi_ext` crate if delegated | `kernel/src/arch/x86_shared/sleep.rs` | 3 days | — |
+| 6.4 | QEMU validation: sleep/wake cycle | `test-sleep-qemu.sh` | 2 days | — |
+
+**Gate**: S5 shutdown works with single AML interpreter (userspace only).
+
+### Phase 7: Hardware Validation Matrix (4–6 weeks, parallel with 4–6)
+**Goal**: Evidence-based support claims.
+
+| # | Task | Hardware | Effort |
+|---|------|----------|--------|
+| 7.1 | Class A1 validation (AMD desktop + discrete GPU) | Ryzen 5000/7000 + AMD GPU | 1 week |
+| 7.2 | Class A2 validation (Intel desktop + iGPU) | Core 12th–14th Gen | 1 week |
+| 7.3 | Class A3 validation (AMD laptop) | Ryzen Mobile | 1 week |
+| 7.4 | Class A4 validation (Intel laptop) | Core Mobile | 1 week |
+| 7.5 | Regression test suite on all 4 classes | All | 2 weeks |
+
+**Gate**: All 4 hardware classes pass boot, shutdown, USB keyboard, and display detection.
+
+---
+
+## 8. Timeline Synthesis
+
+```
+Week  1–3:  Phase 1 — Critical stub removal
+Week  4–7:  Phase 2 — IOMMU + MSI validation
+Week  7–9:  Phase 3 — Timer + CPU power (parallel with Phase 2 week 7)
+Week 10–15: Phase 4 — Display detection (parallel with Phase 5)
+Week 10–13: Phase 5 — USB legacy controllers (parallel with Phase 4)
+Week 14–17: Phase 6 — AML convergence
+Week 14–19: Phase 7 — Hardware validation matrix (parallel with Phase 6)
+
+Total: 19 weeks (≈4.5 months) with 2 developers
+```
+
+### What the existing plans said vs this plan
+
+| Plan | Claimed Timeline | Reality |
+|------|-----------------|---------|
+| COMPREHENSIVE P1 (bare-metal hardening) | 6–8 weeks | Understated — no critical stub removal phase |
+| COMPREHENSIVE P2 (USB) | 4–6 weeks | Realistic for EHCI only |
+| COMPREHENSIVE P3 (IRQ/IOMMU) | 4–6 weeks | Realistic if focused on Gap 1 only |
+| IRQ plan Waves 1–6 | "Complete" | Code quality complete, validation not started |
+| ACPI plan Waves 0–7 | W0–W4 partial, W5–W7 open | Accurate, but two critical stubs not flagged |
+| SMP plan bottlenecks | 11–18 days | Realistic for B1–B2 only |
+
+### Dependencies
+
+```
+Phase 1 (stub removal)
+    │
+    ├── required by ──► Phase 2 (IOMMU validation)
+    │
+    ├── required by ──► Phase 3 (timer + idle)
+    │
+    └── required by ──► Phase 4 (display detection)
+
+Phase 2 (IOMMU)
+    └── required by ──► Phase 7 (hardware validation — safe MSI)
+
+Phase 3 (timer + idle)
+    └── required by ──► Phase 7 (hardware validation — no overheating)
+
+Phase 4 (display)
+    └── required by ──► Phase 7 (hardware validation — working console)
+
+Phase 5 (USB EHCI)
+    └── required by ──► Phase 7 (hardware validation — keyboard input)
+
+Phase 6 (AML convergence)
+    └── not blocking ──► Phase 7 (can validate with dual interpreters)
+```
+
+---
+
+## 9. Risk Register
+
+| # | Risk | Likelihood | Impact | Mitigation |
+|---|------|-----------|--------|------------|
+| R1 | `aml_physmem` stub fix reveals deeper AML memory access issues | Medium | High | Fix with comprehensive error propagation; add fallback to kernel scheme for problematic regions |
+| R2 | IOMMU validation implementation requires kernel ABI change | Medium | High | Prototype in userspace first via `scheme:iommu` call; only promote to kernel if performance requires it |
+| R3 | APIC timer calibration fails on specific CPU models | Medium | Medium | Keep PIT fallback path; detect calibration failure and degrade gracefully |
+| R4 | DDC/I²C implementation requires GPIO/I2C subsystem not yet built | High | High | Scope Phase 4 to "query EDID via ACPI _DDC method first, then direct I²C"; fallback to synthetic still acceptable for initial bring-up |
+| R5 | EHCI driver requires IRQ/MSI-X fixes first | Medium | Medium | Phase 5 starts after Phase 2 gate; use legacy IRQ for EHCI if MSI-X not ready |
+| R6 | AML convergence breaks S3 sleep path | Medium | High | Keep kernel sleep.rs as fallback during transition; remove only after S3 validated via userspace path |
+| R7 | No bare-metal hardware available for validation | Medium | Critical | Prioritize QEMU proofs for all phases; document "QEMU-validated" vs "bare-metal-validated" per subsystem |
+
+---
+
+## 10. Verification Gates
+
+### Gate A: Boot-Baseline Ready (end of Phase 1)
+- [ ] `aml_physmem.rs:195` returns `Result<T>` instead of `T::zero()`
+- [ ] `aml_physmem.rs:274` propagates mapping errors instead of zero-page fallback
+- [ ] `sleep.rs:257–276` either wired to real PCI or explicitly scoped out
+- [ ] `cargo check` clean on `acpid`, `kernel`, `redox-drm`
+- [ ] `repo validate-patches kernel` passes
+- [ ] `repo validate-patches base` passes
+
+### Gate B: IRQ/IOMMU Trustworthy (end of Phase 2)
+- [ ] `iommu_validate_msi_irq()` performs real validation
+- [ ] `test-msix-qemu.sh` passes with IOMMU enabled
+- [ ] `test-iommu-qemu.sh` passes
+- [ ] No unconditional `true` returns in IRQ validation path
+
+### Gate C: Timer + Power (end of Phase 3)
+- [ ] APIC timer fires and calibrates correctly in QEMU
+- [ ] CPU idle backend enters C1/C2 via MWAIT or HLT
+- [ ] `test-timer-qemu.sh` passes
+- [ ] No PIT-only fallback in boot log
+
+### Gate D: Display Detection (end of Phase 4)
+- [ ] `synthetic_edid()` is fallback, not primary
+- [ ] Real EDID retrieved from at least one display in QEMU
+- [ ] `test-drm-display-runtime.sh` passes
+
+### Gate E: USB Legacy (end of Phase 5)
+- [ ] EHCI driver enumerates devices in QEMU
+- [ ] USB keyboard functional via EHCI in QEMU
+- [ ] `test-usb-qemu.sh` passes
+
+### Gate F: Single AML Interpreter (end of Phase 6)
+- [ ] S5 shutdown works with userspace AML only
+- [ ] Kernel `acpi_ext` crate removed or explicitly deprecated
+- [ ] `test-sleep-qemu.sh` passes (S3 + S5)
+
+### Gate G: Hardware Validation (end of Phase 7)
+- [ ] Class A1 (AMD desktop) boots, shuts down, displays, accepts USB keyboard
+- [ ] Class A2 (Intel desktop) boots, shuts down, displays, accepts USB keyboard
+- [ ] Class A3 (AMD laptop) boots, shuts down, displays, accepts USB keyboard
+- [ ] Class A4 (Intel laptop) boots, shuts down, displays, accepts USB keyboard
+- [ ] Validation artifacts committed to `local/docs/HARDWARE-VALIDATION-MATRIX.md`
+
+---
+
+## 11. Appendix: Key File Reference
+
+### ACPI
+- `recipes/core/kernel/source/src/acpi/mod.rs` — Kernel ACPI orchestrator
+- `recipes/core/kernel/source/src/acpi/rsdp.rs` — RSDP discovery
+- `recipes/core/kernel/source/src/acpi/madt/mod.rs` — MADT parser
+- `recipes/core/kernel/source/src/scheme/acpi.rs` — Kernel ACPI scheme
+- `recipes/core/kernel/source/src/arch/x86_shared/sleep.rs` — Kernel AML interpreter for sleep
+- `recipes/core/kernel/source/src/arch/x86_shared/stop.rs` — Shutdown orchestrator
+- `recipes/core/base/source/drivers/acpid/src/main.rs` — acpid daemon entry
+- `recipes/core/base/source/drivers/acpid/src/acpi.rs` — Core ACPI context
+- `recipes/core/base/source/drivers/acpid/src/aml_physmem.rs` — AML physmem handler (stubs at :195, :274)
+- `recipes/core/base/source/drivers/acpid/src/ec.rs` — Embedded Controller handler
+- `recipes/core/base/source/drivers/acpid/src/thermal.rs` — Thermal zone discovery
+- `recipes/core/base/source/drivers/acpid/src/fan.rs` — Fan device discovery
+- `recipes/core/base/source/drivers/acpid/src/cstate.rs` — C-state discovery
+- `recipes/core/base/source/drivers/acpid/src/dmi.rs` — SMBIOS DMI parser
+- `recipes/core/base/source/drivers/hwd/src/backend/acpi.rs` — hwd ACPI backend
+- `recipes/core/base/source/drivers/hwd/src/backend/legacy.rs` — LegacyBackend stub (:13)
+
+### IRQ / PCI
+- `recipes/core/kernel/source/src/scheme/irq.rs` — IRQ scheme (stub at :231)
+- `recipes/core/kernel/source/src/arch/x86_shared/interrupt/irq.rs` — IRQ dispatch
+- `recipes/core/kernel/source/src/arch/x86_shared/device/ioapic.rs` — I/O APIC
+- `recipes/core/kernel/source/src/arch/x86_shared/device/local_apic.rs` — LAPIC (timer disabled at :81)
+- `recipes/core/kernel/source/src/arch/x86_shared/device/msi.rs` — MSI code (patch-based)
+- `recipes/core/kernel/source/src/arch/x86_shared/device/vector.rs` — Vector allocator (patch-based)
+- `recipes/core/kernel/source/src/arch/x86_shared/device/pic.rs` — 8259 PIC
+- `recipes/core/kernel/source/src/arch/x86_shared/idt.rs` — IDT setup
+- `local/recipes/drivers/redox-driver-sys/source/src/irq.rs` — Userspace IRQ handling
+- `local/recipes/drivers/redox-driver-sys/source/src/pci.rs` — Userspace PCI abstraction
+- `recipes/core/base/source/drivers/pcid/src/main.rs` — pcid daemon
+- `recipes/core/base/source/drivers/pcid/src/scheme.rs` — PciScheme
+- `recipes/core/base/source/drivers/pcid/src/driver_interface/irq_helpers.rs` — IRQ helper FIXMEs
+- `local/recipes/system/driver-manager/source/src/main.rs` — Driver manager
+
+### Driver Infrastructure
+- `local/recipes/drivers/redox-driver-sys/source/src/lib.rs` — Core library
+- `local/recipes/drivers/redox-driver-sys/source/src/quirks/mod.rs` — Quirks API
+- `local/recipes/drivers/linux-kpi/source/src/lib.rs` — linux-kpi crate
+- `local/recipes/drivers/linux-kpi/source/src/rust_impl/pci.rs` — PCI KPI (777 lines)
+- `local/recipes/drivers/linux-kpi/source/src/rust_impl/drm_shim.rs` — DRM GEM shim
+- `local/recipes/drivers/linux-kpi/source/src/rust_impl/mac80211.rs` — mac80211 KPI (959 lines)
+- `local/recipes/drivers/linux-kpi/source/src/rust_impl/wireless.rs` — cfg80211 KPI (1002 lines)
+- `local/recipes/system/firmware-loader/source/src/main.rs` — firmware-loader daemon
+- `local/recipes/gpu/redox-drm/source/src/main.rs` — DRM daemon
+- `local/recipes/gpu/redox-drm/source/src/drivers/amd/mod.rs` — AMD GPU driver
+- `local/recipes/gpu/redox-drm/source/src/drivers/intel/mod.rs` — Intel GPU driver
+- `local/recipes/gpu/redox-drm/source/src/kms/connector.rs` — Connector + synthetic EDID (:35)
+- `local/recipes/gpu/amdgpu/source/amdgpu_redox_main.c` — Bounded AMD display C port
+- `local/recipes/gpu/amdgpu/source/redox_glue.h` — Linux→Redox C glue
+- `local/recipes/gpu/amdgpu/source/redox_stubs.c` — Kernel emulation stubs
+
+### Patches
+- `local/patches/kernel/redbear-consolidated.patch` — Consolidated mega-patch
+- `local/patches/kernel/P8-msi.patch` — MSI + vector allocator
+- `local/patches/kernel/P9-ioapic-irq-affinity.patch` — IRQ affinity
+- `local/patches/kernel/P10-irq-affinity-wiring.patch` — Affinity wiring
+- `local/patches/kernel/P20-x2apic-icr-mode-fix.patch` — x2APIC ICR
+- `local/patches/kernel/P21-x2apic-smp-fix.patch` — x2APIC SMP
+- `local/patches/kernel/P22-x2apic-madt-fallback.patch` — x2APIC MADT fallback
+- `local/patches/kernel/P24-cstate-mwait-idle.patch` — C-state MWAIT
+- `local/patches/kernel/P25-cpuidle-deep-cstates.patch` — Deep C-states
+- `local/patches/base/P19-acpid-startup-hardening.patch` — acpid startup
+- `local/patches/base/P24-acpi-s5-derivation-shutdown-semantics.patch` — S5 derivation
+- `local/patches/base/P44-acpid-thermal-zones.patch` — Thermal zones
+- `local/patches/base/P48-acpid-fan-support.patch` — Fan support
+- `local/patches/base/P52-acpid-cstates.patch` — C-state discovery
+
+---
+
+## 12. Document Authority
+
+This document is a **cross-cutting reassessment** that references but does not replace the canonical subsystem plans:
+
+- For ACPI wave-level execution detail, see `ACPI-IMPROVEMENT-PLAN.md`
+- For IRQ/PCI wave-level execution detail, see `IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`
+- For boot detection wave detail, see `BOOT-PROCESS-HARDWARE-DETECTION-PLAN.md`
+- For SMP bottleneck detail, see `SMP-SCHEDULER-IMPROVEMENT-PLAN.md`
+- For desktop path blockers, see `CONSOLE-TO-KDE-DESKTOP-PLAN.md`
+
+**When this document conflicts with a canonical subsystem plan**, the **canonical plan** wins on subsystem-specific details, and this document wins on cross-cutting prioritization and inter-subsystem dependencies.
+
+**This document should be updated** after each phase gate is reached, or when new critical stubs are discovered.