Update ACPI and low-level controller docs

local/docs/ACPI-FIXES.md

@@ -9,8 +9,9 @@ Status of ACPI fixes for AMD bare metal boot. Cross-referenced with
 This file is the **historical P0 bring-up ledger**. The forward-looking ownership, robustness, and
 validation plan now lives in `local/docs/ACPI-IMPROVEMENT-PLAN.md`.
 
-P0 ACPI boot-baseline work is **materially complete**. Kernel patch is 574 lines, base/acpid patch
+P0 ACPI boot-baseline work is **materially complete for the historical boot goal**. It should not
-is 558 lines.
+be read as release-grade ACPI completeness; ownership cleanup, sleep-state support, and bounded
+bare-metal validation still remain open. Kernel patch is 574 lines, base/acpid patch is 558 lines.
 
 ## Crash Reports
 
@@ -46,7 +47,7 @@ access.
 | RSDT/XSDT | `acpi/rsdt.rs`, `acpi/xsdt.rs` | N/A | Root table pointer iteration + SDT checksum validation |
 | MADT (APIC) | `acpi/madt/` | N/A | xAPIC + x2APIC (type 0x9) + NMI (0x4, 0xA) + address override (0x5) |
 | HPET | `acpi/hpet.rs` | N/A | Assumes single HPET |
-| DMAR (Intel VT-d) | N/A | `acpi/dmar/` (present, not wired) | DMAR table parsing present in `dmar/mod.rs` but not initialized at acpid startup; effectively owned by `iommu` daemon. Iterator bug fixed, re-enabled, safe on AMD (early return) |
+| DMAR (Intel VT-d) | N/A | `acpi/dmar/` (present, not wired) | DMAR parsing code remains in `dmar/mod.rs` but is not initialized at `acpid` startup. Ownership is still transitional/orphaned from `acpid`, not cleanly transferred to a real Intel runtime owner. Iterator bug fixed, re-enabled, safe on AMD (early return) |
 | FADT | N/A | `acpi.rs` | Full: PM1a/b CNT, reset register, `\_S5` sleep types, GenericAddress I/O |
 | Power Methods | N/A | `acpi.rs` | `\_PS0`/`\_PS3`/`\_PPC` AML evaluation for device power control |
 | SPCR | `acpi/spcr.rs` | N/A | ARM64 serial console |
@@ -104,7 +105,7 @@ platforms, not just AMD.
 | `acpi.rs` | 643 | Handle SLP_TYPb for sleep states | Upstream | Mainline power management | Open (known gap) |
 | `aml_physmem.rs` | 418,423,428 | Mutex create/acquire/release | Upstream | Mainline AML interpreter | **Partially addressed** — real tracked state implemented, not placeholder |
 | `ec.rs` | 193+ (8 occurrences) | Proper error types | Upstream | Mainline EC handler | **Partially addressed** — widened accesses implemented via byte transactions |
-| `dmar/mod.rs` | 7 | Move DMAR to separate driver | Upstream | Mainline driver refactor | **Partially addressed** — DMAR module present but not wired into startup; effectively deferred to `iommu` daemon |
+| `dmar/mod.rs` | 7 | Move DMAR to separate driver | Upstream | Mainline driver refactor | **Partially addressed** — DMAR module present but not wired into startup; ownership remains transitional/orphaned rather than cleanly moved |
 | `main.rs` | — | Startup panic/expect handling | Local | Boot-path hardening | **Addressed** — typed `StartupError` enum with explicit error messages and clean exit paths |
 
 ## P0 Fixes Applied
@@ -137,7 +138,7 @@ platforms, not just AMD.
 |---|-----|-------------|
 | 1 | DMAR iterator fix | `type_bytes` renamed to `len_bytes` bug fix + `len < 4` guard |
 | 2 | DMAR init re-enabled | Safe on AMD (no DMAR table = early return, no crash) |
-| 3 | DMAR not wired into acpid startup | DMAR module present in `dmar/mod.rs` but not imported or called from `main.rs`; effectively deferred to `iommu` daemon ownership |
+| 3 | DMAR not wired into acpid startup | DMAR module present in `dmar/mod.rs` but not imported or called from `main.rs`; this removes active startup ownership from `acpid`, but does not yet establish a clean Intel runtime owner |
 | 4 | FADT shutdown | `acpi_shutdown()` using PM1a/PM1b CNT_BLK writes with `\_S5` sleep types |
 | 5 | FADT reboot | `acpi_reboot()` using ACPI reset register via GenericAddress |
 | 6 | Keyboard controller fallback | `Pio::<u8>::new(0x64).write(0xFE)` when reset_reg unavailable |

local/docs/ACPI-IMPROVEMENT-PLAN.md

@@ -1,383 +1,330 @@
 # Red Bear OS ACPI Improvement Plan
 
+## Truth Statement
+
+Red Bear ACPI is **boot-baseline complete for the historical P0 bring-up goal**, but it is **not
+release-grade complete**.
+
+What is real today:
+
+- kernel early discovery and MADT/xAPIC/x2APIC bring-up are in place,
+- `acpid` owns FADT shutdown/reboot, AML execution, DMI exposure, and ACPI power exposure,
+- IVRS/AMD-Vi ownership moved out of the broken `acpid` path and into `iommu`,
+- `kstop` shutdown eventing exists and is integrated with `redbear-sessiond`.
+
+What is still open:
+
+- sleep-state support beyond `\_S5`,
+- AML portability and runtime robustness on real firmware,
+- clean ownership boundaries across kernel / `acpid` / IOMMU,
+- bounded real-hardware validation on AMD, Intel, and at least one EC-backed platform.
+
+This document is therefore a **ULW execution plan** for turning the current ACPI stack from
+historical bring-up success into a subsystem that is honest, maintainable, and release-grade.
+
 ## Purpose
 
-This document turns the current ACPI assessment into a concrete execution plan.
+This plan does **not** replace `local/docs/ACPI-FIXES.md`.
 
-It does **not** replace `local/docs/ACPI-FIXES.md`. That file remains the historical record for the
+- `local/docs/ACPI-FIXES.md` remains the historical ledger for P0 ACPI bring-up and the current
-P0 bring-up work and the current table-by-table status snapshot. This document is the forward-looking
+  table-by-table implementation snapshot.
-plan for improving **completeness**, **robustness**, **ownership clarity**, **consumer integration**,
+- This file is the forward execution plan for closing the remaining ACPI gaps in correctness,
-and **validation quality**.
+  ownership clarity, consumer integration, and validation trust.
 
-The goal is not to treat ACPI as a generic checklist of table parsers. The goal is to make the Red
+The goal is not to maximize the number of parsed ACPI tables. The goal is to make the Red Bear ACPI
-Bear ACPI stack:
+stack:
 
-- correct enough to survive bad firmware,
+- correct under bad firmware,
-- clear enough that ownership boundaries stay maintainable,
+- explicit about who owns what,
-- observable enough that failures are diagnosable,
+- observable when it fails,
-- and validated enough that "complete" means more than "boots on one machine".
+- and validated enough that status claims are evidence-backed rather than inferred.
 
 ## Scope
 
-This plan covers the Red Bear ACPI stack and its direct dependency chain:
+This plan covers the Red Bear ACPI stack and its direct consumers:
 
-- kernel ACPI discovery and early table handling,
+- kernel ACPI discovery and early platform setup,
-- `acpid` as the main ACPI/AML/FADT/DMI/power daemon,
+- `acpid` as the main ACPI / AML / FADT / DMI / power daemon,
-- `iommu` as the IVRS/AMD-Vi runtime owner,
+- `iommu` as the IVRS / AMD-Vi runtime owner,
-- `pcid` / `/config` as the MCFG replacement path,
+- `pcid` and `/config` as the PCI config-space path replacing broken MCFG-in-`acpid` stubs,
 - DMI-backed quirks flowing through `acpid` and `redox-driver-sys`,
-- ACPI-consuming services such as `redbear-sessiond` and `redbear-info`.
+- ACPI consumers such as `redbear-sessiond`, `redbear-info`, and downstream services.
 
-Primary focus is the current x86_64 path, because that is the active Red Bear hardware target and the
+Primary focus is the current `x86_64` path. ARM64 remains in scope only where parser quality or
-area where the current implementation and validation debt is concentrated. ARM64 ACPI support remains
+kernel-ownership decisions are shared.
-in scope only where kernel ownership decisions or generic parser quality would affect it.
-
-## Evidence Model
-
-This plan uses five evidence buckets and does **not** treat them as equivalent:
-
-- **source-visible** — behavior is visible in the current checked-in source tree
-- **patch-carried** — behavior exists through `local/patches/*` rather than plain upstream source
-- **build-visible** — code compiles and stages successfully in the current build
-- **runtime-validated** — behavior has been exercised successfully in real boot/runtime paths
-- **negative-result-documented** — failure modes and platform gaps are recorded explicitly
-
-This matters because the current ACPI stack has already crossed the bring-up threshold, but still has
-meaningful gaps between **implemented**, **robust**, and **trusted**.
-
-## Ownership Model
-
-The long-term ownership split should be:
-
-- **Kernel ACPI** — minimum early discovery and unavoidable early platform setup
-- **`acpid`** — ACPI table serving, AML execution, FADT power/reboot logic, DMI exposure,
-  power-state exposure, ACPI table quirk filtering
-- **`iommu` daemon** — IVRS runtime parsing and AMD-Vi controller ownership
-- **future Intel IOMMU owner** — DMAR runtime handling, not `acpid`
-- **`pcid`** — PCI config space access replacing broken MCFG-in-acpid stubs
-- **consumers** — query ACPI-exposed services; do not parse ACPI firmware directly unless they are
-  the designated owner
-
-This ownership split is **not fully enforced today**. The plan below is designed to move the current
-tree from transitional ownership to explicit ownership without destabilizing the working bring-up
-path.
-
-## Current State Summary
-
-### What is strong today
-
-- Kernel RSDP/RSDT/XSDT/MADT handling exists and is sufficient for current boot bring-up.
-- `acpid` owns FADT parsing, AML integration, DMI exposure, and ACPI-backed power state exposure.
-- IVRS was correctly removed from the broken `acpid` stub path and moved to the `iommu` daemon.
-- MCFG ownership was correctly removed from `acpid` and replaced with the `pcid /config` path.
-- DMI-backed quirks are integrated through `/scheme/acpi/dmi` and `redox-driver-sys`.
-- `acpid` startup uses typed `StartupError` with explicit error messages and clean exit paths (Wave 1
-  boot-path hardening partially complete).
-- AML mutex state has real tracked implementation with handle-based acquire/release semantics in
-  `aml_physmem.rs` (Wave 2 AML mutex work partially complete).
-- EC access width is handled via `read_bytes`/`write_bytes` byte-transaction sequences for u16/u32/u64
-  accesses (Wave 2 EC width work partially complete).
-- DMAR table parsing module exists in `acpid` but is not wired into the startup path; DMAR ownership
-  is effectively deferred to the `iommu` daemon (Wave 3 DMAR separation partially complete).
-- Shutdown eventing uses `/scheme/kernel.acpi/kstop` as the kernel-to-userspace shutdown signal;
-  `redbear-sessiond` listens on this path for `PrepareForShutdown` D-Bus signals.
-- Kernel registers the `kstop` scheme at boot and ACPI subsystem shutdown uses PM1a/PM1b CNT writes
-  with `\_S5` sleep types.
-
-### What is still weak today
-
-- Sleep state transitions (`\_Sx` methods beyond `\_S5`) and sleep eventing remain unsupported; there is
-  no `/scheme/acpi/sleep` or event-driven sleep contract.
-- AML opregion error propagation still has some silent failure paths; not all correctness-critical
-  reads return error to caller.
-- `AmlSymbols` initialization order is still tied to PCI FD registration timing; AML initialization
-  is not fully deterministic.
-- `SLP_TYPb` handling remains unimplemented for sleep states beyond `\_S5`.
-- DMAR table parsing module is present but unused; the module itself has not been removed, creating
-  latent confusion about ownership.
-- Docs still risk equating "implemented" with "validated" without explicit evidence qualification.
-
-### Honest status statement
-
-Red Bear ACPI is **materially complete for the historical P0 boot goal**, but it is **not yet complete
-for robustness, ownership cleanliness, sleep state support, or broad platform confidence**. Sleep
-state eventing is a known gap. The shutdown eventing contract via `kstop` is implemented but only
-validated in QEMU; bare-metal validation is still outstanding.
 
 ## Canonical Related Documents
 
 Read these alongside this plan:
 
-- `local/docs/ACPI-FIXES.md` — current status ledger and historical P0 fixes
+- `local/docs/ACPI-FIXES.md`
-- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — controller-level validation and
+- `local/docs/BAREMETAL-LOG.md`
-  quality context
+- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`
-- `local/docs/IOMMU-SPEC-REFERENCE.md` — IVRS/DMAR technical reference
+- `local/docs/IOMMU-SPEC-REFERENCE.md`
-- `local/docs/QUIRKS-SYSTEM.md` — DMI-backed quirks and ACPI table blacklist behavior
+- `local/docs/QUIRKS-SYSTEM.md`
-- `local/docs/AMD-FIRST-INTEGRATION.md` — historical AMD-first framing and hardware context
+- `docs/02-GAP-ANALYSIS.md`
-- `local/docs/BAREMETAL-LOG.md` — real-machine failure notes and negative results
 
-## Work Classification
+## Evidence Model
 
-Every task in this plan is tagged by its main purpose:
+This plan uses five evidence buckets and does **not** treat them as equivalent:
 
-- **Completeness** — functionality exists but is still missing or partial
+- **source-visible** — behavior is visible in the checked-in source tree
-- **Robustness** — behavior exists but is too fragile under bad firmware or runtime stress
+- **patch-carried** — behavior exists through `local/patches/*`
-- **Quality** — ownership, observability, maintainability, or docs are below target
+- **build-visible** — code compiles and stages in the current build
+- **runtime-validated** — behavior has been exercised successfully in boot or runtime
+- **negative-result-documented** — failures and platform gaps are explicitly recorded
+
+This distinction matters because the current ACPI stack has already crossed the bring-up threshold,
+but still has meaningful distance between **implemented**, **robust**, and **trusted**.
+
+## Status Vocabulary
+
+All ACPI status claims in Red Bear docs should use one of these meanings:
+
+- **implemented** — present in code today
+- **validated in QEMU** — exercised in QEMU / OVMF only
+- **validated on bounded real hardware** — proven on named tested hardware only
+- **transitional** — exists, but ownership or architecture is still not clean
+- **known gap** — absent, incomplete, or intentionally deferred and documented
+
+Do **not** use a bare “complete” claim without also saying whether it means boot-baseline,
+bounded-hardware, or release-grade completeness.
+
+## Current State Summary
+
+### Strong today
+
+- Kernel RSDP / RSDT / XSDT / MADT handling is sufficient for current boot bring-up.
+- `acpid` owns FADT parsing, AML integration, DMI exposure, and ACPI-backed power-state exposure.
+- `acpid` startup uses typed `StartupError` and clean exits for several boot-critical failure paths.
+- AML mutex state is real-tracked in `aml_physmem.rs`, not placeholder-only.
+- EC width access is implemented via byte-transaction sequences for widened reads and writes.
+- IVRS ownership was removed from the broken `acpid` stub path and moved into the `iommu` daemon.
+- MCFG handling was removed from `acpid` and replaced with the `pcid /config` path.
+- Shutdown eventing via `/scheme/kernel.acpi/kstop` is implemented and consumed by
+  `redbear-sessiond`.
+
+### Weak today
+
+- Sleep-state transitions beyond `\_S5` are unsupported.
+- Sleep eventing is unsupported.
+- `SLP_TYPb` remains incomplete for broader sleep-state handling.
+- AML init order is still tied to PCI FD registration timing.
+- Some physmem / opregion failure paths are still not explicit enough.
+- DMAR remains orphaned in `acpid` source: present, not wired, not fully transferred.
+- Repo status language can still blur “implemented” vs “validated”.
+- Bare-metal validation is too thin to justify release-grade claims.
+
+## Ownership Model
+
+The long-term ownership split should be:
+
+| Component | Intended owner | Current status |
+|---|---|---|
+| RSDP / RSDT / XSDT early discovery | Kernel | implemented |
+| MADT / HPET / early unavoidable platform setup | Kernel | implemented, broader scope still transitional |
+| FADT parsing, `\_S5`, PM register writes, reboot | `acpid` | implemented |
+| AML execution and opregion handling | `acpid` | implemented, robustness still partial |
+| DMI exposure and ACPI power surfaces | `acpid` | implemented |
+| IVRS / AMD-Vi runtime handling | `iommu` | implemented |
+| DMAR / Intel VT-d runtime handling | future Intel IOMMU owner | transitional / not fully assigned |
+| PCI config-space access | `pcid` | implemented |
+| ACPI consumers | downstream services | should consume ACPI-owned surfaces, not firmware directly |
+
+Important ownership truth:
+
+- **DMAR is not cleanly transferred today.**
+- The `acpi/dmar/mod.rs` module still exists inside `acpid` source, but is not wired into startup.
+- `iommu` is the real IVRS runtime owner today.
+- Do **not** describe Intel DMAR ownership as fully complete until the orphaned `acpid` carrier is
+  removed or a real Intel runtime owner is implemented and validated.
+
+## Degraded-Mode Contract
+
+The ACPI stack must distinguish between **fatal**, **degradable**, and **out-of-scope** failures.
+
+| Condition | Expected behavior today | Classification |
+|---|---|---|
+| ACPI absent / empty root table | `acpid` exits cleanly without ACPI services | degradable |
+| Bad SDT checksum | warn, continue best-effort where supported | degradable |
+| Bad table length / malformed table | behavior varies too much today; must be normalized | open contract |
+| AML init failure | `acpid` exits, ACPI scheme unavailable | currently fatal |
+| EC timeout | AML error path should surface failure, not fabricate success | degradable |
+| Missing `\_S5` | shutdown path cannot use PM registers | degradable if fallback exists |
+| Sleep-state transition request | unsupported today | known gap |
+| Missing `kstop` path | no kernel-orchestrated shutdown event contract | fatal for that integration path |
+| Missing DMAR on Intel | no Intel VT-d runtime | degradable for non-IOMMU boot |
+| Missing IVRS on AMD | no AMD-Vi runtime | degradable for non-IOMMU boot |
+
+Wave 1 must convert the still-fuzzy cases into explicit, table-specific policy.
+
+## ULW Execution Rules
+
+These rules govern all work from this plan:
+
+1. **No hidden status inflation.** Status words must match evidence.
+2. **No ownership moves without a handoff contract.** “Not wired” is not the same as “cleanly moved.”
+3. **No validation laundering.** QEMU success is not bare-metal success.
+4. **No Wave 5 shortcuts.** Validation cannot substitute for unfinished architecture.
+5. **No cross-wave dependency drift.** Later waves must not silently depend on work that was never
+   formalized in earlier waves.
 
 ## Wave 0 — Contracts, truthfulness, and degraded-mode policy
 
 ### Goal
 
-Stop treating ACPI as a loose cluster of working code and instead define:
+Establish one canonical answer to:
 
 1. who owns what,
-2. which failures are fatal versus degradable,
+2. what counts as degraded but acceptable,
-3. and what status words in the docs actually mean.
+3. and what ACPI status words mean.
 
 ### Why this wave is first
 
-Without an explicit contract, later hardening work turns into hidden rewrites and docs drift.
+Without a contract, all later hardening work turns into undocumented rewrites and docs drift.
 
-### Scope
+### Primary files
 
 - `local/docs/ACPI-FIXES.md`
-- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`
 - this file
-- related references in `README.md`, `docs/02-GAP-ANALYSIS.md`, and `AGENTS.md` if needed
+- `docs/02-GAP-ANALYSIS.md`
+- `README.md` and related status surfaces if needed
 
-### Status: Wave 0 execution partially complete
+### Dependencies
 
-Tasks 0.1, 0.2, and 0.3 are partially executed in this documentation pass. The degraded-mode matrix
+- none
-and normalized vocabulary are new in this pass. Ownership boundaries are partially documented below;
-the canonical statement still lives in `local/docs/ACPI-FIXES.md`.
 
-### Vocabulary normalization (Task 0.2 — partially executed)
+### Deliverables
 
-Replace ambiguous wording such as "complete" with one of:
+- one normalized ACPI vocabulary,
+- one degraded-mode contract,
+- one canonical ownership statement,
+- removal of doc language that implies subsystem completeness without evidence.
 
-- **implemented** — behavior exists in the current source tree
+### Verification
-- **validated in QEMU** — behavior has been exercised in QEMU/OVMF but not on real hardware
-- **validated on bounded real hardware** — behavior verified on specific hardware that was tested
-- **still transitional** — behavior exists but ownership or robustness is not yet clean
-- **known gap** — functionality is absent or broken; the gap is documented
 
-### ACPI degraded-mode matrix (Task 0.1 — new)
+- documentation review only,
+- no contradictory ownership claims across ACPI docs,
+- no bare “complete” wording without scope.
 
-This matrix documents the expected system behavior for ACPI failure cases. All entries reflect
+### Exit criteria
-implemented behavior visible in the current source tree.
 
-| Condition | Kernel behavior | Userspace (`acpid`) behavior | Session impact |
+- one canonical ownership statement exists,
-|-----------|----------------|----------------------------|----------------|
+- one degraded-mode matrix exists,
-| Bad RSDP checksum | Warns, continues with best-effort RSDP parse | No ACPI init if RSDT/XSDT unreadable; exits cleanly | No ACPI services |
+- all top-level ACPI docs use the same vocabulary.
-| Bad SDT checksum | Logs warning per table, continues | Table skipped; other tables still served | Reduced ACPI surface |
-| Truncated FADT | FADT fields fall back to zero defaults | Uses zero defaults for PM registers; `acpi_shutdown` may not fire | Shutdown may fall back to keyboard controller |
-| Truncated DMAR | N/A (DMAR not used by kernel) | Logs error, continues without DMAR; `iommu` daemon not started | No Intel IOMMU via DMAR |
-| Truncated IVRS | N/A (IVRS not used by kernel) | No effect on `acpid` (IVRS owned by `iommu` daemon) | No AMD-Vi via IVRS |
-| AML interpreter init failure | N/A | `acpid` exits with typed error; no ACPI scheme | No AML, no power methods |
-| EC timeout | N/A | Returns `AmlError::MutexAcquireTimeout` to AML interpreter | AML opregion access fails gracefully |
-| EC unsupported width access | N/A | Wider accesses split into byte transactions via `read_bytes`/`write_bytes` | Works on byte-access ECs only |
-| Missing DMAR on Intel | N/A | `acpid` logs DMAR absent; `iommu` daemon not started | No Intel VT-d |
-| Missing IVRS on AMD | N/A | No effect (IVRS owned by `iommu` daemon) | No AMD-Vi |
-| Missing `\_S5` sleep types | N/A | `acpi_shutdown` logs error and returns without writing PM registers | Shutdown may fall back to keyboard controller |
-| Missing `/scheme/kernel.acpi/kstop` | Kernel does not register kstop scheme | `acpid` exits with error on startup | No kernel-orchestrated shutdown |
-| Sleep state transition (`\_Sx`) | N/A | Not implemented; no event-driven sleep contract | Sleep states not available |
-| `redbear-sessiond` shutdown watcher | Kernel signals `kstop` on shutdown | `acpi_watcher.rs` reads kstop and emits D-Bus `PrepareForShutdown` | Login1 session manager informed |
 
-### Ownership boundaries (Task 0.3 — partially documented)
+### Current status
 
-This section documents the current ownership split as visible in the source tree. Items marked
+- partially complete
-**transitional** indicate the ownership boundary is not yet fully enforced by code.
-
-| Component | Owner | Status |
-|-----------|-------|--------|
-| Early table discovery (RSDP, RSDT, XSDT) | Kernel | implemented |
-| MADT, HPET, SPCR, GTDT parsing | Kernel | implemented |
-| FADT parsing, `\_S5` sleep types, PM registers | `acpid` | implemented |
-| AML interpreter initialization and execution | `acpid` | implemented |
-| EC access (byte-wide and widened via byte transactions) | `acpid` | implemented |
-| AML mutex state tracking | `acpid` (`aml_physmem.rs`) | implemented (real tracked state, not placeholder) |
-| FADT shutdown/reboot via PM1a/PM1b CNT | `acpid` | implemented |
-| Keyboard controller fallback reboot | `acpid` | implemented |
-| DMAR table parsing | `acpid` (module present) | **transitional** — module not wired; effectively owned by `iommu` daemon |
-| IVRS ownership | `iommu` daemon | implemented |
-| MCFG/PCI config space | `pcid` `/config` endpoint | implemented |
-| DMI exposure and quirks | `acpid` via `/scheme/acpi/dmi` | implemented |
-| Power methods (`\_PS0`/`\_PS3`/`\_PPC`) | `acpid` | implemented |
-| Sleep state transitions (`\_Sx` beyond `\_S5`) | none | **known gap** |
-| Sleep eventing | none | **known gap** |
-| Shutdown event via `kstop` | Kernel + `acpid` + `redbear-sessiond` | implemented (QEMU-validated; bare-metal validation outstanding) |
-| DMAR runtime ownership (Intel VT-d) | `iommu` daemon | **transitional** — not yet fully separated from `acpid` DMAR module |
-
-### Acceptance criteria
-
-- one canonical ownership statement exists — **partially met** (this table, plus `ACPI-FIXES.md`)
-- one degraded-mode matrix exists — **met** (this pass)
-- all high-level ACPI status claims use the same vocabulary — **partially met** (normalized in this pass)
-
-### Validation
-
-- doc review only,
-- no code changes required for vocabulary and matrix,
-- Wave 0 should be treated as ongoing; new evidence may require matrix updates
 
 ## Wave 1 — Boot-path hardening and parser strictness
 
 ### Goal
 
-Remove catastrophic or silent failure behavior from the boot-critical ACPI path.
+Remove catastrophic or silent failure behavior from boot-critical ACPI initialization.
 
-### Main files
+### Primary files
 
 - `recipes/core/base/source/drivers/acpid/src/main.rs`
 - `recipes/core/base/source/drivers/acpid/src/acpi.rs`
 - `recipes/core/base/source/drivers/acpid/src/scheme.rs`
 - `recipes/core/kernel/source/src/acpi/mod.rs`
-- kernel ACPI submodules for RSDP/RSDT/XSDT/MADT/HPET/SPCR/GTDT
+- kernel ACPI submodules as needed
 
-### Status: Task 1.1 partially executed
+### Dependencies
 
-`acpid` main.rs now uses a typed `StartupError` enum covering:
+- Wave 0 ownership and degraded-mode vocabulary in place
 
-- `ReadRootTable` — failed to read `/scheme/kernel.acpi/rxsdt`
+### Deliverables
-- `ParseRootTable` — failed to parse `[R|X]SDT`
-- `UnexpectedRootTableSignature` — wrong root table signature
-- `MalformedRootTableEntries` — malformed entry area
-- `InitializeAcpi` — failed ACPI context init
-- port I/O rights acquisition failure
-- shutdown pipe open failure (`/scheme/kernel.acpi/kstop`)
-- event queue creation failure
-- scheme socket creation failure
-- event queue subscription failure
-- scheme registration failure
 
-Each failure path logs a human-readable error and calls `std::process::exit(1)`. No `panic!`
+- startup paths are typed and explicit,
-remains on these paths. Empty RSDT (no ACPI) causes a clean `exit(0)` after `daemon.ready()`.
+- table rejection policy is documented per table class,
+- parser observability is strong enough to reconstruct failures,
+- degraded boot succeeds for all conditions classified as degradable.
 
-Tasks 1.2 and 1.3 remain open.
+### Specific tasks
 
-### Tasks
+1. Finish replacing panic-grade startup behavior in active firmware-origin paths.
+2. Define table-specific reject / warn / degrade / fail rules.
+3. Log accepted and rejected tables with enough evidence to debug failures.
 
-#### Task 1.1 — Replace panic-grade startup failures in `acpid` — **partially done**
+### Verification
 
-Typed `StartupError` enum is implemented in `main.rs`. The following failure classes are now handled:
+- malformed checksum / truncated-length tests,
-
-- hard fail with typed error message and exit code 1,
-- soft fail with degraded behavior (ACPI absent → clean exit 0),
-- or early clean exit when `/scheme/kernel.acpi/rxsdt` is empty.
-
-#### Task 1.2 — Make table rejection policy explicit — **open**
-
-For kernel and `acpid` table use, define when a bad length/checksum/revision:
-
-- is logged and ignored,
-- is logged and downgraded,
-- or is fatal.
-
-This policy must be table-specific, not one global "warn and continue" convention.
-
-#### Task 1.3 — Improve parser observability — **open**
-
-Every accepted or rejected table should leave enough evidence to reconstruct why:
-
-- table signature,
-- physical address if known,
-- length/revision/checksum status,
-- consumer that requested it,
-- fallback path chosen.
-
-### Acceptance criteria
-
-- no `panic!/expect()` remains on firmware-origin or optional-service startup paths in `acpid` — **partially met** (Tasks 1.2 and 1.3 still open),
-- malformed-table decisions are deterministic and documented — **open**,
-- degraded boot still succeeds in all cases classified as degradable by Wave 0 — **open**.
-
-### Validation
-
-- negative tests for malformed checksums and table lengths,
 - QEMU validation with intentionally damaged tables if feasible,
-- one AMD and one Intel bounded hardware boot recheck,
+- one bounded AMD hardware boot recheck,
-- evidence captured in `local/docs/BAREMETAL-LOG.md` or a successor log.
+- one bounded Intel hardware boot recheck,
+- evidence captured in `local/docs/BAREMETAL-LOG.md` or its successor.
+
+### Exit criteria
+
+- no unjustified `panic!/expect()` remains on firmware-origin startup paths,
+- malformed-table decisions are deterministic and documented,
+- degraded boot behavior matches Wave 0 classification.
+
+### Current status
+
+- partially complete
 
 ## Wave 2 — AML, opregions, EC, and power-state correctness
 
 ### Goal
 
-Close the biggest runtime-correctness gaps in the ACPI stack.
+Close the biggest runtime-correctness gaps in the `acpid` layer.
 
-### Main files
+### Primary files
 
 - `recipes/core/base/source/drivers/acpid/src/acpi.rs`
 - `recipes/core/base/source/drivers/acpid/src/aml_physmem.rs`
 - `recipes/core/base/source/drivers/acpid/src/ec.rs`
 
-### Status: Tasks 2.1, 2.2, and 2.5 partially executed
+### Dependencies
 
-#### Task 2.1 — Remove placeholder AML mutex behavior — **partially done**
+- Wave 1 startup paths hardened enough that runtime work is not sitting on a fragile base
 
-`AmlMutexState` in `aml_physmem.rs` implements real tracked state:
+### Deliverables
 
-- `AmlMutexState::create_handle()` generates unique handles via incrementing `next_handle`
+- real AML synchronization semantics,
-- `AmlMutexState::states` is a `FxHashMap<Handle, bool>` tracking locked/unlocked state
+- explicit physmem / opregion failure behavior,
-- `lock_aml_mutexes()` wraps the state map with proper `Mutex` guard and poisoned-state recovery
+- deterministic AML init order,
-- The `acquire()` method looks up the handle in the map, sets it to `true` on success, and returns
+- explicit sleep-state scope,
-  `AmlError::MutexAcquireTimeout` on timeout or unknown handle
+- honest EC behavior bounds.
 
-This is no longer a placeholder implementation. Remaining work: timeout semantics documentation
+### Specific tasks
-and concurrent acquire/release stress testing.
 
-#### Task 2.2 — Eliminate silent zero-on-failure physical reads — **partially done**
+1. Document and stress AML mutex timeout semantics.
+2. Remove silent correctness-critical physmem failure paths.
+3. Finish `AmlSymbols` initialization contract; stop tying AML readiness to fragile PCI timing.
+4. Decide whether sleep support is in-scope now or explicitly deferred.
+5. If in-scope now, implement and validate the missing sleep-state pieces, including `SLP_TYPb`.
 
-EC reads via `read_bytes` now propagate `AmlError::MutexAcquireTimeout` on EC timeout rather than
+### Verification
-returning zero. Kernel-physmem reads still have some silent failure paths; this task is not fully
-closed.
-
-#### Task 2.5 — Decide and validate EC width behavior — **partially done**
-
-`ec.rs` now implements `read_u16`, `read_u32`, `read_u64`, `write_u16`, `write_u32`, and `write_u64`
-on `Ec` via byte-transaction sequences in `read_bytes`/`write_bytes`:
-
-- `ensure_access()` validates the access fits in a u8 addressable range
-- `read_bytes<const N: usize>` loops over individual byte reads with timeout per byte
-- `write_bytes()` loops over individual byte writes with timeout per byte
-
-Wider accesses are emulated through byte transactions rather than being rejected. This is implemented
-behavior, not a placeholder. Validation on real EC hardware remains outstanding.
-
-### Tasks still open
-
-#### Task 2.3 — Finish `AmlSymbols` initialization contract — **open**
-
-`AmlSymbols` initialization order is still tied to PCI FD registration timing. AML initialization
-is not fully deterministic. The upstream TODO to "use these parsed tables for the rest of acpid"
-remains.
-
-#### Task 2.4 — Fix power-state completeness gaps — **open**
-
-`SLP_TYPb` handling remains unimplemented. Sleep state transitions beyond `\_S5` are not supported.
-Sleep eventing is not implemented. These are documented as known gaps.
-
-### Acceptance criteria
-
-- AML synchronization is no longer placeholder-driven — **partially met** (2.1 done; 2.3 open),
-- physmem failures do not silently fabricate correctness-critical values — **partially met** (EC done; kernel-physmem still open),
-- AML initialization order is reproducible and documented — **open** (Task 2.3),
-- sleep-state handling is explicit for both implemented and out-of-scope states — **open** (Task 2.4),
-- EC behavior is either implemented or honestly bounded — **met** (byte transactions for wider widths)
-
-### Validation
 
 - targeted AML method execution tests,
-- shutdown/reboot proof on QEMU and bounded real hardware,
+- shutdown / reboot proof in QEMU and bounded hardware,
-- EC timeout/error-path tests where possible,
+- EC timeout and error-path tests,
-- concurrent ACPI scheme reads while AML methods run.
+- concurrent ACPI scheme reads while AML methods run,
+- at least one EC-backed platform check if available.
 
-## Wave 3 — Ownership cleanup: reduce kernel ACPI scope and remove DMAR from `acpid`
+### Exit criteria
+
+- AML synchronization is no longer placeholder-grade,
+- physmem failures do not silently fabricate correctness-critical values,
+- AML initialization order is reproducible and documented,
+- sleep-state handling is either implemented or explicitly bounded as a known gap,
+- EC behavior is implemented or honestly constrained.
+
+### Current status
+
+- partially complete
+
+## Wave 3 — Ownership cleanup and kernel-surface reduction
 
 ### Goal
 
-Move from transitional ownership to architecture that is easier to maintain.
+Move from transitional ownership to an architecture that can survive long-term maintenance.
 
-### Main files
+### Primary files
 
 - `recipes/core/kernel/source/src/acpi/mod.rs`
 - kernel ACPI submodules as needed
@@ -385,203 +332,239 @@ Move from transitional ownership to architecture that is easier to maintain.
 - `recipes/core/base/source/drivers/acpid/src/scheme.rs`
 - `local/recipes/system/iommu/source/src/*`
 
-### Status: Tasks 3.1 and 3.2 partially executed
+### Dependencies
 
-#### Task 3.1 — Define the minimum kernel ACPI surface — **open**
+- Wave 1 and Wave 2 are at least partially complete
 
-The kernel still carries TODOs for kernel ACPI scope reduction. No staged migration contract has
+### Deliverables
-been written yet.
 
-#### Task 3.2 — Move DMAR to the correct owner — **partially done**
+- a minimum kernel ACPI contract,
+- explicit handoff paths for table discovery and topology,
+- DMAR no longer orphaned in `acpid`,
+- ownership wording that matches the code.
 
-The `acpi/dmar/mod.rs` module remains present in `acpid` source but is not imported or called from
+### Specific tasks
-`main.rs` startup. The DMAR parsing code itself is not executed at daemon startup. However, the
-module has not been removed from the source tree, creating latent confusion about ownership.
 
-The `iommu` daemon is responsible for IVRS/DMAR runtime handling. DMAR is not initialized by
+1. Define the minimum kernel ACPI surface that must remain in early boot.
-`acpid`. The exit path from `acpid` for DMAR is therefore effectively achieved, but the cleanup
+2. Document the userspace handoff contract for topology and table consumers.
-(task: remove the unused module or move it to the `iommu` crate) is not complete.
+3. Remove or relocate the orphaned DMAR carrier in `acpid`.
+4. Do not claim Intel DMAR runtime ownership complete unless a real owner exists and is validated.
 
-#### Task 3.3 — Ensure handoff paths are explicit — **open**
+### Verification
 
-Handoff paths for table discovery and CPU/topology are not yet documented as a staged migration
+- before / after boot regressions,
-contract.
+- Intel-specific validation for any DMAR ownership move,
+- AMD regression checks showing IVRS ownership remains isolated in `iommu`.
 
-### Acceptance criteria
+### Exit criteria
 
-- the minimal kernel ACPI contract is written down — **open**,
+- the minimum kernel ACPI contract is written down,
-- DMAR has a concrete exit path from `acpid` — **partially met** (not wired; module still present),
+- DMAR has a concrete, non-ambiguous owner or is explicitly deferred,
-- ownership reductions are staged and do not break current bring-up — **open**
+- ownership reductions do not regress current bring-up.
 
-### Validation
+### Current status
 
-- before/after boot regressions,
+- partially complete
-- Intel-specific validation for DMAR path changes,
-- AMD regression checks proving IVRS ownership remains isolated in `iommu`.
 
 ## Wave 4 — Consumer integration and eventing quality
 
 ### Goal
 
-Make ACPI consumers correct and low-friction, not just functional.
+Make ACPI consumers correct, observable, and low-friction.
 
-### Main files
+### Primary files
 
 - `local/recipes/system/redbear-sessiond/source/src/acpi_watcher.rs`
 - `recipes/core/base/source/drivers/acpid/src/scheme.rs`
-- DMI/quirk consumers under `redox-driver-sys` and reporting surfaces
+- DMI / quirk consumers in `redox-driver-sys`
+- reporting surfaces such as `redbear-info`
 
-### Status: Task 4.1 partially executed; sleep eventing still a gap
+### Dependencies
 
-#### Task 4.1 — Replace polling-based ACPI state consumption — **partially done**
+- Wave 2 runtime behavior is stable enough for downstream consumers to depend on it
 
-Shutdown eventing is now event-driven via `/scheme/kernel.acpi/kstop`:
+### Deliverables
 
-- `acpid` opens `kstop` at startup and subscribes to it via `RawEventQueue`
+- event-driven core power-session behavior where feasible,
-- When the kernel triggers shutdown, `acpid` receives an event on the `kstop` file descriptor
+- bounded DMI quirk authority,
-- `redbear-sessiond`'s `acpi_watcher.rs` opens `kstop` and reads one byte in a blocking
+- operator-facing observability strong enough to diagnose behavior,
-  `spawn_blocking` call, then emits D-Bus `PrepareForShutdown(true)` signal
+- explicit treatment of unsupported sleep eventing if it remains deferred.
 
-Sleep eventing (`\_Sx` transitions) remains unsupported. There is no `/scheme/acpi/sleep` surface
+### Specific tasks
-and no event-driven sleep contract. This is a known gap.
 
-#### Task 4.2 — Bound DMI quirk authority — **open**
+1. Keep shutdown eventing on `kstop` as the canonical shutdown signal.
+2. Improve consumer-facing observability for ACPI state and failures.
+3. Define DMI quirk precedence and limits.
+4. If sleep eventing remains out-of-scope, document that explicitly and consistently.
 
-#### Task 4.3 — Improve operator-facing observability — **open**
+### Verification
 
-### Acceptance criteria
+- repeated shutdown edge tests,
-
+- sleep-edge tests if sleep work is in scope,
-- no periodic polling remains for core ACPI power/session transitions if eventing is feasible — **partially met** (shutdown done; sleep still polling/absent),
-- quirk precedence is documented — **open**,
-- consumer-visible behavior is diagnosable from logs and status outputs — **open**
-
-### Validation
-
-- repeated shutdown/sleep edge tests,
 - DMI quirk application checks on known systems,
 - race checks with multiple simultaneous consumers of `/scheme/acpi/*`.
 
-## Wave 5 — Validation closure and release gate
+### Exit criteria
+
+- no unnecessary polling remains for core ACPI transitions where eventing is feasible,
+- quirk precedence is documented,
+- consumer-visible behavior is diagnosable from logs and status outputs.
+
+### Current status
+
+- partially complete
+
+## Wave 5 — Validation closure and release gates
 
 ### Goal
 
-Convert the current implementation from bring-up evidence into release-grade trust.
+Turn the current ACPI stack from bring-up evidence into release-grade trust.
 
-### Validation matrix
+### Dependencies
 
-At minimum, require:
+- Waves 1 through 4 have produced stable behavior worth validating
 
-- QEMU/OVMF boot with ACPI active,
+### Required validation matrix
-- modern AMD hardware,
+
-- modern Intel hardware,
+At minimum:
+
+- QEMU / OVMF boot with ACPI active,
+- one modern AMD machine,
+- one modern Intel machine,
 - one platform that exercises EC-backed AML behavior,
 - malformed-table or degraded-mode evidence where feasible.
 
-### Tasks
+### Deliverables
 
-#### Task 5.1 — Publish a platform matrix
+- a bounded platform matrix,
+- negative-result capture,
+- explicit release gates for both boot-baseline and full ACPI claims,
+- docs that distinguish implemented from validated.
 
-For each validated platform, record:
+### Specific tasks
 
-- firmware mode,
+1. Publish the platform matrix in `local/docs/BAREMETAL-LOG.md` or its successor.
-- key ACPI tables detected,
+2. Record for each platform: firmware mode, key ACPI tables, APIC mode, shutdown / reboot,
-- APIC mode,
+   DMI / power exposure, AML / EC failures, and notable degraded behavior.
-- whether shutdown/reboot worked,
+3. Preserve negative results such as unsupported AML opcodes or platform-specific regressions.
-- whether DMI and power exposure worked,
+4. Require evidence before any stronger ACPI completeness claim is made.
-- whether any AML/EC failure was observed.
 
-#### Task 5.2 — Capture negative results
+### Verification
 
-Do not hide unsupported AML opcodes, partial EC behavior, or platform-specific regressions behind a
+- repeated QEMU proof,
-generic "works on tested hardware" label.
+- bounded repeated bare-metal proof on AMD and Intel,
+- one EC-heavy platform check,
+- cross-check docs so claims match recorded evidence.
 
-#### Task 5.3 — Define the ACPI release gate
+### Exit criteria
 
-Before calling ACPI complete for current Red Bear goals, require:
+- one bounded but honest platform matrix exists,
-
-- clean boot on the bounded matrix,
-- explicit degraded-mode behavior for known bad firmware cases,
-- documented ownership state,
-- and current docs that distinguish implemented vs validated.
-
-### Acceptance criteria
-
-- one bounded but honest validation matrix exists,
 - negative results are documented,
-- ACPI status claims are tied to explicit evidence rather than inference.
+- ACPI status claims are tied to explicit evidence,
+- release gates are defined and followed.
+
+### Current status
+
+- open
+
+## Release Gates
+
+### Gate A — Boot-Baseline ACPI Ready
+
+This is the strongest claim the repo can make before sleep and broader ownership cleanup are done.
+
+Require:
+
+- clean boot on bounded QEMU + AMD + Intel validation targets,
+- working MADT / APIC initialization on those targets,
+- shutdown / reboot proof where supported,
+- explicit degraded behavior for known firmware-bad cases,
+- current docs that distinguish implemented from validated.
+
+### Gate B — Full ACPI / Power-Management Ready
+
+Do **not** claim this until all of the following are true:
+
+- AML runtime behavior is stable across the bounded matrix,
+- sleep-state scope is implemented and validated or explicitly excluded from the release claim,
+- ownership boundaries are clean rather than merely transitional,
+- consumer integration is observable and race-bounded,
+- the platform matrix supports the stronger claim.
 
 ## Upstream vs Red Bear Work Split
 
-### Upstream-first work
+### Prefer upstream for
 
-These are generic ACPI correctness or architecture issues and should be solved upstream whenever
+- generic `acpid` startup hardening,
-possible, with temporary Red Bear patch carriers only if necessary:
+- AML mutex semantics,
+- `SLP_TYPb` completion,
+- EC error typing and generic width behavior,
+- reuse of parsed tables inside `acpid`,
+- DMAR leaving `acpid`,
+- kernel ACPI scope reduction TODOs,
+- generic parser quality in kernel ACPI modules.
 
-- `acpid` startup hardening
+### Red Bear owns
-- AML mutex semantics in `aml_physmem.rs`
-- `SLP_TYPb` completion
-- EC error typing and possibly EC access-width handling
-- using parsed tables for the rest of `acpid`
-- DMAR leaving `acpid`
-- kernel ACPI scope reduction TODOs
-- generic parser quality for kernel ACPI modules
 
-### Red Bear-owned work
+- honest status language,
-
+- bounded validation matrices and runbooks,
-These remain Red Bear responsibilities even if upstream code improves:
+- `redbear-sessiond` shutdown-consumer quality,
-
+- DMI quirk governance and integration policy,
-- honest status/phase documentation
+- patch carriers in `local/patches/*`,
-- bounded validation matrix and operator runbooks
+- coordination across `acpid`, `iommu`, `pcid`, and downstream consumers.
-- `redbear-sessiond` event consumption quality
-- DMI quirk governance and integration policy
-- temporary durable patch carriers in `local/patches/*`
-- coordination between `acpid`, `iommu`, `pcid`, and downstream consumers
 
 ## Sequencing Constraints
 
-1. **Wave 0 must come first** so later changes do not drift architecturally.
+1. **Wave 0 first** — architecture and wording must stop drifting.
-2. **Wave 1 must come before Wave 2** so runtime correctness sits on a hardened startup path.
+2. **Wave 1 before Wave 2** — runtime correctness should not sit on fragile startup behavior.
-3. **Wave 2 should come before Wave 4** because consumer contracts should depend on correct AML and
+3. **Wave 2 before Wave 4** — consumer contracts must rely on correct AML / power behavior.
-   power behavior.
+4. **Wave 3 after Waves 1 and 2 are partially stable** — ownership moves are risky on unstable
-4. **Wave 3 should not start until Waves 1 and 2 are at least partially complete**; ownership moves
+   behavior.
-   are dangerous if the runtime behavior is still fragile.
+5. **Wave 5 last** — validation closes work; it does not replace architecture.
-5. **Wave 5 closes the work**; it must not be used as a substitute for architecture.
 
 ## Main Risks
 
-- stricter parser/error handling may expose machines that currently boot only by luck,
+- stricter parser behavior may expose machines currently booting only by luck,
-- AML/EC changes may uncover hidden ordering assumptions with PCI registration,
+- AML / EC changes may uncover hidden PCI-registration ordering assumptions,
-- reducing kernel ownership too early may regress early platform bring-up,
+- reducing kernel scope too early may regress early bring-up,
-- moving DMAR out of `acpid` may create Intel-only regressions if the replacement contract is vague,
+- careless DMAR cleanup may create Intel-only regressions,
-- DMI quirks can become a crutch if they are allowed to override runtime facts indiscriminately.
+- DMI quirks can become a crutch if allowed to override runtime facts indiscriminately.
+
+## Non-Goals
+
+- claiming sleep support that does not exist,
+- calling DMAR ownership “complete” while the orphaned `acpid` module still exists,
+- treating one-machine success as subsystem-level proof,
+- using Wave 5 validation language to hide unfinished ownership work.
 
 ## Deliverable Order
 
-If work from this plan is executed, the recommended order is:
+Recommended order:
 
-1. documentation and degraded-mode contract,
+1. truth contract and doc normalization,
 2. startup hardening,
-3. AML/EC correctness,
+3. AML / EC / power-state correctness,
 4. ownership cleanup,
-5. consumer/eventing quality,
+5. consumer / eventing quality,
-6. validation closure.
+6. validation closure and release gate.
 
-## Definition of Done for the Current ACPI Plan
+## Definition of Done
 
-This plan can be considered substantially complete only when:
+This plan is substantially complete only when:
 
-- ownership boundaries are explicit — **partially met** (this doc; module-level cleanup still needed)
+- ownership boundaries are explicit and not contradicted by the code,
-- boot-critical panic/silent-fallback paths are removed or justified — **partially met** (Task 1.1 done; Tasks 1.2 and 1.3 open)
+- boot-critical panic / silent-fallback paths are removed or justified,
-- AML and EC behavior are no longer TODO-grade — **partially met** (mutex state and EC width done; AML init order and SLP_TYPb open)
+- AML and EC behavior are no longer TODO-grade,
-- DMAR and IVRS ownership are cleanly separated — **partially met** (DMAR not wired; module still present in acpid)
+- DMAR and IVRS ownership are no longer described ambiguously,
-- ACPI consumers are event-driven or explicitly bounded — **partially met** (shutdown done via kstop; sleep not implemented)
+- consumers are event-driven or explicitly bounded where eventing is not feasible,
-- sleep state transitions and eventing are implemented or explicitly documented as known gaps — **open**
+- sleep-state handling is implemented or explicitly excluded from the release claim,
-- the repo contains platform evidence that supports its status claims — **open** (QEMU validated; bare-metal evidence still needed)
+- the repo contains bounded platform evidence that supports every status claim.
 
-Current truthful status for Red Bear ACPI:
+## Current Truthful Status
 
-> materially complete for historical bring-up, but still under active robustness, ownership,
+> Red Bear ACPI is materially complete for historical boot bring-up, but still under active
-> sleep-state, and validation improvement. Shutdown eventing is implemented via kstop. Sleep state
+> robustness, ownership, sleep-state, and validation improvement. Shutdown eventing is implemented
-> transitions are a known gap. EC width support is implemented via byte transactions. AML mutex
+> via `kstop`. Sleep-state transitions remain a known gap. EC widened access is implemented via byte
-> state is real-tracked, not placeholder. DMAR is not initialized by acpid. Bare-metal validation
+> transactions. AML mutex state is real-tracked, not placeholder. DMAR is not initialized by
-> for the full ACPI surface is still outstanding.
+> `acpid`, and Intel DMAR runtime ownership is not yet cleanly closed. Bare-metal validation for the
+> full ACPI surface is still outstanding.

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

@@ -74,10 +74,20 @@ Red Bear OS already has a meaningful low-level controller and interrupt foundati
   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-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
 
@@ -161,7 +171,7 @@ especially under real runtime scenarios.
 
 ### ACPI / APIC / x2APIC
 
-**State**: materially complete for current platform bring-up goals.
+**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`,
@@ -179,6 +189,7 @@ 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
 
@@ -268,6 +279,9 @@ Current implementation improvement:
 - 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
 
@@ -311,6 +325,9 @@ 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
 
 ### USB xHCI controller interrupt path
 
@@ -323,8 +340,8 @@ Concrete checked-in owner:
 Current behavior:
 
 - xHCI has MSI/MSI-X and legacy INTx detection logic in source
-- the hardwired polling override in `xhcid` has been removed, and the driver now uses the existing
+- the checked-in `xhcid` source now calls the existing `get_int_method` path again instead of
-  MSI-X / MSI / INTx selection logic again
+  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
@@ -359,7 +376,7 @@ Open enhancement items:
   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 is significantly more mature than the rest of the low-level stack.
+- 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
 
@@ -537,7 +554,7 @@ 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 probe
+- `local/scripts/test-usb-storage-qemu.sh` — USB mass-storage autospawn plus bounded sector-0 readback proof
 
 ## Bottom Line