RedBear-OS/local/docs/ACPI-IMPROVEMENT-PLAN.md

# 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 plan does **not** replace `local/docs/ACPI-FIXES.md`.

- `local/docs/ACPI-FIXES.md` remains the historical ledger for P0 ACPI bring-up and the current
  table-by-table implementation snapshot.
- This file is the forward execution plan for closing the remaining ACPI gaps in correctness,
  ownership clarity, consumer integration, and validation trust.

The goal is not to maximize the number of parsed ACPI tables. The goal is to make the Red Bear ACPI
stack:

- correct under bad firmware,
- explicit about who owns what,
- observable when it fails,
- and validated enough that status claims are evidence-backed rather than inferred.

## Scope

This plan covers the Red Bear ACPI stack and its direct consumers:

- kernel ACPI discovery and early platform setup,
- `acpid` as the main ACPI / AML / FADT / DMI / power daemon,
- `iommu` as the IVRS / AMD-Vi runtime owner,
- `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 consumers such as `redbear-sessiond`, `redbear-info`, and downstream services.

Primary focus is the current `x86_64` path. ARM64 remains in scope only where parser quality or
kernel-ownership decisions are shared.

## Canonical Related Documents

Read these alongside this plan:

- `local/docs/ACPI-FIXES.md`
- `local/docs/BAREMETAL-LOG.md`
- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md`
- `local/docs/IOMMU-SPEC-REFERENCE.md`
- `local/docs/QUIRKS-SYSTEM.md`
- `docs/02-GAP-ANALYSIS.md`

## Evidence Model

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

- **source-visible** — behavior is visible in the checked-in source tree
- **patch-carried** — behavior exists through `local/patches/*`
- **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`.
- `acpid` now models `S1` / `S3` / `S4` / `S5` explicitly in userspace, and the current `_S5`
  shutdown path routes through that model instead of a special-case magic value.

### Weak today

- Sleep-state transitions beyond `\_S5` are unsupported.
- Sleep eventing is unsupported.
- `SLP_TYPb` remains incomplete for broader sleep-state handling.
- Non-`S5` sleep targets are now represented explicitly, but they remain groundwork-only and do not
  imply implemented suspend/resume support yet.
- 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

Establish one canonical answer to:

1. who owns what,
2. what counts as degraded but acceptable,
3. and what ACPI status words mean.

### Why this wave is first

Without a contract, all later hardening work turns into undocumented rewrites and docs drift.

### Primary files

- `local/docs/ACPI-FIXES.md`
- this file
- `docs/02-GAP-ANALYSIS.md`
- `README.md` and related status surfaces if needed

### Dependencies

- none

### Deliverables

- one normalized ACPI vocabulary,
- one degraded-mode contract,
- one canonical ownership statement,
- removal of doc language that implies subsystem completeness without evidence.

### Verification

- documentation review only,
- no contradictory ownership claims across ACPI docs,
- no bare “complete” wording without scope.

### Exit criteria

- one canonical ownership statement exists,
- one degraded-mode matrix exists,
- all top-level ACPI docs use the same vocabulary.

### Current status

- partially complete

## Wave 1 — Boot-path hardening and parser strictness

### Goal

Remove catastrophic or silent failure behavior from boot-critical ACPI initialization.

### 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 as needed

### Dependencies

- Wave 0 ownership and degraded-mode vocabulary in place

### Deliverables

- startup paths are typed and explicit,
- 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.

### Specific 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.

### Verification

- malformed checksum / truncated-length tests,
- QEMU validation with intentionally damaged tables if feasible,
- one bounded AMD hardware boot recheck,
- 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 `acpid` layer.

### 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`

### Dependencies

- Wave 1 startup paths hardened enough that runtime work is not sitting on a fragile base

### Deliverables

- real AML synchronization semantics,
- explicit physmem / opregion failure behavior,
- deterministic AML init order,
- explicit sleep-state scope,
- honest EC behavior bounds.

### Specific tasks

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`.

### Verification

- targeted AML method execution tests,
- shutdown / reboot proof in QEMU and bounded hardware,
- EC timeout and error-path tests,
- concurrent ACPI scheme reads while AML methods run,
- at least one EC-backed platform check if available.

### 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 an architecture that can survive long-term maintenance.

### Primary files

- `recipes/core/kernel/source/src/acpi/mod.rs`
- kernel ACPI submodules as needed
- `recipes/core/base/source/drivers/acpid/src/acpi/dmar/mod.rs`
- `recipes/core/base/source/drivers/acpid/src/scheme.rs`
- `local/recipes/system/iommu/source/src/*`

### Dependencies

- Wave 1 and Wave 2 are at least partially complete

### Deliverables

- 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.

### Specific tasks

1. Define the minimum kernel ACPI surface that must remain in early boot.
2. Document the userspace handoff contract for topology and table consumers.
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.

### Verification

- before / after boot regressions,
- Intel-specific validation for any DMAR ownership move,
- AMD regression checks showing IVRS ownership remains isolated in `iommu`.

### Exit criteria

- the minimum kernel ACPI contract is written down,
- DMAR has a concrete, non-ambiguous owner or is explicitly deferred,
- ownership reductions do not regress current bring-up.

### Current status

- partially complete

## Wave 4 — Consumer integration and eventing quality

### Goal

Make ACPI consumers correct, observable, and low-friction.

### Primary files

- `local/recipes/system/redbear-sessiond/source/src/acpi_watcher.rs`
- `recipes/core/base/source/drivers/acpid/src/scheme.rs`
- DMI / quirk consumers in `redox-driver-sys`
- reporting surfaces such as `redbear-info`

### Dependencies

- Wave 2 runtime behavior is stable enough for downstream consumers to depend on it

### Deliverables

- event-driven core power-session behavior where feasible,
- bounded DMI quirk authority,
- operator-facing observability strong enough to diagnose behavior,
- explicit treatment of unsupported sleep eventing if it remains deferred.

### Specific tasks

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.

### Verification

- repeated shutdown edge tests,
- sleep-edge tests if sleep work is in scope,
- DMI quirk application checks on known systems,
- race checks with multiple simultaneous consumers of `/scheme/acpi/*`.

### 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

Turn the current ACPI stack from bring-up evidence into release-grade trust.

### Dependencies

- Waves 1 through 4 have produced stable behavior worth validating

### Required validation matrix

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.

### Deliverables

- a bounded platform matrix,
- negative-result capture,
- explicit release gates for both boot-baseline and full ACPI claims,
- docs that distinguish implemented from validated.

### Specific tasks

1. Publish the platform matrix in `local/docs/BAREMETAL-LOG.md` or its successor.
2. Record for each platform: firmware mode, key ACPI tables, APIC mode, shutdown / reboot,
   DMI / power exposure, AML / EC failures, and notable degraded behavior.
3. Preserve negative results such as unsupported AML opcodes or platform-specific regressions.
4. Require evidence before any stronger ACPI completeness claim is made.

### Verification

- repeated QEMU proof,
- bounded repeated bare-metal proof on AMD and Intel,
- one EC-heavy platform check,
- cross-check docs so claims match recorded evidence.

### Exit criteria

- one bounded but honest platform matrix exists,
- negative results are documented,
- 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

### Prefer upstream for

- generic `acpid` startup hardening,
- 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.

### Red Bear owns

- honest status language,
- bounded validation matrices and runbooks,
- `redbear-sessiond` shutdown-consumer quality,
- DMI quirk governance and integration policy,
- patch carriers in `local/patches/*`,
- coordination across `acpid`, `iommu`, `pcid`, and downstream consumers.

## Sequencing Constraints

1. **Wave 0 first** — architecture and wording must stop drifting.
2. **Wave 1 before Wave 2** — runtime correctness should not sit on fragile startup behavior.
3. **Wave 2 before Wave 4** — consumer contracts must rely on correct AML / power behavior.
4. **Wave 3 after Waves 1 and 2 are partially stable** — ownership moves are risky on unstable
   behavior.
5. **Wave 5 last** — validation closes work; it does not replace architecture.

## Main Risks

- stricter parser behavior may expose machines currently booting only by luck,
- AML / EC changes may uncover hidden PCI-registration ordering assumptions,
- reducing kernel scope too early may regress early bring-up,
- careless DMAR cleanup may create Intel-only regressions,
- 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

Recommended order:

1. truth contract and doc normalization,
2. startup hardening,
3. AML / EC / power-state correctness,
4. ownership cleanup,
5. consumer / eventing quality,
6. validation closure and release gate.

## Definition of Done

This plan is substantially complete only when:

- ownership boundaries are explicit and not contradicted by the code,
- boot-critical panic / silent-fallback paths are removed or justified,
- AML and EC behavior are no longer TODO-grade,
- DMAR and IVRS ownership are no longer described ambiguously,
- consumers are event-driven or explicitly bounded where eventing is not feasible,
- sleep-state handling is implemented or explicitly excluded from the release claim,
- the repo contains bounded platform evidence that supports every status claim.

## Current Truthful Status

> Red Bear ACPI is materially complete for historical boot bring-up, but still under active
> robustness, ownership, sleep-state, and validation improvement. Shutdown eventing is implemented
> via `kstop`. Sleep-state transitions remain a known gap. EC widened access is implemented via byte
> transactions. AML mutex state is real-tracked, not placeholder. DMAR is not initialized by
> `acpid`, and Intel DMAR runtime ownership is not yet cleanly closed. Bare-metal validation for the
> full ACPI surface is still outstanding.