RedBear-OS/local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md

# Red Bear OS IRQ and Low-Level Controllers Enhancement Plan

## Purpose

This document assesses the current IRQ and low-level controller implementation in Red Bear OS for
completeness and quality, then defines the next enhancement plan in execution order.

It is grounded in the current repository state, especially:

- `local/recipes/drivers/redox-driver-sys/`
- `local/recipes/drivers/linux-kpi/`
- `local/recipes/gpu/redox-drm/`
- `local/recipes/system/iommu/`
- `recipes/core/kernel/source/src/acpi/`
- `recipes/core/base/source/drivers/acpid/`
- `local/docs/IOMMU-SPEC-REFERENCE.md`
- `local/docs/ACPI-FIXES.md`
- `local/docs/ACPI-IMPROVEMENT-PLAN.md`
- `docs/04-LINUX-DRIVER-COMPAT.md`

The goal is not to restate that these pieces compile, but to separate:

- what exists architecturally,
- what is only build-validated,
- what is runtime-validated,
- and what still needs focused enhancement work.

## Evidence Model

This plan uses four different evidence buckets and does **not** treat them as equivalent:

- **Checked-in source** — what is visible directly in the current source tree.
- **Local patch state** — behavior carried by `local/patches/*` that may not be visible in the
  unpacked upstream source snapshot until patches are applied.
- **Build-validated** — code or recipes compile successfully.
- **Runtime-validated** — behavior has been exercised in a real boot/runtime path.

Where a statement depends on local patches instead of the visible source snapshot, that is called
out explicitly below.

## Controller Inventory and Ownership

| Area | Primary owner | Main entry points | Current evidence class |
|---|---|---|---|
| LAPIC / xAPIC / x2APIC | kernel | `recipes/core/kernel/source/src/acpi/madt/`, `arch/x86_shared/device/local_apic.rs` | source + local patch + boot/runtime evidence |
| IOAPIC / IRQ overrides | kernel | `recipes/core/kernel/source/src/arch/x86_shared/device/ioapic.rs`, MADT ISO parsing | source |
| Legacy PIC | kernel | `arch/x86_shared/device/pic.rs` | source |
| ACPI power/reset methods | userspace `acpid` | `recipes/core/base/source/drivers/acpid/src/acpi.rs` plus local base patch | source + local patch + runtime evidence |
| HPET / timer tables | kernel | `recipes/core/kernel/source/src/acpi/hpet.rs` | source |
| PIT fallback timer | kernel | `recipes/core/kernel/source/src/arch/x86_shared/device/mod.rs`, `pit.rs` | source |
| PCI interrupt plumbing | userspace `pcid` / driver layer | `recipes/core/base/source/drivers/pci/`, `scheme:irq`, `scheme:pci` | source + runtime evidence |
| Driver IRQ abstraction | `redox-driver-sys` | `local/recipes/drivers/redox-driver-sys/source/src/irq.rs` | source |
| Linux IRQ compatibility | `linux-kpi` | `local/recipes/drivers/linux-kpi/source/` headers | source |
| GPU MSI/MSI-X usage | `redox-drm` | `local/recipes/gpu/redox-drm/source/` | source + build evidence |
| IOMMU / interrupt remapping | `iommu` daemon | `local/recipes/system/iommu/source/src/main.rs`, `local/docs/IOMMU-SPEC-REFERENCE.md` | source + build evidence |
| Kernel serio / PS2 path | kernel `serio` + userspace `ps2d` | `recipes/core/kernel/source/src/scheme/serio.rs`, `recipes/core/base/source/drivers/input/ps2d/src/main.rs` | source |
| Input controller path | `inputd` / `evdevd` / `udev-shim` | base driver + local system recipes | source + runtime evidence |
| USB xHCI host controller | userspace `xhcid` | `recipes/core/base/source/drivers/usb/xhcid/src/main.rs` | source + build evidence |
| Port I/O / legacy controller access | kernel + `redox-driver-sys` | `iopl`, `io.rs`, legacy driver code | source |
| Legacy IRQ dispatch / ownership map | kernel | `recipes/core/kernel/source/src/arch/x86_shared/interrupt/irq.rs` | source |

## Current State Summary

### What is already in place

Red Bear OS already has a meaningful low-level controller and interrupt foundation:

- ACPI boot, FADT power control, visible MADT parsing for LAPIC/IOAPIC/interrupt overrides, and
  HPET initialization are in place in the checked-in source.
- Additional MADT x2APIC / NMI / power-method handling exists in the local patch set and in prior
  runtime validation notes, but that behavior should not be conflated with the unpatched source
  snapshot.
- `redox-driver-sys` provides userspace driver primitives for MMIO, DMA, PCI access, IRQ handles,
  MSI-X table mapping, and IRQ affinity control.
- `linux-kpi` exposes Linux-style IRQ, PCI, memory, and synchronization APIs on top of
  `redox-driver-sys`.
- `redox-driver-sys` now has direct host-runnable unit coverage for pure PCI/IRQ substrate rules,
  including PCI scheme-entry parsing bounds, I/O BAR port conversion safety, and MSI-X BAR window
  helper validation. This should be treated as **source + host-test evidence**, not as runtime
  controller proof.
- `redox-driver-sys` fast PCI enumeration now preserves capability-chain data from config-space
  bytes instead of returning empty capability lists, and exposes a quirk-aware interrupt-support
  summary (`none` / `legacy` / `msi` / `msix`) for downstream policy convergence.
- `redox-drm` already contains a shared interrupt abstraction with MSI-X-first and legacy-IRQ
  fallback paths for GPU drivers.
- The AMD-Vi / Intel VT-d reference material and the in-tree `iommu` daemon establish a serious
  implementation direction for IOMMU and interrupt-remapping work.
- the repo now has a bounded timer proof path via `redbear-phase-timer-check` and
  `local/scripts/test-timer-qemu.sh --check`, which verifies the monotonic time scheme is present
  and advances across two reads inside a guest runtime
- the bounded low-level controller proof hooks can now be run together through
  `local/scripts/test-lowlevel-controllers-qemu.sh`, which sequences xHCI, IOMMU, PS/2, and timer
  runtime checks on the desktop validation image

### What is still weak

The dominant weakness is not missing abstractions. It is missing runtime proof and uneven
controller-specific validation.

- MSI-X support exists architecturally but is still weak on hardware validation.
- IOMMU support is specification-rich and code-rich, but still unvalidated on real hardware.
- IRQ routing quality-of-service remains primitive: raw wait handles exist, but balancing,
  coalescing, and validation of affinity behavior remain thin.
- Input stacks (`inputd`, `evdevd`, `udev-shim`) now exist as a runtime substrate, but the exact
  end-to-end interrupt-to-consumer path still needs sustained validation discipline.
- Low-level controller quality is uneven: ACPI/APIC are much further along than IOMMU, MSI-X, and
  controller-specific runtime characterization.

## Architectural Assessment

### 1. IRQ delivery architecture

The project’s IRQ delivery model is fundamentally sound.

- Kernel/platform side routes interrupts through APIC/x2APIC infrastructure.
- Userspace consumes interrupts through `scheme:irq` handles.
- MSI-X vector allocation is already modeled per CPU via the IRQ scheme.

This is the right design for Red Bear OS. The main enhancement need is validation and quality, not
an architectural rewrite.

### 2. PCI and MSI/MSI-X

The PCI and MSI-X model is one of the strongest parts of the current stack.

- Config-space access exists.
- Capability parsing exists.
- MSI-X table mapping exists.
- GPU drivers already use the abstraction.

The gap is that the repository still talks too often in “compiles” language instead of “validated on
hardware with real interrupts firing” language.

Current runtime-proof entrypoint now present in-tree:

- `local/scripts/test-msix-qemu.sh` — QEMU/UEFI boot path that verifies live `virtio-net`
  initialization reporting `virtio: using MSI-X`

### 3. IOMMU and interrupt remapping

IOMMU was the most important low-level controller area that was still incomplete in practice.

- The implementation direction is correct.
- The data structures and register model are already documented deeply.
- But the hardware-validation story is still effectively open, and current daemon discovery is still
  only partially integrated: the daemon now searches common IVRS table locations automatically, but
  full platform-native discovery and hardware validation are still open.
- The current QEMU path now reaches AMD-Vi unit detection and `scheme:iommu` registration without
  crashing at daemon startup.
- The current guest-driven first-use proof now completes successfully in QEMU: it reaches readable
  and writable AMD-Vi MMIO, initializes both discovered units, and drains the event path without
  faulting.
- The critical blockers that previously stopped this path were fixed in the shared mapping layers,
  not just in the userspace `iommu` daemon: physically contiguous DMA allocations now preserve
  writable mappings, and MMIO mappings now use the explicit `fmap` path with the intended protection
  bits.

This leaves IOMMU as a hardware-validation and deeper interrupt-remapping quality area, rather than
as an immediate QEMU runtime blocker.

### 4. Input/controller path

The input/controller path is no longer missing. It is now a quality and observability problem.

- `inputd` exists.
- `evdevd` exists.
- `udev-shim` exists.
- Phase 3 validation helpers exist.

The enhancement task is to keep turning these from “service present” into “interrupt path proven,”
especially under real runtime scenarios.

## Completeness Assessment by Area

### ACPI / APIC / x2APIC

**State**: materially complete for the historical boot-baseline bring-up goals, but not release-grade complete.

**Important source note**: the checked-in MADT parser in
`recipes/core/kernel/source/src/acpi/madt/mod.rs` visibly handles `LocalApic`, `IoApic`,
 `IntSrcOverride`, `Gicc`, and `Gicd`. Additional x2APIC/NMI support referenced elsewhere in the
 repo is currently evidenced through the local patch set and prior validation notes rather than the
 plain source snapshot alone.

Strengths:

- MADT entries for xAPIC/x2APIC/NMI are handled.
- ACPI reboot/shutdown/power methods exist.
- x2APIC and SMP platform bring-up have already crossed the foundational threshold.

Open enhancement items:

- Better controller/runtime characterization on diverse hardware.
- Clearer documentation for what is kernel-complete versus only tested on limited platforms.
- Keep sleep-state support beyond `\_S5`, DMAR ownership cleanup, and bounded validation visible as open ACPI work rather than implying subsystem closure.

### IOAPIC / interrupt source override routing

**State**: present in ACPI parsing, but less explicitly validated than LAPIC/x2APIC paths.

Concrete checked-in owner:

- `recipes/core/kernel/source/src/arch/x86_shared/device/ioapic.rs`
- `recipes/core/kernel/source/src/acpi/madt/mod.rs`

Open enhancement items:

- explicit validation of interrupt source overrides on more real machines
- repo-visible test notes for IOAPIC routing behavior

### HPET / timer controller surface

**State**: present, but still thinly characterized.

Concrete checked-in owner:

- `recipes/core/kernel/source/src/acpi/hpet.rs`

Open enhancement items:

- runtime verification beyond “initialized from ACPI”
- clearer single-HPET limitation documentation

### PIT fallback timer path

**State**: explicit checked-in fallback controller path.

Concrete checked-in owner:

- `recipes/core/kernel/source/src/arch/x86_shared/device/mod.rs`
- `recipes/core/kernel/source/src/arch/x86_shared/device/pit.rs`

Current behavior:

- the kernel prefers HPET when available
- if HPET initialization fails or is unavailable, it falls back to PIT
- PIT interrupt ticks currently drive timeout and scheduler timing paths

Open enhancement items:

- document runtime characterization of PIT-only boots
- clarify timer-source selection evidence in validation notes

### PCI interrupt plumbing / MSI / MSI-X

**State**: architecturally strong, validation-incomplete.

Open enhancement items:

- real hardware MSI-X proof for AMD and Intel GPU paths
- controller-level observability for vector allocation and affinity behavior
- testable records of fallback behavior between MSI-X and legacy IRQs

Current runtime-validation surface now present in-tree:

- `local/scripts/test-msix-qemu.sh` — boots a Red Bear image and confirms a live MSI-X path via
  `virtio-net` log evidence in QEMU

### IOMMU / interrupt remapping

**State**: QEMU runtime proof present; broader hardware validation still open.

Concrete checked-in owner:

- `local/recipes/system/iommu/source/src/main.rs`
- `local/docs/IOMMU-SPEC-REFERENCE.md`

Open enhancement items:

- real AMD-Vi initialization validation
- event log and fault-path validation
- interrupt remapping validation under device load
- explicit distinction between “daemon builds” and “controller works”
- replacement of `IOMMU_IVRS_PATH`-only discovery with real system discovery/integration

Current implementation improvement:

- the daemon no longer depends only on `IOMMU_IVRS_PATH`; it now searches common IVRS table paths
  automatically before falling back to the environment variable override
- daemon startup now defers AMD-Vi unit initialization until first scheme use, which keeps the
  QEMU validation path alive long enough to prove detection plus `scheme:iommu` registration
- a guest-driven self-test path now exists (`/usr/bin/iommu --self-test-init` via
  `redbear-phase-iommu-check` / `test-iommu-qemu.sh`) and now proves first-use unit initialization
  and event-drain completion in QEMU
- the self-test output now includes structured discovery diagnostics (`discovery_source`,
  `kernel_acpi_status`, `ivrs_path`) so zero-unit failures can be distinguished from kernel-ACPI
  fallback and missing-IVRS cases without changing the IOMMU MMIO path itself

### Legacy IRQ ownership and dispatch map

**State**: explicit checked-in kernel ownership exists, but it is under-documented in higher-level
controller discussions.

Concrete checked-in owner:

- `recipes/core/kernel/source/src/arch/x86_shared/interrupt/irq.rs`

Current covered paths include:

- PIT timer interrupt handling
- keyboard and mouse interrupt delivery
- serial COM1/COM2 delivery
- PIC/APIC mask, acknowledge, and EOI behavior
- spurious IRQ accounting for IRQ7 and IRQ15

Open enhancement items:

- document legacy IRQ ownership and routing expectations explicitly in validation notes
- record PIC-vs-APIC runtime behavior on more hardware classes

### Kernel `serio` / PS2 controller path

**State**: present and important, but easy to miss if input work is described only in terms of the
later `evdevd`/`udev-shim` stack.

Concrete checked-in owner:

- `recipes/core/kernel/source/src/scheme/serio.rs`
- `recipes/core/base/source/drivers/input/ps2d/src/main.rs`

Current behavior:

- the kernel owns the serio byte queues to avoid PS/2 controller races
- `ps2d` consumes `/scheme/serio/0` and `/scheme/serio/1`
- that path then feeds the broader input producer chain

Open enhancement items:

- keep validation language explicit about the PS/2 path versus the later generic input stack
- add platform notes for systems that still rely on PS/2 keyboard/mouse delivery
- the repo now has a bounded PS/2 runtime-proof path via `redbear-phase-ps2-check` and
  `local/scripts/test-ps2-qemu.sh --check`, which proves serio node presence and a successful
  handoff into the existing Phase 3 input-path checker inside a guest
- `ps2d` controller init now also drains stale controller output during probe and around the core
  init/self-test path, which is the current bounded Red Bear-native equivalent of Linux i8042 flush
  discipline before broader PS/2 suspend/resume work exists.

### USB xHCI controller interrupt path

**State**: present, but not honestly interrupt-complete in the checked-in source.

Concrete checked-in owner:

- `recipes/core/base/source/drivers/usb/xhcid/src/main.rs`

Current behavior:

- xHCI has MSI/MSI-X and legacy INTx detection logic in source
- the checked-in `xhcid` source now calls the existing `get_int_method` path again instead of
  hardwiring polling, and it logs whether it selected MSI/MSI-X, legacy INTx, or polling
- `local/scripts/test-xhci-irq-qemu.sh --check` now provides a repo-visible runtime proof path by
  booting a Red Bear image in QEMU and checking the xHCI interrupt-mode log output
- `redox-driver-sys` now logs allocated MSI-X vectors so interrupt selection is more observable in
  runtime logs

Open enhancement items:

- validate the restored interrupt path beyond early boot/logging, especially event-ring behavior
- validate the checked-in event-ring growth path under sustained runtime/device activity

### Port I/O / legacy controller support

**State**: exists, but under-characterized.

Concrete current consumers/owners include:

- legacy PIC handling in `recipes/core/kernel/source/src/arch/x86_shared/device/pic.rs`
- port-I/O wrappers in `local/recipes/drivers/redox-driver-sys/source/src/io.rs`
- ACPI reset fallback via keyboard-controller port writes in the base/acpid patch path documented in
  `local/docs/ACPI-FIXES.md`

Open enhancement items:

- determine which real devices still need the port-I/O path
- validate that the current wrappers are sufficient for those devices

## Quality Assessment

### Strong points

- The layering is correct: kernel/platform routing below, userspace schemes and driver wrappers
  above.
- The repository already has serious implementation artifacts, not just speculative plans.
- The low-level controller work is documented more deeply than many higher-level desktop areas.
- ACPI and early-platform work are significantly more mature than the rest of the low-level stack, but that maturity is still best read as boot-baseline progress with bounded validation rather than subsystem-complete closure.

### Weak points

- Validation language is still inconsistent across docs. “builds” and “validated” are too often
  treated as adjacent states when they are not.
- IOMMU progress is easy to overread because the spec reference is detailed, but the runtime proof
  and discovery story are not there yet.
- Some controller areas are rich in abstractions but poor in operator-facing validation procedures.
- Hardware-controller quality is still under-documented in terms of negative results and known
  failure modes.
- Earlier summaries in the repo can blur checked-in source, local patches, and validated runtime
  behavior; this document should be used to keep those categories separate.
- Broad category labels can hide concrete controller owners unless PIT, `serio`/PS2, legacy IRQ
  dispatch, and xHCI are named explicitly.

## Enhancement Priorities

## Priority 1 — MSI-X runtime validation on real devices

Goal: move MSI-X from “implemented abstraction” to “repeatedly proven behavior.”

Deliverables:

- explicit AMD GPU MSI-X validation notes
- explicit Intel GPU MSI-X validation notes
- verified fallback behavior to legacy IRQs when MSI-X is unavailable
- logged CPU/vector affinity behavior in real runs

Why first:

This is the lowest-level controller feature that already exists in the main runtime driver path and
blocks confidence in GPU/display work above it.

## Priority 2 — IOMMU hardware bring-up and fault-path validation

Goal: move IOMMU from spec-driven implementation to actual controller bring-up.

Deliverables:

- validated AMD-Vi daemon initialization on real hardware
- device table / command buffer / event log validation
- explicit interrupt-remapping validation notes
- negative-result documentation if hardware still fails

Why second:

It is the largest remaining low-level completeness gap, and it affects the safety and correctness of
userspace driver DMA.

## Priority 3 — IRQ quality-of-service and observability

Goal: make IRQ behavior easier to reason about in production.

Deliverables:

- better logging/telemetry around allocated IRQs and vectors
- explicit affinity-validation procedures
- measured notes on whether current userspace IRQ wait behavior is good enough for display/input
  latency needs

Why third:

This improves reliability without changing the underlying architecture.

## Priority 4 — input/controller runtime proof

Goal: continue turning the existing input substrate into a well-proven low-level controller path.

Deliverables:

- sustained validation of `inputd` → `evdevd` → consumer path
- documentation of real interrupt-backed input evidence, not only service existence
- explicit known limitations for consumer nodes and path expectations

Why fourth:

The architecture is there. What remains is proof quality.

## Priority 5 — timer/controller characterization

Goal: reduce uncertainty around HPET/APIC-timer behavior and controller assumptions.

Deliverables:

- a compact validation note for HPET behavior on real hardware
- notes on timer-controller assumptions and known limits

Why fifth:

Important, but less immediately blocking than MSI-X and IOMMU.

## Priority 6 — xHCI interrupt-path hardening

This is Priority 6 **within the low-level controller plan itself**, not within the repository-wide
subsystem order. At the repo-wide level, low-level controller quality remains ahead of USB/Wi-Fi/
Bluetooth because these later subsystems depend on the controller/runtime proof work documented
here.

Goal: keep USB host-controller operation on the restored interrupt-driven path and harden the proof
surface beyond the current narrow QEMU validation.

Deliverables:

- keep the actual `get_int_method` path in `xhcid` healthy
- validate MSI/MSI-X or INTx behavior for xHCI on real hardware and/or QEMU
- update docs so USB controller quality is not overstated while broader runtime and hardware
  validation remain open

Why sixth:

This remains a real completeness gap in an important low-level controller, but it is now narrower in
scope than the cross-cutting MSI-X and IOMMU priorities above because the interrupt path itself is
already restored and QEMU-proven.

## Execution Plan

### Step A — Establish validation vocabulary in all related docs

For every low-level controller area, use the same four states consistently:

- builds
- boots
- validated
- experimental

Do not mark controller infrastructure “complete” unless the claimed runtime behavior is actually
proven.

### Step B — Add dedicated validation notes for MSI-X and IOMMU

The project already has enough code to justify dedicated runtime-validation docs for:

- GPU MSI-X behavior
- IOMMU bring-up and fault handling

There is now also an in-tree generic MSI-X runtime proof helper:

- `local/scripts/test-msix-qemu.sh`

These should record both successful and failed hardware runs.

### Step C — Expand runtime-proof tooling where signal is weak

The project already has a good pattern for this in the Phase 3/4/5 validation helpers.

Use the same pattern for low-level controllers:

- one host-side launcher/check path
- one guest-side runtime check path
- one doc entry that records what “passing” actually means

### Step D — Keep the controller plan separate from higher-level desktop work

Do not let IRQ/IOMMU/controller planning get absorbed into generic Wayland/KDE roadmaps.

Controller quality must remain measurable at its own layer.

## Recommended New Documentation Work

The current project docs should eventually include dedicated runtime-validation companion documents
for:

- MSI-X validation
- IOMMU bring-up and fault validation
- timer/controller characterization
- input/controller runtime evidence

This document is the umbrella enhancement plan; those would be the execution/validation companions.

## Current Validation Entry Points

The following in-tree validation paths now exist and should be treated as the current controller
runtime-evidence surface:

- `local/scripts/test-xhci-irq-qemu.sh --check` — xHCI interrupt-mode proof from QEMU boot logs
- `local/scripts/test-msix-qemu.sh` — live MSI-X proof via `virtio-net`
- `local/scripts/test-iommu-qemu.sh --check` — AMD IOMMU device visibility plus guest boot reachability
- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn plus bounded sector-0 readback proof

## Bottom Line

Red Bear OS does **not** need a new IRQ/controller architecture.

It already has the correct architectural direction:

- scheme-based userspace IRQ delivery
- safe Rust driver wrappers
- PCI/MSI-X support
- IOMMU direction
- ACPI/APIC groundwork

What it needs now is disciplined completion work in this order:

1. MSI-X runtime proof
2. IOMMU hardware validation
3. IRQ observability and affinity proof
4. input/controller runtime evidence
5. timer/controller characterization

The main quality risk is no longer missing design. It is over-claiming readiness before low-level
controller runtime evidence exists.