Crate aml

aml is a pure-Rust AML (ACPI Machine Language) parser, used for parsing the DSDT and SSDT tables from ACPI. This crate can be used by kernels to gather information about the hardware, and invoke control methods to query and change the state of devices in a hardware-independent way.

Using the library

To use the library, you should create an AmlContext using AmlContext::new(), and then pass it tables containing AML (probably from the acpi crate), which you’ve mapped into the virtual address space. This will parse the table, populating the namespace with objects encoded by the AML. After this, you may unmap the memory the table was mapped into - all the information needed will be extracted and allocated on the heap.

You can then access specific objects by name like so: e.g.

let my_aml_value = aml_context.lookup(&AmlName::from_str("\\_SB.PCI0.S08._ADR").unwrap());

And invoke control methods like this: e.g.

let result = aml_context.invoke_method(&AmlName::from_str("\\_SB.HPET._CRS").unwrap(), value::Args::EMPTY);

About the parser

The parser is written using a set of custom parser combinators - the code can be confusing on first reading, but provides an extensible and type-safe way to write parsers. For an easy introduction to parser combinators and the foundations used for this library, I suggest reading Bodil’s fantastic blog post.

The actual combinators can be found in parser.rs. Various tricks are used to provide a nice API and work around limitations in the type system, such as the concrete types like MapWithContext.

The actual parsers are then grouped into categories based loosely on the AML grammar sections in the ACPI spec. Most are written in terms of combinators, but some have to be written in a more imperitive style, either because they’re clearer, or because we haven’t yet found good combinator patterns to express the parse.

Re-exports

pub use crate::value::AmlValue;

Modules

pci_routing

resource

value

Structs

AmlContext

AmlHandle

A handle is used to refer to an AML value without actually borrowing it until you need to access it (this makes borrowing situation much easier as you only have to consider who’s borrowing the namespace). They can also be cached to avoid expensive namespace lookups.

AmlName

Namespace

NamespaceLevel

Enums

AmlError

Used when an AmlContext encounters an error.

DebugVerbosity

Describes how much debug information the parser should emit. Set the “maximum” expected verbosity in the context’s debug_verbosity - everything will be printed that is less or equal in ‘verbosity’.

LevelType

NameComponent

Constants

AML_INTERPRETER_REVISION

AML has a RevisionOp operator that returns the “AML interpreter revision”. It’s not clear what this is actually used for, but this is ours.

Traits

Handler

Trait type used by AmlContext to handle reading and writing to various types of memory in the system.