4. 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. 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]
9. 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
11. 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. 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. 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. 14
Definition blocks, Namespace and
ACPI devices
[1]Load
[2]
[3] Parse
PCI
CPU
Memory
Companion
Companion
Companion
PCI
CPU
Memory
[4] handle
16. 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. 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. 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
….
20. 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]
26. 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. 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. 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. 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. 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. 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. 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
34. 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
36. 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. 37
Override DSDT table
• Extract DSDT
‒ acpidump >acpidump
‒ acpixtract acpidump
• Disassemble to ASL
‒ iasl -d dsdt.dat # dsdt.dsl be created
38. 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. 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. 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. 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
56. 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. 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
63. 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.