acpi-machine

Documents ACPI table construction, PM registers, and guest power-off for the Entangled Desktop VMM.

Updated Aug 18, 2026
One-click install
npx skills add https://github.com/doctorspider42/entangled-destop --skill acpi-machine-doctorspider42
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: acpi-machine
Source: https://github.com/doctorspider42/entangled-destop/tree/main/.agents/skills/acpi-machine
Command: npx skills add https://github.com/doctorspider42/entangled-destop --skill acpi-machine-doctorspider42

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Working on the ACPI subsystem of a from-scratch Rust VMM requires knowing exactly how the RSDP/XSDT/FADT/FACS/MADT/DSDT tables are laid out, how the PM register block behaves, and how guest shutdown and reboot are wired — getting any of these wrong produces obscure boot failures like #GP faults or guests that cannot power off. ## Core Features & Use Cases - Table inventory and layout: Documents the exact addresses, sizes, and contents of every ACPI table at 0x000e_0000, including why the FACS and DSDT must never appear in the XSDT. - PM register block semantics: Explains the 16-port ACPI PM block at 0x600, the latched PM timer invariant, SCI_EN behavior, and the S5 shutdown latch that ends the VM. - AML/DSDT authoring and verification: Describes the hand-rolled AML encoder, the iasl round-trip acceptance test, and the boot tests that validate tables against real Linux and UEFI guests. - Use Case: Before modifying machine_x86::acpi or debugging a guest that fails to power off, load this Skill to understand the S5 write path through PM1a_CNT and SLEEP_CONTROL and how the run loop polls shutdown_requested(). ## Quick Start Load the acpi-machine skill before editing the ACPI tables, PM register block, or guest shutdown code in the Entangled Desktop machine.

Frequently Asked Questions about acpi-machine

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement guest power-off in a custom VMM with ACPI?

Implement the S5 sleep path: the guest writes SLP_TYP 5 with SLP_EN to PM1a_CNT (0x606) on Linux or SLEEP_CONTROL (0x600) on EDK2. Set a latch on that write and have the run loop poll a shutdown_requested method after every exit, returning a Shutdown outcome.

How are ACPI tables laid out in guest memory for a virtual machine?

Place a contiguous blob at 0xe0000 inside the legacy RSDP scan window: RSDP, XSDT, FADT, FACS, MADT, then DSDT, each 64-byte aligned. Mark the region as AcpiReclaim in the E820 map so guest allocators never claim it.

Why does a guest fail to power off with 'Power off not available'?

The DSDT is missing the \_S5 object. Linux's acpi_sleep_init refuses to register a power-off handler without it, so add a Name (\_S5, Package) entry with SLP_TYP 5 to the DSDT.

Should the DSDT be listed in the XSDT table?

No. EDK2's InstallCloudHvTables installs every XSDT entry and then installs the DSDT separately from the FADT's X_DSDT pointer, so a DSDT in the XSDT would be installed twice. The same applies to the FACS.

How do I verify hand-written AML and ACPI tables?

Dump the tables via the acpi_dump test, then run iasl -d on dsdt.aml, facp.dat, and apic.dat. The acceptance bar is zero errors or warnings and disassembled ASL matching the intended DSDT source.

Why does a guest read a PM timer value that appears to go backwards?

The timer was sampled per byte instead of once per access, letting a carry land between bytes. Latch the counter once before walking the access bytes so the read value lies between the counter before and after the access.