InstallationThe acpica-tools can be installed by
- sudo apt install acpica-tool
- Windows: https://acpica.org/downloads/binary-tools
- Ubuntu: sudo apt install acpica-tool
ACPICA ToolsThe acpica-tools consist of the following utilities: acpibin, acpiexamples, acpihelp, acpisrc, iasl, acpidump, acpiexec, acpinames and acpixtract. This article focuses on how to use iasl, acpidump, acpiexec and acpixtract because they are commonly used in debugging.
- acpidump - collect ACPI tables from a running system
- acpixtract - extract ACPI tables from an acpidump file
- acpiexec - emulate ACPI tables from extracted acpi tables
- iasl - compile & disassemble ACPI tables
A Case Study - Airplane ModeThe airplane-mode button on laptops is usually implemented by both system BIOS and an OS driver. More specifically, it requires an ACPI device to be “present” in DSDT (or SSDT) table and a corresponding device driver. The figure below demonstrates how to debug if the airplane mode button fails to work.
Each computer brand has its specific implementation(s) and corresponding device driver(s). Some examples are listed below. Similarly, other driver source code can be found in Linux kernel.
- Acer - acer-wireless
- ASUS - asus-wireless
- Dell - dell-rbtn, intel-hid, intel-vbtn
- HP - hp-wireless
- Lenovo - idealpad-laptop, thinkpad_acpi
- Xiaomi - hp-wireless
Let’s use a Dell system as an example but the same technique also applies for others. To understand whether the airplane mode driver is loaded, one can run
As expected, the intel-hid is used on this particular Dell system.
As seen above, the “intel-hid” is used on this particular Dell system.
Let’s assume we know intel-hid is supposed to be used on this Dell system but it is not loaded for now. We can debug BIOS ASL/AML code using ACPICA utilities following the below steps.
Find Out ACPI Device's (intel-hid's) Hardware ID
A quick online search shows intel-hid.c is for an ACPI device with _HID “INT33D5”.
Extract and Disassemble ACPI Tables
- Get all ACPI tables: sudo acpidump > acpi.log
- Extract DSDT and SSDT: acpixtract acpi.log
- Disassemble tables: iasl -d *.dat
Check Whether INT33D5 is "Present"
- Find INT33D5 in DSDT or SSDT: grep INT33DT *.dsl
Once found, let's use vi to see more details in DSDT such as the device name (HIDD) as below:
- Check device status, i.e. Method (_STA)
Alternatively, using acpiexec is easier for this task.
Evaluate _SB.HIDD._STA with acpiexec
Using acpiexec is the same as acpidbg, but it loads ACPI tables from files and runs AML in emulation mode, i.e. it does not touch hardware registers or actual memory.
- Load ACPI tables: acpiexec *.dat
- Find HIDD path: find HIDD
- Execute HIDD's _STA: execute _SB.HIDD._STA
If _SB.HIDD._STA returns 0, we can continue to use acpiexec to find out OIDE() returns. In fact, we can use acpiexec to trace _SB._HIDD._STA
- Trace _SB.HIDD._STA: debug _SB.HIDD._STA