Skip to main content

Your submission was sent successfully! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates from Canonical and upcoming events where you can meet our team.Close

Thank you for contacting us. A member of our team will be in touch shortly. Close

  1. Blog
  2. Article

Alex Hung
on 4 June 2019

Debug ACPI Tables with Firmware Test Suite (FWTS)

ACPI Debugging Firmware FWTS

In my previous two articles, ACPI AML Debugger in Ubuntu 18.04 & Debug AML (DSD & SSDT) with ACPICA Utilities, I discussed techniques for AML debugging; however the ACPI specification includes many other important tables. Firmware Test Suite (FWTS) is a test suite (as the name indicates) that can play a big role in debugging ACPI implementations.

While other ACPI tables include fixed fields and lengths, it doesn’t mean their their content cannot go wrong. In fact, many systems have many incorrect tables in their firmware. This can happen when systems are developed by integrating code from various parties without being modified specifically for the 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 mention it is freely available too?) and it is the recommended ACPI SCT by the UEFI forum, who is the owner of the specification.

What is Firmware Test Suite?

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

More information can be found on the Firmware Test Suite website.

Installing Firmware Test Suite

Installation for Ubuntu Linux is as below:

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

You can also download Firmware Test Suite for other Linux distros.

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 pages.

Running multiple tests

Multiple tests can be run 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…

Here are some examples of tests we have run.

Checking FACP Table

Running fadt includes 6 tests that check whether the system firmware/BIOS implements the FACP table correctly. An example results.log is as 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

// truncated...

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.

// truncated...

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 comes from the table checksum. When built by the AML compiler, ex. iasl, the table checksum is updated; however, it is common practice that the system firmware/BIOS modifies the tables for hardware customisation during boot time. This can corrupt the table checksum if the firmware/BIOS does not update it accordingly.

Below is an example to verify the checksum fields of all 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|
---------------+-----+-----+-----+-----+-----+-----+

Related posts

Alex Hung
8 July 2019

Analyze ACPI Tables in a Text File with FWTS

Cloud and server Article

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 verifying ACPI tables without compiling firmware an ...

Alex Hung
20 March 2019

Debug ACPI DSDT and SSDT with ACPICA Utilities

Desktop Article

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 Installing acpica-tools is as easy as the following command: The latest source c ...

Alex Hung
14 February 2019

ACPI AML Runtime Debugger in Ubuntu 18.04 (x64)

Desktop Article

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). However, AML debugging on Linux in run-time wasn’t provided in ACPICA until Linux Kernel 4.13. Enabling AML Debugging The aml-debugger.t ...