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 (3) - Debug ACPI Tables with Firmware Test Suite (FWTS)

Previous two articles, ACPI AML Debugger in Ubuntu 18.04 & Debug AML (DSD & SSDT) with ACPICA Utilities, discuss techniques for AML debugging; however ACPI specification includes many other important tables. Firmware Test Suite (FWTS) can play a big role in debugging ACPI implementation.

While other ACPI tables include fixed fields and lengths, it doesn't mean their contents cannot go wrong. In fact, many systems have many incorrect ACPI tables in their firmware. This can happen when systems are developed by integrating code from various parties without being modified specifically for customised hardware.

A test suite is a good solution to catch errors without involving too many engineering resources as it can identify errors automatically or semi-automatically. In particular, Firmware Test Suite is one of the best test suite (did I also mention it is freely available too?) and it is the recommended ACPI SCT by UEFI forum, who is the owner of the specification.

What is Firmware Test Suite (FWTS) ?

Firmware Test Suite (FWTS) is a test suite that performs sanity checks on firmware. It is intended to identify BIOS, UEFI, ACPI and many other errors and if appropriate it will try to explain the errors and give advice to help workaround or fix firmware bugs.

More information can be found at its official website.

Installing FWTS

Installation for Ubuntu Linux is as below:

1. Add stable PPA for latest FWTS (optional) - sudo add-apt-repository ppa:firmware-testing-team/ppa-fwts-stable
2. Install FWTS - sudo apt install fwts

FWTS packages for Other Linux distros can be found here.

Running Firmware Test Suite

FWTS is a command-line tool and its usage is "fwts cmds" (root access is usually required). The below is an example of checking FACP table
~$ sudo fwts fadt Running 1 tests, results appended to results.log Test: FADT Fixed ACPI Description Table tests. ACPI FADT Description Table flag info. 1 info only FADT checksum test. 1 passed FADT revision test. 1 warning ACPI FADT Description Table tests. 24 passed, 2 warnings, 2 skipped Test FADT SCI_EN bit is enabled. 1 passed Test FADT reset register. 2 passed ~$ sudo fwts mcfg Running 1 tests, results appended to results.log Test: MCFG PCI Express* memory mapped config space test. Validate MCFG table. 1 passed Validate MCFG PCI config space. 1 passed ~$ sudo fwts checksum Running 1 tests, results appended to results.log Test: ACPI table checksum test. ACPI table checksum test. 20 passed ~$ sudo fwts acpitables Running 1 tests, results appended to results.log Test: ACPI table headers sanity tests. Test ACPI headers. 17 passed, 1 failed

More test details can be found on its references.

Running Multiple Tests

FWTS can also run multiple tests by appending tests one after another as below:

~$ sudo fwts fadt mcfg checksum acpitables Running 4 tests, results appended to results.log Test: FADT Fixed ACPI Description Table tests. ACPI FADT Description Table flag info. 1 info only FADT checksum test. 1 passed FADT revision test. 1 warning ACPI FADT Description Table tests. 24 passed, 2 warnings, 2 skipped Test FADT SCI_EN bit is enabled. 1 passed Test FADT reset register. 2 passed Test: MCFG PCI Express* memory mapped config space test. Validate MCFG table. 1 passed Validate MCFG PCI config space. 1 passed Test: ACPI table checksum test. ACPI table checksum test. 20 passed Test: ACPI table headers sanity tests. Test ACPI headers. 17 passed, 1 failed

Running All ACPI Tests

FWTS provides a way to execute all tests in a category. For example, sudo fwts --acpitests run all ACPI tests all together. A similar command is sudo fwts --uefitests which will not be discussed in details here.

Let's See Some Examples...

FWTS is used for real projects. Here are some examples of tests we have run.

Checking FADT

Running fadt includes 6 tests that check whether system firmware/BIOS implements FACP table correctly.

Especially, the sizes of FACP table grow with ACPI specs, but some firmware/BIOS updates the FACP major and minor versions without adding the new fields in later ACPI spec. This can be caught by FWTS with ease. An example is Test 3 in results.log shown below.

~$ sudo fwts fadt ; cat results.log Running 1 tests, results appended to results.log Test: FADT Fixed ACPI Description Table tests. ACPI FADT Description Table flag info. 1 info only FADT checksum test. 1 passed FADT revision test. 1 warning ACPI FADT Description Table tests. 24 passed, 2 warnings, 2 skipped Test FADT SCI_EN bit is enabled. 1 passed Test FADT reset register. 2 passed Results generated by fwts: Version V19.01.00 (2019-01-16 03:58:48). Some of this work - Copyright (c) 1999 - 2019, Intel Corp. All rights reserved. Some of this work - Copyright (c) 2010 - 2019, Canonical. Some of this work - Copyright (c) 2016 - 2019, IBM. Some of this work - Copyright (c) 2017 - 2019, ARM Ltd. This test run on 24/01/19 at 17:16:21 on host Linux earth 4.15.0-43-generic #46-Ubuntu SMP Thu Dec 6 14:45:28 UTC 2018 x86_64. Command: "fwts fadt". Running tests: fadt. fadt: FADT Fixed ACPI Description Table tests. -------------------------------------------------------------------------------- FADT X_FIRMWARE_CTRL 64 bit pointer was zero, falling back to using FIRMWARE_CTRL 32 bit pointer. Test 1 of 6: ACPI FADT Description Table flag info. FADT: flag states WBINVD is set WBINVD_FLUSH is not set PROC_C1 is set P_LVL2_UP is not set PWR_BUTTON is not set SLP_BUTTON is set FIX_RTC is not set RTC_S4 is set TMR_VAL_EXT is not set DCK_CAP is not set RESET_REG_SUP is set SEALED_CASE is not set HEADLESS is not set CPU_SW_SLP is not set PCI_EXP_WAK is not set USE_PLATFORM_CLOCK is set S4_RTC_STS_VALID is set REMOTE_POWER_ON_CAPABLE is set FORCE_APIC_CLUSTER_MODEL is not set FORCE_APIC_PHYSICAL_DESTINATION_MODE is not set HW_REDUCED_ACPI is not set LOW_POWER_S0_IDLE_CAPABLE is not set FADT: IA-PC Boot Architecture flag states LEGACY_DEVICES is not set 8042 is not set VGA_NOT_PRESENT is not set MSI_NOT_SUPPORTED is not set PCIE_ASPM_CONTROLS is not set CMOS_RTC_NOT_PRESENT is not set FADT: ARM Boot Architecture flag states PSCI_COMPLIANT is not set PSCI_USE_HVC is not set Test 2 of 6: FADT checksum test. PASSED: Test 2, FADT checksum is correct Test 3 of 6: FADT revision test. FADT revision: 5.0 FADT table length: 268 WARNING: Test 3, FADT revision is outdated: 5.0 ADVICE: The most recent revision of the FADT defined in the ACPI specification is 6.2. While older revisions of the FADT can be used, newer ones may enable additional functionality that cannot be used until the FADT is updated. Test 4 of 6: ACPI FADT Description Table tests. PASSED: Test 4, Only one of FIRMWARE_CTRL and X_FIRMWARE_CTRL is non-zero. PASSED: Test 4, FADT 32 bit DSDT and 64 bit X_DSDT both point to the same physical address (0xd8fef1b0). ADVICE: While it is not correct to use both of the 32- and 64-bit DSDT address fields in recent versions of ACPI, they are at least the same address, which keeps the kernel from getting confused. At some point, the 32-bit DSDT address may get ignored so it is recommended that the FADT be upgraded to only use the 64-bit X_DSDT field. In the meantime, however, ACPI will still behave correctly. PASSED: Test 4, FADT first reserved field is one (compatible with ACPI 1.0). PASSED: Test 4, FADT second reserved field is zero. FADT Preferred PM Profile: 1 (Desktop) PASSED: Test 4, FADT has a valid preferred PM profile. FADT indicates ACPI IS NOT in reduced hardware mode. FADT SCI_INT is 9 PASSED: Test 4, FADT SMI_CMD indicates System Management Mode is supported, and the SCI Interrupt is non-zero. PASSED: Test 4, FADT SMI ACPI enable command is non-zero, and SMM is supported. PASSED: Test 4, FADT SMI ACPI disable command is non-zero, and SMM is supported. PASSED: Test 4, FADT indicates we are not in reduced hardware mode, and required FACS is present. PASSED: Test 4, FADT S4BIOS_REQ command is not set and FACS indicates it is not supported. PASSED: Test 4, FADT required PM1A_EVT_BLK field is non-zero PASSED: Test 4, FADT 32- and 64-bit PM1A_EVT_BLK fields are at least equal. ADVICE: Both FADT 32- and 64-bit PM1A_EVT_BLK fields are being used, but only one should be non-zero. However, they are at least equal so the kernel will at least have a usable value. SKIPPED: Test 4, FADT PM1B_EVT_BLK not being used. PASSED: Test 4, FADT required PM1A_CNT_BLK field is non-zero PASSED: Test 4, FADT 32- and 64-bit PM1A_CNT_BLK fields are at least equal. ADVICE: Both FADT 32- and 64-bit PM1A_CNT_BLK fields are being used, but only one should be non-zero. However, they are at least equal so the kernel will at least have a usable value. SKIPPED: Test 4, FADT PM1B_CNT_BLK not being used. PASSED: Test 4, FADT 32- and 64-bit PM2_CNT_BLK fields are at least equal. ADVICE: Both FADT 32- and 64-bit PM2_CNT_BLK fields are being used, but only one should be non-zero. However, they are at least equal so the kernel will at least have a usable value. PASSED: Test 4, FADT 32- and 64-bit PM_TMR_BLK fields are at least equal. ADVICE: Both FADT 32- and 64-bit PM_TMR_BLK fields are being used, but only one should be non-zero. However, they are at least equal so the kernel will at least have a usable value. PASSED: Test 4, FADT PM1_EVT_LEN >= 4. PASSED: Test 4, FADT PM1_CNT_LEN >= 2. PASSED: Test 4, FADT PM2_CNT_LEN >= 1. PASSED: Test 4, FADT PM_TMR_LEN is 4. PASSED: Test 4, FADT GPE0_BLK_LEN non-zero and a non-negative multiple of 2: 16. PASSED: Test 4, FADT GPE1_BLK_LEN is zero and GPE1_BLK is not supported. FADT GPE1_BASE is 0 Using P_BLK address of 0x1810 WARNING: Test 4, FADT P_LVL2_LAT is > 100 (101) but a P_BLK is defined. This implies a C2 state is not supported, but there is a P_BLK register block defined which implies there might be a C2 state that works. There is not enough information to determine if this is expected or not. WARNING: Test 4, FADT P_LVL3_LAT is > 1000 (1001) but a P_BLK is defined. This implies a C3 state is not supported, but there is a P_BLK register block defined which implies there might be a C3 state that works. There is not enough information to determine if this is expected or not. FADT FLUSH_SIZE is 1024 FADT FLUSH_STRIDE is 16 FADT DUTY_OFFSET is 0 FADT DUTY_WIDTH is 0 FADT DAY_ALRM is 13 FADT MON_ALRM is 0 FADT CENTURY is 50 PASSED: Test 4, FADT SLEEP_CONTROL_REG is null and not available when not in reduced hardware mode. PASSED: Test 4, FADT SLEEP_STATUS_REG is null and not available when not in reduced hardware mode. FADT Hypervisor Vendor Identity is 0 Test 5 of 6: Test FADT SCI_EN bit is enabled. FADT is greater than ACPI version 1.0 PASSED: Test 5, SCI_EN bit in PM1a Control Register Block is enabled. Test 6 of 6: Test FADT reset register. PASSED: Test 6, FADT reset register width is 8 bits wide as expected. PASSED: Test 6, FADT register bit offset is 0 as expected. ================================================================================ 28 passed, 0 failed, 3 warnings, 0 aborted, 2 skipped, 1 info only. ================================================================================ 28 passed, 0 failed, 3 warnings, 0 aborted, 2 skipped, 1 info only. Test Failure Summary ================================================================================ Critical failures: NONE High failures: NONE Medium failures: NONE Low failures: NONE Other failures: NONE Test |Pass |Fail |Abort|Warn |Skip |Info | ---------------+-----+-----+-----+-----+-----+-----+ fadt | 28| | | 3| 2| 1| ---------------+-----+-----+-----+-----+-----+-----+ Total: | 28| 0| 0| 3| 2| 1| ---------------+-----+-----+-----+-----+-----+-----+

 

Checking Table Checksum

Another common error in system firmware/BIOS is ACPI table checksum. When built by AML compiler, ex. iasl, table checksum is updated; however, it is a common practice that system firmware/BIOS modifies ACPI tables for hardware customisation during boot time. This can corrupt table checksum if firmware/BIOS does not update it accordingly.

Below is an example to verify the checksum fields of all ACPI tables.

~$ sudo fwts checksum ; cat results.log Running 1 tests, results appended to results.log Test: ACPI table checksum test. ACPI table checksum test. 20 passed Results generated by fwts: Version V19.01.00 (2019-01-16 03:58:48). Some of this work - Copyright (c) 1999 - 2019, Intel Corp. All rights reserved. Some of this work - Copyright (c) 2010 - 2019, Canonical. Some of this work - Copyright (c) 2016 - 2019, IBM. Some of this work - Copyright (c) 2017 - 2019, ARM Ltd. This test run on 24/01/19 at 17:23:54 on host Linux earth 4.15.0-43-generic #46-Ubuntu SMP Thu Dec 6 14:45:28 UTC 2018 x86_64. Command: "fwts checksum". Running tests: checksum. checksum: ACPI table checksum test. -------------------------------------------------------------------------------- Test 1 of 1: ACPI table checksum test. FADT X_FIRMWARE_CTRL 64 bit pointer was zero, falling back to using FIRMWARE_CTRL 32 bit pointer. PASSED: Test 1, Table RSDP has correct checksum 0x90. PASSED: Test 1, Table RSDP has correct extended checksum 0x8e. PASSED: Test 1, Table XSDT has correct checksum 0x21 PASSED: Test 1, Table DSDT has correct checksum 0xfc PASSED: Test 1, Table FACP has correct checksum 0xc9 PASSED: Test 1, Table APIC has correct checksum 0xbf PASSED: Test 1, Table FPDT has correct checksum 0x73 PASSED: Test 1, Table SLIC has correct checksum 0x6a PASSED: Test 1, Table SSDT has correct checksum 0x36 PASSED: Test 1, Table SSDT has correct checksum 0xb7 PASSED: Test 1, Table SSDT has correct checksum 0x3e PASSED: Test 1, Table HPET has correct checksum 0xa9 PASSED: Test 1, Table SSDT has correct checksum 0x3e PASSED: Test 1, Table MCFG has correct checksum 0x9c PASSED: Test 1, Table SSDT has correct checksum 0x31 PASSED: Test 1, Table ASF! has correct checksum 0xb8 PASSED: Test 1, Table BGRT has correct checksum 0x46 PASSED: Test 1, Table DMAR has correct checksum 0x37 PASSED: Test 1, Table RSDT has correct checksum 0xbd PASSED: Test 1, Table FACP has correct checksum 0xa1 ================================================================================ 20 passed, 0 failed, 0 warning, 0 aborted, 0 skipped, 0 info only. ================================================================================ 20 passed, 0 failed, 0 warning, 0 aborted, 0 skipped, 0 info only. Test Failure Summary ================================================================================ Critical failures: NONE High failures: NONE Medium failures: NONE Low failures: NONE Other failures: NONE Test |Pass |Fail |Abort|Warn |Skip |Info | ---------------+-----+-----+-----+-----+-----+-----+ checksum | 20| | | | | | ---------------+-----+-----+-----+-----+-----+-----+ Total: | 20| 0| 0| 0| 0| 0| ---------------+-----+-----+-----+-----+-----+-----+

Next Topic...

FWTS can analyze ACPI tables from other systems. This can be done with fwts --dumpfile=acpidump.log. More details will be discussed in the next blog.

[Presentation] Firmware Test Suite - Uses, Development, Contribution and GPL

I did a presentation of "Firmware Test Suite - Uses, Development, Contribution and GPL" in UEFI Plugfest in Taipei on Nov 1 2017. The presentation is shared @ slideshare and can be viewed below:

Firmware Test Suite - Uses, Development, Contribution and GPL from Alex Hung

[Presentation] BIOS, Linux and Firmware Test Suite in-between

I was invited to present "BIOS, Linux and Firmware Test Suite in-between" in Debian Taiwan's MiniDeb Conf in Taipei, Taiwan on Nov 9, 2013. The presentation is shared @ slideshare and can be viewed below:



Firmware Test Suite is an ongoing project that targets to automate firmware and hardware related tests. It receives some attentions from various parties including hardware, software and system vendors. (I also presented the similar topic in UEFI Plugfest in Sept, 2013, and the presentation slides are available @ http://uefi.org/learning_center/presentationsandvideos).