ACPI Debugging (4) -Analyse ACPI Tables in a Text File with FWTS

I often need to implement tests for new ACPI tables before they become available on real hardware. Fortunately, FWTS provides a framework to read ACPI tables' binary.

The below technique is especially convenient for ACPI firmware and OS kernel developers. It provides a simple approach to verify ACPI tables without compiling firmware and deploying it to hardware.

Using acpidump.log as an Input for FWTS

The command to read ACPI tables' binary is

 # check ACPI methods from a text file
 $ fwts method --dumpfile=acpidump.log

or

 # check ACPI FACP table from a text file
 $ fwts facp --dumpfile=acpidump.log

where acpidump.log contains ACPI tables' binary in a specific format as depicted below:

• Table Signature - the 4-byte long ACPI table signature
• Offset - data start from 0000 and increase by 16 bytes per line
• Hex Data- each line has 16 hex integers of the compiled ACPI table
• ASCII Data - the ASCII presentation of the hex data

This format may look familiar because it is not specific to FWTS. In fact, it is the same format generated by acpidump. In other words, the following commands generate the identical results.

# reading ACPI tables from memory
$ sudo fwts method

# dumping ACPI tables and testing it
$ sudo acpidump > acpidump.log
$ fwts method --dumpfile=acpidump.log

This means it is probable to debug remote systems by the following steps: 1) run sudo acpidump > acpidump.log, 2) copy acpidump.log and 3) run fwts with the --dumpfile=acpidump.log.

For developers, using --dumpfile option also means it is possible to test ACPI tables before deploying them on real hardware. The following sections present how to prepare a customized acpidump.log for such purposes.

Using a customized acpidump.log for FWTS

We can use acpica-tools to generate an acpidump.log. The following is an example of building a customized acpidump for the method test.

1. Generate a dummy FACP table

FWTS requires a FACP table in an acpidump.log so it can recognize acpidump.log as a valid input file.

1. iasl -T FACP
2. iasl facp.asl > /dev/zero
3. echo "FACP @ 0x0000000000000000" >> acpidump.log
4. xxd -c 16 -g 1 facp.aml  | sed 's/^0000/    /' >> acpidump.log
5. echo "" >> acpidump.log

2. Generate a Customized DSDT table

A customized DSDT can be generated by the following commands

1. Generate a DSDT -  run "iasl -T DSDT"
2. Customize dsdt.asl - ex. adding an ACPI battery device

3. Compile the DSDT table to binary

Similar to FACP, the DSDT can be compiled and appended to acpidump.log.

1. iasl dsdt.asl > /dev/zero
2. echo "DSDT @ 0x0000000000000000" >> acpidump.log
3. xxd -c 16 -g 1 dsdt.aml  | sed 's/^0000/    /' >> acpidump.log
4. echo "" >> acpidump.log

3. Run FWTS method with acpidump.log

And finally, run fwts with the generated acpidump.log

• fwts method --dumpfile=acpidump.log

Final Words

While we use DSDT as an example, the same technique applies to all ACPI tables. For instance, HMAT was introduced and frequently updates in recent ACPI specs, and Firmware Test Suite includes most, if not all, changes up-to-date; therefore, FWTS is able to detect errors before firmware developers integrate HMAT into their projects, and therefore reduce errors in final products.

ACPI Debugging (2) - Debug AML (DSDT & SSDT) with ACPICA Utilities

Using acpidbg on Ubuntu 18.04 x64 can be quite handy; however, the Linux kernel with ACPI_DEBUGGER is not always available, such as on Ubuntu for ARM. In such cases, acpica also provides a set of utilities, named acpica-tools, for ACPI debugging.

Installation

The acpica-tools can be installed by

•  sudo apt install acpica-tool

The latest source code can be downloaded from either of below, and it can be compiled and installed by “make” followed by “sudo make install“.

• Windows: https://acpica.org/downloads/binary-tools
• Ubuntu: sudo apt install acpica-tool

ACPICA Tools

The 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 Mode

The 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

$ lsmod | grep -E 'dell_rbtn|intel_hid|intel_vbtn' intel_hid 16384 0 sparse_keymap 16384 2 intel_hid,dell_wmi

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

$ grep INT33D5 *.dsl dsdt.dsl: Name (_HID, "INT33D5") // _HID: Hardware ID
Once found, let's use vi to see more details in DSDT such as the device name (HIDD) as below:

Scope (_SB) { Device (HIDD) { Name (_HID, "INT33D5") // _HID: Hardware ID // ... skipped Method (_STA, 0, Serialized) // _STA: Status { If ((OIDE () >= One)) { Return (0x0F) } Else { Return (Zero) } } ...

• Check device status, i.e. Method (_STA)

In addition to the device declaration, Linux ACPI device driver is loaded when _STA returns “present”. As in the above ASL code, _STA can be present (return 0x0F) or absent (return Zero). One can continue to trace OIDE() -> OSID() and so on to find out what _STA returns.

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 0xF but intel-hid is not loaded, something is wrong with Linux kernel, ex. intel-hid is not compiled or is blacklisted. In this case, this should be forwarded to a Linux kernel engineer.

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

Tutorial of using acpiexec is the same as acpidbg and can be found in the previous blog.

Final Words

ACPICA tools are very useful for debugging ACPI bugs, and using it well can save much time. This tutorial touches surface of what ACPICA tools can do and more documents can be found on acpica.org website.

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

ACPICA is an open-source 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 runtime wasn't provided in ACPICA ... not until Linux Kernel 4.13.

Enabling AML Debugging

The aml-debugger.txt, the instruction for enabling AML runtime debugger, is available at Documentation/acpi/ in Linux kernel source code. In short, two things are required for AML runtime debugging

• Enable AML debugging (CONFIG_ACPI_DEBUGGER=y & CONFIG_ACPI_DEBUGGER_USER=m) when compiling Linux kernel

• Compile an utility, acpidbg from Linux kernel (I uploaded a copy here)

While compiling a custom-build kernel is nothing new to kernel developers, it is often inconvenient for system firmware / BIOS developers who need to verify ACPI AML implementation in their firmware. Fortunately, Ubuntu 18.04 (x64) and later enable these config by default, and one can simply execute acpidbg on Ubuntu 18.04 - even on Ubuntu Live from USB too!

Running AML Debugging

Executing acpidbg on Ubuntu 18.04 (x64) is straight-forward
$ sudo ./acpidbg -

and "help" shows a list supported commands
- help General-Purpose Commands: ... ... Namespace Access Commands: ... ... Control Method Execution Commands: ... ...

Examples

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

Example 1 - To determine AC power status in runtime.

1. Find _PSR objects
2. Evaluate _PSR when AC is disconnected
3. Evaluate _PSR when AC is connected.

- find _PSR \_SB.PCI0.LPC.EC.AC._PSR Method 00000000c53d0a47 01 Args 0 Len 0023 Aml 00000000eab88cb2 - execute \_SB.PCI0.LPC.EC.AC._PSR Evaluating \_SB.PCI0.LPC.EC.AC._PSR Evaluation of \_SB.PCI0.LPC.EC.AC._PSR returned object 00000000c46fa555, external buffer length 18 [Integer] = 0000000000000000 - execute \_SB.PCI0.LPC.EC.AC._PSR Evaluating \_SB.PCI0.LPC.EC.AC._PSR Evaluation of \_SB.PCI0.LPC.EC.AC._PSR returned object 00000000c46fa555, external buffer length 18 [Integer] = 0000000000000001

acpidbg also works with complex objects such as packages.
Example 2 - To determine battery information and status.

1. Find _BIF and _BST objects
2. Evaluate _BIF and _BST objects (note _BST changes dynamically).

- find _BIF \_SB.PCI0.LPC.EC.BAT0._BIF Method 00000000817541c3 01 Args 0 Len 0040 Aml 000000009abb252e - execute \_SB.PCI0.LPC.EC.BAT0._BIF Evaluating \_SB.PCI0.LPC.EC.BAT0._BIF Evaluation of \_SB.PCI0.LPC.EC.BAT0._BIF returned object 00000000c46fa555, external buffer length 170 [Package] Contains 13 Elements: [Integer] = 0000000000000000 [Integer] = 000000000000ABE0 [Integer] = 0000000000009E34 [Integer] = 0000000000000001 [Integer] = 0000000000003B60 [Integer] = 00000000000007E9 [Integer] = 00000000000000C8 [Integer] = 0000000000000001 [Integer] = 0000000000000001 [String] Length 07 = "00HW027" [String] Length 05 = " 409" [String] Length 03 = "LiP" [String] Length 03 = "SMP" - find _BST \_SB.PCI0.LPC.EC.BAT0._BST Method 00000000ed98c5ba 01 Args 0 Len 001D Aml 00000000a48eaeb6 - execute \_SB.PCI0.LPC.EC.BAT0._BST Evaluating \_SB.PCI0.LPC.EC.BAT0._BST Evaluation of \_SB.PCI0.LPC.EC.BAT0._BST returned object 00000000c46fa555, external buffer length 78 [Package] Contains 4 Elements: [Integer] = 0000000000000001 [Integer] = 00000000000010C6 [Integer] = 00000000000088B8 [Integer] = 0000000000003FC9

acpidbg can decode bit fields and save time on counting bits. Try to run acpidbg to evaluate any _PLD objects and you will see what I mean :).