Tuesday, May 1, 2018

ACPI Debugging (1) - ACPI AML Debugger in Ubuntu 18.04

ACPICA is a project that provides an operating system (OS)-independent reference implementation. It also contains a list of utilities such as ASL compiler (iasl), acpiexec (an AML emulator) and so on. However, debugging AML on Linux in real time wasn't provided in ACPICA ... until Linux Kernel 4.13.

The aml-debugger.txt the instruction of how to enable AML debugger, is available at Documentation/acpi/ in Linux kernel source code. In short, two things are required to run AML debugging
  1. Enabling AML debugging (CONFIG_ACPI_DEBUGGER=y & CONFIG_ACPI_DEBUGGER_USER=m) in Linux kernel
  2. Compile an utility, acpidbg from Linux kernel (I uploaded a copy here)
While compiling a custom-build kernel with the above two config is nothing new to kernel developers, it is often inconvenient for firmware developers who need to verify ACPI implementation in their firmware. Fortunately, Ubuntu 18.04 (x64) enables these two config by default, and one can run acpidbg on Ubuntu 18.04 - even on Ubuntu Live from USB too!

Executing acpidbg on Ubuntu 18.04 is very straight-forward

and "help" shows a list supported commands

acpidbg is particularly handy when one needs to evaluate any ACPI AML objects during runtime - especially the ones that changes under different conditions. This may be best explained by some examples below:

Example - Determine implementation for AC power status. This includes 1) find _PSR object, 2) evaluate _PSR when AC is disconnected, and 3) evaluate _PSR when AC is connected.

acpidbg also works with more complex returns such as packages.
Example - Determine battery information and status. This include 1) find _BIF and _BST objects, 2) evaluate _BIF and _BST objects (note _BST changes dynamically).

acpidbg can decode bit fields in the return to save some time on counting bits. Please try to run acpidbg on any _PLD objects and you will understand what I mean :).


  1. good sharing. does 18.04.1 has it enabled by default as well?

  2. Tommy, 18.04.1 support it, because 18.04.1 and 18.04 use the same kernel.