Understanding ACPI and Device Tree

This blog document and help to understand how ACPI works

AML (ACPI Machine Language)

AML is compiled binary that written in the ACPI Source Language (ASL) and it is interpreted binary that interpreted by AML interpreter during OS runtime. AML is provided by hardware manufacture and embedded in the firmware, it provides the entire device base hierarchy (all thing that equipped on your motherboard, and cannot be removed.) and function to OS that could interface the dedicated hardware, like PCI-ISA bridge or processor, controlling the power, turn on/off, etc.

AML operated by different object type, and defined in definition block in firmware table (DSDT / SSDT)

AML object type

• Scope
• String Constant
• Package
• Control Method
• Device 

 ACPI Object Naming Convention

 1. All object names are 32 bits long.
 2. The first byte of a name must be one of 'A' - 'Z', '_'.
 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
    - '9', '_'.
 4. Names starting with '_' are reserved by the ACPI specification.
 5. The '\' symbol represents the root of the namespace (i.e. names
    prepended with '\' are relative to the namespace root).
 6. The '^' symbol represents the parent of the current namespace node
    (i.e. names prepended with '^' are relative to the parent of the current namespace node).

More info about AML syntax and programming see:       https://acpica.org/sites/acpica/files/asl_tutorial_v20190625.pdf

ACPI components

• AML Interpreter
• ACPI namespace 
• Hardware interaction - set of ACPI object evaluation APIs 

ACPI Namespace

ACPI driver constructs the following tree, called namespace for entire base system by loading Differentiate Definition Block(DDB) and other definition blocks from DSDT and SSDT respectively in firmware, these blocks get parsed by AML interpreter of ACPI driver on system boot.

DDB cannot be unloaded, definition blocks from SSDT were added to namespace after DDB is loaded.

 

ACPI namespace topology example

AML Interpreter offers ability to ACPI driver to evaluate ACPI object, the result of evaluation should

depend on the object type, e.g. executing native method, returning package contents, hardware ID,

etc.

Evaluation flow from ACPI spec

Device Tree's birthday

Each device in AML will be represented as PDO in ACPI device stack, after system loaded the corresponding driver, the drivers creates the FDO and attach it to the PDO just created, such as, PCI.sys for PCI Root bridge device in AML.

Similarly, PCI driver manages huge part of entire device tree, it creates PDOs for other PCI-based device just like ACPI did to it, and load their corresponding drivers and the drivers then create its FDO.

For example, USB Controller as other PCI-based bus device, or Thunderbolt controller as other PCI

based functional device, or the other bus device.

To my understanding, PDO in every bus device stack just act as representative of device from bus perspective, bus driver doesn't know how to operate these device, it only helps bus driver, like ACPI, to find which is the hardware need to be operated upon FDO or when someone request.

And obviously, FDO is some device owner who knows how to operate the target device, and have enough knowledge to ask bus driver complete the task on behalf of them.

 

PCI is another bus spec, so it becomes other logical bus driver like acpi.sys does, such as, usbxhci.sys to pci.sys as other bus driver however, every bus could have non-bus device to each of them, such as, i8042prt.sys / intelppm.sys / monitor.sys to acpi.sys or nhi.sys to pci.sys (thunderbolt driver)

Reference

https://uefi.org/sites/default/files/resources/ACPI_6_0_Errata_A.PDF

https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/

https://docs.microsoft.com/en-us/windows-hardware/drivers/gettingstarted/device-nodes-and-device-stacks