ACPI Debugging from Linux Kernel

ACPI Debugging from Linux Kernel October, 2019, openSUSE.Asia Summit, Udayana University Joey Lee SUSE Labs Taipei jlee@suse.com

2 Agenda • ACPI subsystem in Linux Kernel • ACPI debug log • Override ACPI Definition Blocks Tables • Case: Tracing ACPI temperature • Q&A

ACPI subsystem in Linux Kernel

4 ACPI • Advanced Configuration and Power Interface (ACPI) is a method for describing hardware interfaces in terms abstract enough to allow flexible and innovative hardware implementations and concrete enough to allow shrink-wrap OS code to use such hardware interfaces. [1] • The ACPI subsystem in Linux kenrel maintains ACPI bus, ACPI device drivers , event handlers and opregion handlers...

5 ACPICA • The ACPI Component Architecture (CA) is the core of Advanced Configuration and Power Interface (ACPI) subsystem in Linux kernel. • The ACPICA provides the fundamental ACPI services that are independent of any operating system. [1] • ACPICA’s services include an AML parser/interpreter, ACPI namespace management, ACPI table management and event handling [1]. ‒ Mainly maintained by Intel: https://github.com/acpica/acpica.git • The OS Services Layer (OSL) is a conversion layer between the OS-independent ACPICA to a particular host operating system. [1]

6 Platform Kernel ACPI Subsystem Firmware ACPI Tables RSDP XSDT Hardware ACPI ACPICA root bus driver device Namespace AML Interpreter Tables node node Event FADT DSDT SSDT2SSDT1 Resource Hardware mm OSL resource printkEFIIRQqueue PCI CPU Memory pm AcpiOs* Acpi* Acpi*

7 ACPICA components • ACPI fundamental: Namespace Management, Table Management, Event Handling, Resource Manager, Hardware Management, Utilities • AML interpreter: Dispatcher, Executer, Parser, Disassembler, Debugger • OS Services Layer (OSL) ‒ ACPICA implements OSL for user space of Unix, Linux, Windows and BSD. ‒ Linux Kernel’s ACPI subsystem maintains a OSL (drivers/acpi/osl.c) to adapt ACPICA.

8 Kernel or Userland ACPICA Core Components ACPICA root Namespace AML Interpreter Tables node node Events OSL Parser Resources Hardware Utilities Disassembler Dispatcher Executer Debuggernode node node AcpiOs* Acpi*Acpi* Acpi* Acpi* Acpi* Acpi*

9 ACPICA tools • iasl: ASL compiler / AML decompiler • Tools: acpidump, acpixtract, acpinames, acpiexec... • Tests: ASL grammar validation Test Suite (ASLTS), ASL test cases • Generate: generation tools, release tools

10 ACPICA and Tools Components Namespace AML Interpreter Tables Events OSL Parser Resources Hardware Utilities Disassembler Dispatcher Executer Debugger Tools acpidump acpiexec Compiler TestsGenerate release linux msvc unix msvc9 efi acpixtract root node node node node node iasl osunix* oslinux* oswin* osbsd* efi* aslts Acpi*Acpi* AcpiOs*

11 ACPI Namespace and Event handing • ACPI Namespace ‒ A static tree structure reflects to AML definition blocks which is an abstract layer of hardware devices in platform. • ACPI Event handing ‒ ACPICA provides event mechanisms to define and to handle the dynamic behavior at runtime.

12 ACPI Namespace • The ACPI Namespace is a large data structure that is constructed and maintained by the ACPICA Subsystem component. [1] • Constructed primarily from the AML defined within an ACPI Differentiated System Description Table (DSDT), the namespace contains a hierarchy of named ACPI objects. [1] root Namespace node node

13 Namespace Initialization • Firmware puts definition blocks tables (DSDT and SSDT*) to memory. • Table Management component loads DSDT and SSDT. ‒ OSL helps to get RSDP for loading ACPI tables • Table Management component forwards DSDT/SSDT points to Namespace Management component. • Namespace Management component requests AML interpreter to parse tables. • Base on parsing result, Namespace Management component creates ACPI namespace.

14 Definition blocks, Namespace and ACPI devices [1]Load [2] [3] Parse PCI CPU Memory Companion Companion Companion PCI CPU Memory [4] handle

15 The relation between layers

16 Event types in ACPICA • ACPI Fixed Events and General Purpose Events (GPEs) ‒ System Control Interrupts (SCIs) be generated • Event types in control method ‒ Notify events that are generated via the execution of the ASL Notify keyword in a control method. [1] ‒ e.g. Notify (^^PCI0.XHC1, 0x02) // Device Wake ‒ Events that are caused by accesses to an address space or operation region during the execution of a control method. [1]

17 System Control Interrupts (SCIs) • SCI ‒ IRQ9 on x86. (otherwise checking SCI_INT in FADT) • SCI handlers ‒ in ACPICA: AcpiEvGpeXruptHandler, AcpiEvSciXruptHandler ‒ in Linux Kernel: acpi_global_event_handler

18 Fixed Events • Fixed Events ‒ ACPI events that have a predefined meaning in the ACPI specification. e.g. power button, timer overflows. ‒ These events are handled directly by the OS handlers. [2] ‒ ACPI register: PM1 = PM1a | PM1b ‒ PM1x_STS.8: PWRBTN_STS ‒ PM1x_STS.9: SLPBTN_STS ‒ PM1x_STS.10: RTC_STS ….

19 ACPI Events (Fixed Event) [1]Set [2]SCI[2]SCI [3] [3]Read Clear [4] Button Input [5] input [5]Keycode

20 GPEs • GPEs ‒ GPEs are ACPI events that are not predefined by the ACPI specification. ‒ These events are usually handled by evaluating control methods, which are objects in the namespace and can access system hardware. ‒ ACPI registers: GPE0_BLK, GPE1_BLK ‒ Control Methods: _GPE._Lxx, _GPE._Exx ‒ X86: reference GPE0_STS register in the Intel I/O Controller Hub (ICH) datasheet. ‒ watch -n 1 cat /sys/firmware/acpi/interrupts/gpe[012] [0123456789ABCDEF]

21 ACPI Events (GPE) [1]Set [2]SCI[2]SCI [3] [3]Read Clear [4] _Exx _Lxx _GPE [5] [6]Access Address space [6] NotifyPCI CPU Memory PCI CPU Memory Interactive Interactive interactive

23 ACPI Debug Log • CONFIG_ACPI_DEBUG • Kernel parameter ‒ acpi.debug_layer ‒ acpi.debug_level • sysfs /sys/module/acpi/parameters/debug_layer /sys/module/acpi/parameters/debug_level • ACPI_DEBUG_PRINT() in kernel codes [6] ‒ debug_layer: per-component level ‒ debug_level: per-type level ‒ e.g. drivers/acpi/ac.c #define _COMPONENT ACPI_AC_COMPONENT ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Unsupported event [0x%x]n", event));

24 acpi.debug_layer • ACPICA (drivers/acpi/acpica/) ‒ ACPI_UTILITIES 0x00000001 : ut*.c (except uthex.c, utuuid.c) ‒ ACPI_HARDWARE 0x00000002 : hw*.c (except hwpci.c) ‒ ACPI_EVENTS 0x00000004 : ev*.c ‒ ACPI_TABLES 0x00000008 : tb*.c ‒ ACPI_NAMESPACE 0x00000010 : ns*.c, hwpci.c ‒ ACPI_PARSER 0x00000020 : ps*.c ‒ ACPI_DISPATCHER 0x00000040 : ds*.c ‒ ACPI_EXECUTER 0x00000080 : ex*.c ‒ ACPI_RESOURCES 0x00000100 : rs*.c ‒ ACPI_CA_DEBUGGER 0x00000200 : db*.c • OSL ‒ ACPI_OS_SERVICES 0x00000400 : drivers/acpi/osl.c • ACPICA (drivers/acpi/acpica/) ‒ ACPI_CA_DISASSEMBLER 0x00000800 : No code uses it ‒ ACPI_COMPILER 0x00001000 : uthex.c, utuuid.c • acpidump tool ‒ ACPI_TOOLS 0x00002000 : tools/power/acpi/common/cmfsize.c

25 acpi.debug_layer (cont.) • ACPI Drivers (drivers/acpi/) ‒ ACPI_BUS_COMPONENT 0x00010000 : bus.c, scan.c, utils.c ‒ ACPI_AC_COMPONENT 0x00020000 : ac.c ‒ ACPI_BATTERY_COMPONENT 0x00040000 : battery.c ‒ ACPI_BUTTON_COMPONENT 0x00080000 : button.c ‒ ACPI_SBS_COMPONENT 0x00100000 : cm_sbs.c ‒ ACPI_FAN_COMPONENT 0x00200000 : fan.c (did not use ACPI_DEBUG_PRINT() yet) ‒ ACPI_PCI_COMPONENT 0x00400000 : pci_*.c (irq, link, root, slot) ‒ ACPI_POWER_COMPONENT 0x00800000 : power.c, device_pm.c ‒ ACPI_CONTAINER_COMPONENT 0x01000000 : container.c ‒ ACPI_SYSTEM_COMPONENT 0x02000000: events.c, proc.c, wakeup.c, customer_method.c, debugfs.c, sysfs.c ‒ ACPI_THERMAL_COMPONENT 0x04000000 : thermal.c ‒ ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 : acpi_memhotplug.c ‒ ACPI_VIDEO_COMPONENT 0x10000000 : video_detect.c, acpi_video.c ‒ ACPI_PROCESSOR_COMPONENT 0x20000000 : acpi_processor.c, processor_*.c (idle, core, perflib, thermal, throttling, driver, pdc) ‒ ACPI_ALL_DRIVERS 0xFFFF0000

26 Platform Kernel ACPI Subsystem and acpi.debug_layer Firmware ACPI Tables RSDP XSDT Hardware ACPI ACPICA root bus driver device Namespace AML Interpreter Tables node node Event FADT DSDT SSDT2SSDT1 Resource Hardware mm OSL resource printkEFIIRQqueue PCI CPU Memory pm AcpiOs* Acpi* Acpi* 0xFFFF0000 0x0000011F 0x00001AE0 0x00004000

27 acpi.debug_level • Raw debug output levels ‒ Do not use these in the ACPI_DEBUG_PRINT macros ‒ ACPI_LV_INIT 0x00000001 ‒ Object initialization in acpica components ‒ ACPI_LV_DEBUG_OBJECT 0x00000002 ‒ Print debug object in AML code, e.g. Store(INT1, Debug) ‒ ACPI_LV_INFO 0x00000004 ‒ General information level, drivers/acpi/*, drivers/acpi/acpica/* ‒ ACPI_LV_REPAIR 0x00000008 ‒ Repair functions in acpica namespace component ‒ ACPI_LV_TRACE_POINT 0x00000010 ‒ For debugging method and opcode in acpica

28 acpi.debug_level (cont.) • Trace verbosity level 1 [Standard Trace Level] ‒ ACPI_LV_INIT_NAMES 0x00000020 ‒ Display object's full pathname in acpica components ‒ ACPI_LV_PARSE 0x00000040 ‒ Debug log for parsing AML, drivers/acpi/acpica/ps*.c ‒ ACPI_LV_LOAD 0x00000080 ‒ Print name string for loading objects, creating region, matching gpe ‒ ACPI_LV_DISPATCH 0x00000100 ‒ Log for dispatcher in AML interpreter ‒ ACPI_LV_EXEC 0x00000200 ‒ Log for execution of control methods or a job be execution in host OS ‒ ACPI_LV_NAMES 0x00000400 ‒ Log for Namespace component in ACPICA, drivers/acpi/acpica/ns* ‒ ACPI_LV_OPREGION 0x00000800 ‒ Log for Operation Region, PCI config region, Memory address space

29 acpi.debug_level (cont.) • Trace verbosity level 1 [Standard Trace Level] (cont.) ‒ ACPI_LV_BFIELD 0x00001000 ‒ Print value when reading/writing field unit in operation region ‒ ACPI_LV_TABLES 0x00002000 ‒ Print what tables be found, dump namespace or device after tables be loaded ‒ ACPI_LV_VALUES 0x00004000 ‒ Dump the entry/device value in namespace, print the value when read/write IO port, print the value for table id or method owner id ‒ ACPI_LV_OBJECTS 0x00008000 ‒ Dump members of namespace node or members of the acpi operand object descriptor ‒ ACPI_LV_RESOURCES 0x00010000 ‒ Dump resource objects, print IRQ routing table, drivers/acpi/acpica/rs* ‒ ACPI_LV_USER_REQUESTS 0x00020000 ‒ Reserved, Not used yet ‒ ACPI_LV_PACKAGE 0x00040000 ‒ Reserved, Not used yet

30 acpi.debug_level (cont.) • Trace verbosity level 2 [Function tracing and memory allocation] ‒ ACPI_LV_ALLOCATIONS 0x00100000 ‒ Log for allocate and free object ‒ ACPI_LV_FUNCTIONS 0x00200000 ‒ Log for function entry/exit trace ‒ ACPI_LV_OPTIMIZATIONS 0x00400000 ‒ Not used in kernel. It be used in iasl, source/compiler/aslopt.c • Trace verbosity level 3 [Threading, I/O, and Interrupts] ‒ ACPI_LV_MUTEX 0x01000000 ‒ For debugging mutex and semaphore in drivers/acpi/acpica/utmutex.c, drivers/acpi/osl.c ‒ ACPI_LV_THREADS 0x02000000 ‒ Print thread id in debug message in all components ‒ ACPI_LV_IO 0x04000000 ‒ For read/write memory or io space, read/write ACPI registers (PM1/PM2…) in acpica/hw*.c ‒ ACPI_LV_INTERRUPTS 0x08000000 ‒ Log for for fixed event, GPE in acpica/evevent.c and acpica/evgpe.c

31 acpi.debug_level (cont.) • Exceptionally verbose output -- also used in the global "DebugLevel" ‒ ACPI_LV_AML_DISASSEMBLE 0x10000000 ‒ Reserved, Not used yet ‒ ACPI_LV_VERBOSE_INFO 0x20000000 ‒ Reserved, Not used yet ‒ ACPI_LV_FULL_TABLES 0x40000000 ‒ Reserved, Not used yet ‒ ACPI_LV_EVENTS 0x80000000 ‒ Reserved, Not used yet

32 ACPICA Log reducer • when the particular layer/level is applied to the control method evaluations, the quantity of the debugging outputs may still be too large to be put into the kernel log buffer. [6] • The idea thus is worked out to only enable the particular debug layer/level (normally more detailed) logs when the control method evaluation is started, and disable the detailed logging when the control method evaluation is stopped. [6] • cd /sys/module/acpi/parameters ‒ echo "0xXXXXXXXX" > trace_debug_layer ‒ echo "0xYYYYYYYY" > trace_debug_level ‒ echo "enable" > trace_state

Override ACPI definition blocks tables

34 ACPI Tables • Definition blocks tables ‒ AML (ACPI Machine Language) format ‒ DSDT (differentiated system description table), SSDT (secondary system description tables) • Data tables ‒ TDL (Table Definition Language) ‒ FADT, MADT, ECDT, SRAT, etc. - essentially any table other than a DSDT or SSDT. [2] • The iasl tool supports AML and TDL

35 Definition blocks, Namespace and ACPI devices [1]Load [2] [3] Parse [4] handle Override tables by initrd

36 Upgrading ACPI tables via initrd • CONFIG_ACPI_TABLE_UPGRADE=y ‒ Leap 15.1, Tumbleweed ‒ x86_64, arm64 • This facility also provides a powerful feature to easily debug and test ACPI BIOS table compatibility with the Linux kernel by modifying old platform provided ACPI tables or inserting new ACPI tables. [4] • All ACPI tables iasl knows should be overridable, except RSDP and FACS.

37 Override DSDT table • Extract DSDT ‒ acpidump >acpidump ‒ acpixtract acpidump • Disassemble to ASL ‒ iasl -d dsdt.dat # dsdt.dsl be created

38 Override DSDT table (cont.) • Modify DSDT ‒ vi dsdt.dsl ‒ e.g. Add debug log to _PRT Method (_PRT, 0, NotSerialized) // _PRT: PCI Routing Table { Store("HELLO WORLD", debug) …. ‒ Increase the OEM Revision < DefinitionBlock ("", "DSDT", 2, "ALASKA", "A M I ", 0x01072009) > DefinitionBlock ("", "DSDT", 2, "ALASKA", "A M I ", 0x0107200a) ‒ DefinitionBlock (AMLFileName, TableSignature, ComplianceRevision, OEMID, TableID, OEMRevision) [2]

39 Override DSDT table (cont.) • Recompile to AML ‒ iasl -sa dsdt.dsl #dsdt.aml be created • Add the dsdt.aml to initrd ‒ /kernel/firmware/acpi in an uncompressed cpio archive. ‒ The table put here matches a platform table (similar Table Signature, and similar OEMID, and similar OEM Table ID) with a more recent OEM Revision, the platform table will be upgraded by this table. [4] ‒ mkdir -p kernel/firmware/acpi cp dsdt.aml kernel/firmware/acpi find kernel | cpio -H newc --create > /boot/instrumented_initrd- 4.12.14-94.41-default cat /boot/initrd-4.12.14-94.41-default >>/boot/instrumented_initrd- 4.12.14-94.41-default

40 Override DSDT table (cont.) • Modify /boot/grub2/grub.cfg ‒ Put following kernel parameters to increase acpi debug level: acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF ‒ Change the booting initrd: < initrdefi /boot/initrd-4.12.14-94.41-default > initrdefi /boot/instrumented_initrd-4.12.14-94.41-default • Reboot

41 Override DSDT table (cont.) • dmesg after reboot [ 0.000000] ACPI: DSDT ACPI table found in initrd [kernel/firmware/acpi/dsdt.aml][0x16087] ... [ 0.000000] ACPI: Table Upgrade: override [DSDT-ALASKA- A M I ] [ 0.000000] ACPI: DSDT 0x000000005B1601F8 Physical table override, new table: 0x000000005AEF5000 … [ 0.264865] pci 0000:00:01.0: Activating ISA DMA hang workarounds [ 0.265814] [ACPI Debug] "HELLO WORLD" [ 0.287271] PCI Interrupt Link [LNKC] enabled at IRQ 10

Case: Tracing ACPI temperature

43 UP Board • up-board.org • X86_64 development board • UEFI firmware • AAEON Technology

44 UP Board responses zero degree

45 loglevel and dmesg • Kernel parameters: ‒ loglevel=9 or debug ‒ log_buf_len=5M or more • rsyslog config (/etc/rsyslog.conf) ‒ $klogConsoleLogLevel 8 • dmesg ‒ Set console level: dmesg -n 8 ‒ Clear ring buffer: sudo dmesg -C ‒ Wait for new messages: dmesg -w

46 Using debug_layer and debug_level • # echo "0x04000000" > /sys/module/acpi/parameters/debug_layer ACPI_THERMAL_COMPONENT 0x04000000 [*] • # echo "0x00000004" > /sys/module/acpi/parameters/debug_level ACPI_LV_INFO 0x00000004 [*] • dmesg -C; echo 0x04000000 > /sys/module/acpi/parameters/debug_layer; echo 0x00000004 > /sys/module/acpi/parameters/debug_level; sensors; echo 0x00000000 > /sys/module/acpi/parameters/debug_layer; echo 0x00000000 > /sys/module/acpi/parameters/debug_level;

48 More debug_layer and debug_level • # echo "0x04010010" > /sys/module/acpi/parameters/debug_layer ACPI_NAMESPACE 0x00000010 [*] ACPI_BUS_COMPONENT 0x00010000 [*] ACPI_THERMAL_COMPONENT 0x04000000 [*] • # echo "0x000fffff" > /sys/module/acpi/parameters/debug_level ‒ Enable all log in Trace verbosity level 1 [Standard Trace Level] • dmesg -C; echo 0x04010010 > /sys/module/acpi/parameters/debug_layer; echo 0x000fffff > /sys/module/acpi/parameters/debug_level; sensors; echo 0x00000000 > /sys/module/acpi/parameters/debug_layer; echo 0x00000000 > /sys/module/acpi/parameters/debug_level;

50 Tracing _TZ.TZ00._TMP in DSDT

51 The default return value from _TMP 0xAAC = 2732 match with dmesg absolute zero, degrees Kelvin

52 Add debug log in _TMP in DSDT

53 Override DSDT for debugging • # iasl -sa dsdt.dsl # mkdir -p kernel/firmware/acpi; cp dsdt.aml kernel/firmware/acpi # find kernel | cpio -H newc --create > /boot/instrumented_initrd-4.12.14-lp151.28.10-default # cat /boot/initrd-4.12.14-lp151.28.10-default >>/boot/instrumented_initrd-4.12.14-lp151.28.10- default • /boot/grub2/grub.cfg ‒ initrdefi /boot/instrumented_initrd-4.12.14-lp151.28.10-default

54 The PMIC type in DSDT debug log

56 TI Dollar Cover PMIC driver – temperature support is not ready yet • ACPI / PMIC: Add opregion driver for Intel Dollar Cove TI PMIC ‒ 313749723 commit in v4.15-rc1 6bac0606f commit in v4.15-rc1 ‒ Takashi Iwai <tiwai@suse.de> • Bug 193891 - TI Dollar Cove PMIC support for Cherrytrail platform ‒ https://bugzilla.kernel.org/show_bug.cgi?id=193891

57 Summary • Using debug_layer and debug_level to grab more information ‒ debug_layer: ‒ ACPI drivers first ‒ then ACPI fundamental components in ACPICA ‒ then AML Interpreter components ‒ debug_level: ‒ ACPI_LV_DEBUG_OBJECT and ACPI_LV_INFO first ‒ Then open Trace verbosity level 1 [Standard Trace Level] • Override DSDT or SSDT ‒ Add debug log to DSDT or SSDT

59 Reference • [1] ACPI Component Architecture User Guide and Programmer Reference Revision 6.2, May 31, 2017 • [2] Advanced Configuration and Power Interface (ACPI) Specification Version 6.3, January 2019 • [3] Linux Kernel, Documentation/firmware- guide/acpi/debug.rst • [4] Linux Kernel, Documentation/admin- guide/acpi/initrd_table_override.rst • [5] Documentation/firmware-guide/acpi/aml-debugger.rst • [6] Documentation/firmware-guide/acpi/method- tracing.rst

Thank you. 60 Feedback to jlee@suse.com

Corporate Headquarters Maxfeldstrasse 5 90409 Nuremberg Germany +49 911 740 53 0 (Worldwide) www.suse.com Join us on: www.opensuse.org 62

Unpublished Work of SUSE. All Rights Reserved. This work is an unpublished work and contains confidential, proprietary and trade secret information of SUSE. Access to this work is restricted to SUSE employees who have a need to know to perform tasks within the scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of SUSE. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability. General Disclaimer This document is not to be construed as a promise by any participating company to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. SUSE makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for SUSE products remains at the sole discretion of SUSE. Further, SUSE reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All SUSE marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.

ACPI Debugging from Linux Kernel

In this document

More Related Content

What's hot

Similar to ACPI Debugging from Linux Kernel

More from SUSE Labs Taipei

Recently uploaded

ACPI Debugging from Linux Kernel