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

Red Bear OS ACPI Improvement Plan

Purpose

This document turns the current ACPI assessment into a concrete execution plan.

It does not replace local/docs/ACPI-FIXES.md. That file remains the historical record for the P0 bring-up work and the current table-by-table status snapshot. This document is the forward-looking plan for improving completeness, robustness, ownership clarity, consumer integration, and validation quality.

The goal is not to treat ACPI as a generic checklist of table parsers. The goal is to make the Red Bear ACPI stack:

• correct enough to survive bad firmware,
• clear enough that ownership boundaries stay maintainable,
• observable enough that failures are diagnosable,
• and validated enough that "complete" means more than "boots on one machine".

Scope

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

• kernel ACPI discovery and early table handling,
• acpid as the main ACPI/AML/FADT/DMI/power daemon,
• iommu as the IVRS/AMD-Vi runtime owner,
• pcid / /config as the MCFG replacement path,
• DMI-backed quirks flowing through acpid and redox-driver-sys,
• ACPI-consuming services such as redbear-sessiond and redbear-info.

Primary focus is the current x86_64 path, because that is the active Red Bear hardware target and the area where the current implementation and validation debt is concentrated. ARM64 ACPI support remains 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/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md — controller-level validation and quality context
• local/docs/IOMMU-SPEC-REFERENCE.md — IVRS/DMAR technical reference
• local/docs/QUIRKS-SYSTEM.md — DMI-backed quirks and ACPI table blacklist behavior
• local/docs/AMD-FIRST-INTEGRATION.md — historical AMD-first framing and hardware context
• local/docs/BAREMETAL-LOG.md — real-machine failure notes and negative results

Work Classification

Every task in this plan is tagged by its main purpose:

• Completeness — functionality exists but is still missing or partial
• Robustness — behavior exists but is too fragile under bad firmware or runtime stress
• Quality — ownership, observability, maintainability, or docs are below target

Wave 0 — Contracts, truthfulness, and degraded-mode policy

Goal

Stop treating ACPI as a loose cluster of working code and instead define:

1. who owns what,
2. which failures are fatal versus degradable,
3. and what status words in the docs actually mean.

Why this wave is first

Without an explicit contract, later hardening work turns into hidden rewrites and docs drift.

Scope

• 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

Status: Wave 0 execution partially complete

Tasks 0.1, 0.2, and 0.3 are partially executed in this documentation pass. The degraded-mode matrix 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)

Replace ambiguous wording such as "complete" with one of:

• implemented — behavior exists in the current source tree
• 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)

This matrix documents the expected system behavior for ACPI failure cases. All entries reflect implemented behavior visible in the current source tree.

Condition	Kernel behavior	Userspace (acpid) behavior	Session impact
Bad RSDP checksum	Warns, continues with best-effort RSDP parse	No ACPI init if RSDT/XSDT unreadable; exits cleanly	No ACPI services
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)

This section documents the current ownership split as visible in the source tree. Items marked 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.

Main 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

Status: Task 1.1 partially executed

acpid main.rs now uses a typed StartupError enum covering:

• ReadRootTable — failed to read /scheme/kernel.acpi/rxsdt
• 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! remains on these paths. Empty RSDT (no ACPI) causes a clean exit(0) after daemon.ready().

Tasks 1.2 and 1.3 remain open.

Tasks

Task 1.1 — Replace panic-grade startup failures in acpid — partially done

Typed StartupError enum is implemented in main.rs. The following failure classes are now handled:

• 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,
• evidence captured in local/docs/BAREMETAL-LOG.md or a successor log.

Wave 2 — AML, opregions, EC, and power-state correctness

Goal

Close the biggest runtime-correctness gaps in the ACPI stack.

Main 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

Task 2.1 — Remove placeholder AML mutex behavior — partially done

AmlMutexState in aml_physmem.rs implements real tracked state:

• AmlMutexState::create_handle() generates unique handles via incrementing next_handle
• AmlMutexState::states is a FxHashMap<Handle, bool> tracking locked/unlocked state
• lock_aml_mutexes() wraps the state map with proper Mutex guard and poisoned-state recovery
• The acquire() method looks up the handle in the map, sets it to true on success, and returns AmlError::MutexAcquireTimeout on timeout or unknown handle

This is no longer a placeholder implementation. Remaining work: timeout semantics documentation and concurrent acquire/release stress testing.

Task 2.2 — Eliminate silent zero-on-failure physical reads — partially done

EC reads via read_bytes now propagate AmlError::MutexAcquireTimeout on EC timeout rather than 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,
• EC timeout/error-path tests where possible,
• concurrent ACPI scheme reads while AML methods run.

Wave 3 — Ownership cleanup: reduce kernel ACPI scope and remove DMAR from acpid

Goal

Move from transitional ownership to architecture that is easier to maintain.

Main 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/*

Status: Tasks 3.1 and 3.2 partially executed

Task 3.1 — Define the minimum kernel ACPI surface — open

The kernel still carries TODOs for kernel ACPI scope reduction. No staged migration contract has been written yet.

Task 3.2 — Move DMAR to the correct owner — partially done

The acpi/dmar/mod.rs module remains present in acpid source but is not imported or called from 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 acpid. The exit path from acpid for DMAR is therefore effectively achieved, but the cleanup (task: remove the unused module or move it to the iommu crate) is not complete.

Task 3.3 — Ensure handoff paths are explicit — open

Handoff paths for table discovery and CPU/topology are not yet documented as a staged migration contract.

Acceptance criteria

• the minimal kernel ACPI contract is written down — open,
• DMAR has a concrete exit path from acpid — partially met (not wired; module still present),
• ownership reductions are staged and do not break current bring-up — open

Validation

• before/after boot regressions,
• 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.

Main 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

Status: Task 4.1 partially executed; sleep eventing still a gap

Task 4.1 — Replace polling-based ACPI state consumption — partially done

Shutdown eventing is now event-driven via /scheme/kernel.acpi/kstop:

• acpid opens kstop at startup and subscribes to it via RawEventQueue
• When the kernel triggers shutdown, acpid receives an event on the kstop file descriptor
• redbear-sessiond's acpi_watcher.rs opens kstop and reads one byte in a blocking spawn_blocking call, then emits D-Bus PrepareForShutdown(true) signal

Sleep eventing (\_Sx transitions) remains unsupported. There is no /scheme/acpi/sleep surface and no event-driven sleep contract. This is a known gap.

Task 4.2 — Bound DMI quirk authority — open

Task 4.3 — Improve operator-facing observability — open

Acceptance criteria

• 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

Goal

Convert the current implementation from bring-up evidence into release-grade trust.

Validation matrix

At minimum, require:

• QEMU/OVMF boot with ACPI active,
• modern AMD hardware,
• modern Intel hardware,
• one platform that exercises EC-backed AML behavior,
• malformed-table or degraded-mode evidence where feasible.

Tasks

Task 5.1 — Publish a platform matrix

For each validated platform, record:

• firmware mode,
• key ACPI tables detected,
• APIC mode,
• whether shutdown/reboot worked,
• whether DMI and power exposure worked,
• whether any AML/EC failure was observed.

Task 5.2 — Capture negative results

Do not hide unsupported AML opcodes, partial EC behavior, or platform-specific regressions behind a generic "works on tested hardware" label.

Task 5.3 — Define the ACPI release gate

Before calling ACPI complete for current Red Bear goals, require:

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

Upstream vs Red Bear Work Split

Upstream-first work

These are generic ACPI correctness or architecture issues and should be solved upstream whenever possible, with temporary Red Bear patch carriers only if necessary:

• acpid startup hardening
• 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

These remain Red Bear responsibilities even if upstream code improves:

• honest status/phase documentation
• bounded validation matrix and operator runbooks
• 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.
2. Wave 1 must come before Wave 2 so runtime correctness sits on a hardened startup path.
3. Wave 2 should come before Wave 4 because consumer contracts should depend on correct AML and power behavior.
4. Wave 3 should not start until Waves 1 and 2 are at least partially complete; ownership moves are dangerous if the runtime behavior is still fragile.
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,
• AML/EC changes may uncover hidden ordering assumptions with PCI registration,
• reducing kernel ownership too early may regress early platform bring-up,
• moving DMAR out of acpid may create Intel-only regressions if the replacement contract is vague,
• DMI quirks can become a crutch if they are allowed to override runtime facts indiscriminately.

Deliverable Order

If work from this plan is executed, the recommended order is:

1. documentation and degraded-mode contract,
2. startup hardening,
3. AML/EC correctness,
4. ownership cleanup,
5. consumer/eventing quality,
6. validation closure.

Definition of Done for the Current ACPI Plan

This plan can be considered substantially complete only when:

• ownership boundaries are explicit — partially met (this doc; module-level cleanup still needed)
• boot-critical panic/silent-fallback paths are removed or justified — partially met (Task 1.1 done; Tasks 1.2 and 1.3 open)
• AML and EC behavior are no longer TODO-grade — partially met (mutex state and EC width done; AML init order and SLP_TYPb open)
• DMAR and IVRS ownership are cleanly separated — partially met (DMAR not wired; module still present in acpid)
• ACPI consumers are event-driven or explicitly bounded — partially met (shutdown done via kstop; sleep not implemented)
• sleep state transitions and eventing are implemented or explicitly documented as known gaps — open
• the repo contains platform evidence that supports its status claims — open (QEMU validated; bare-metal evidence still needed)

Current truthful status for Red Bear ACPI:

materially complete for historical bring-up, but still under active robustness, ownership, sleep-state, and validation improvement. Shutdown eventing is implemented via kstop. Sleep state transitions are a known gap. EC width support is implemented via byte transactions. AML mutex state is real-tracked, not placeholder. DMAR is not initialized by acpid. Bare-metal validation for the full ACPI surface is still outstanding.