Profiling the ACPICA Namespace and Event Handing

Profiling the ACPICA
Namespace and Event
Handing
September, 2019, SUSE Labs Conference 2019, Špindlerův
mlýn
Joey Lee
SUSE Labs Taipei
jlee@suse.com

2
Agenda
• Components in ACPICA
• ACPICA in Linux Kernel
• Definition blocks and ACPI Namespace
• The Fixed event and GPE handling
• Q&A

3
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]
• Mainly maintained by Intel
‒ https://github.com/acpica/acpica.git

4
ACPICA (cont.)
• ACPICA’s services include an AML
parser/interpreter, ACPI namespace management,
ACPI table management and event handling [1].
• The OS Services Layer (OSL) is a conversion layer
between the OS-independent ACPICA to a particular
host operating system. [1]

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

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*

12
ACPI host and ACPICA
• OSL in Linux Kernel: drivers/acpi/osl.c
• ACPICA-to-host: All ACPICA-to-host interactions
pass through the OSL via direct calls to the AcpiOs*
interfaces from ACPICA. [1]
• Host-to-ACPICA
‒ Synchronous: the host making direct calls to the various
public Acpi* interfaces. [1]
‒ Asynchronous: The host calls ACPICA to install an
appropriate handler at initialization time. This handler is
then invoked by ACPICA whenever the requested event
occurs. (handle fixed events or GPE) [1]

13
OSL Services
• Environmental: enable acpi mode
• Memory Management: mm
• Multitasking Support
• Mutual Exclusion and Synchronization
• Interrupt handling: IRQ
• Address Spaces
• Stream I/O: printk

14
Platform
Kernel
ACPICA in Linux Kernel
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*

Definition blocks and ACPI Namespace

16
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

17
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

18
Definition blocks, Namespace and
ACPI devices
Tables
OSL
EFI
ACPI Tables
RSDP XSDT
FADT DSDT
SSDT2SSDT1
root
Namespace
AML
Interpreter
node node
bus
driver device

19
ACPI devices
[1]Load

20
ACPI devices
[1]Load
[2]

21
ACPI devices
[1]Load
[2]
[3] Parse

22
ACPI devices
[1]Load
[2]
[3] Parse
[4] handle

23
ACPI devices
[1]Load
[2]
[3] Parse
PCI
CPU
Memory
Companion
Companion
Companion
PCI
CPU
Memory
[4] handle

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

25
ACPICA
Table to Namespace
tables
2) AcpiTbLoadNamespace
namespace
2.1.1) AcpiNsParseTable
2.1.1.1) AcpiNsExecuteTable
3.1) AcpiNsInitOneObject
2.1) AcpiNsLoadTable
3) AcpiNsInitializeObjects
2.1.2) AcpiDsInitializeObjects
0) acpi_load_tables
(AcpiLoadTables)
Kernel
drivers/acpi/bus.c
events
1) AcpiEvInstallRegionHandlers
dispatcher
2.1.1.1) AcpiPsExecuteTable
parser
2.1.1.1.1) AcpiPsCreateScopeOp
2.1.1.1.5) AcpiPsParseAml
2.1.1.1.2) AcpiDsCreateWalkState
2.1.1.1.3) AcpiDsInitAmlWalk
2.1.1.1.4) AcpiDsScopeStackPush
2.1.1.1.6) AcpiDsDeleteWalkState
2.1.1.1.7) AcpiPsDeleteParseTree

26
ACPICA
Evaluate method/object
namespace
1) AcpiNsValidateHandle
2) AcpiNsEvaluate
2.1) AcpiNsGetNode
2.4) AcpiNsCheckReturnValue
3) AcpiNsResolveReferences
0) acpi_evaluate_object
(AcpiEvaluateObject)
Kernel
drivers/acpi/utils.c
tables
2.2.1) AcpiTbCheckDsdtHeader
dispatcher
2.2) AcpiPsExecuteMethod
parser
2.2.3) AcpiPsUpdateParameterList
2.2.4) AcpiPsCreateScopeOp
2.2.7) AcpiPsParseAml
2.2.8) AcpiPsDeleteParseTree
2.2.9) AcpiPsUpdateParameterList
2.2.2) AcpiDsBeginMethodExecution
2.2.5) AcpiDsCreateWalkState
2.2.6) AcpiDsInitAmlWalk
executer
2.3) AcpiExResolveNodeToValue

27
The relation between layers

28

29

30

31

32

33

34

35

36
Class diagram for ACPI Namespace

The Fixed event and GPE handling

38
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]
‒ Events that are caused by accesses to an address space
or operation region during the execution of a control
method. [1]

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

40
ACPI Events
OSL
root
Namespace
AML
Interpreter
node node
bus
driver device
Hardware
Event
Platform Firmware ACPI Registers
Hardware
FADT PM1a
IRQ
GPE0
PM1b
GPE1
Sleep
Timer

42
ACPI Events
[1]Set
[2]SCI[2]SCI

43
ACPI Events
[1]Set
[2]SCI[2]SCI
[3]
[3]Read
Clear

44
ACPI Events (Fixed Event)
[1]Set
[2]SCI[2]SCI
[3]
[3]Read
Clear
[4] Button

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

46
ACPI Events (GPE)
[1]Set
[2]SCI[2]SCI
[3]
[3]Read
Clear
_Exx _Lxx
_GPE

47
ACPI Events (GPE)
[1]Set
[2]SCI[2]SCI
[3]
[3]Read
Clear
[4]
_Exx _Lxx
_GPE
[5]

48
ACPI Events (GPE)
[1]Set
[2]SCI[2]SCI
[3]
[3]Read
Clear
[4]
_Exx _Lxx
_GPE
[5]
[6]Access
Address space
[6] Notify

49
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

50
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
….

51
ACPICA
Events (fixed)
events
1) AcpiEvFixedEventDetect
1.3) AcpiEvFixedEventDispatch
2) AcpiEvGpeDetect
3) AcpiEvSciDispatch
Kernel
0) acpi_ev_sci_xrupt_handler
(AcpiEvSciXruptHandler)
1.1) AcpiHwRegisterRead
Kernel/irq
drivers/acpi
1.2) acpi_global_event_handler
(AcpiGbl_GlobalEventHandler)
bus.csysfs.c
1.3.1) acpi_device_fixed_event
(AcpiGbl_FixedEventHandlers[Event].Handle)
button.c
1.3.1.x) notify
hardware

52
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]

53
ACPICA
Events (GPE)
events
1) AcpiEvFixedEventDetect
2) AcpiEvGpeDetect
2.1) AcpiEvDetectGpe
2.1.4) AcpiEvGpeDispatch
2.1.4.4.1) AcpiEvQueueNotifyRequest
3) AcpiEvSciDispatch
Kernel
0) acpi_ev_sci_xrupt_handler
(AcpiEvSciXruptHandler)
hardware
2.1.4.4.2.2) AcpiPsExecuteMethod
executer
2.1.4.4.2.3) AcpiExResolveNodeToValue
Kernel/irq
drivers/acpi
ec.csysfs.c osl.c
2.1.1) AcpiHwRead
2.1.4.1) AcpiHwLowSetGpe
2.1.4.2) AcpiHwClearGpe
2.1.2) acpi_global_event_handler
(AcpiGbl_GlobalEventHandler)
2.1.3) acpi_ec_gpe_handler
(GpeHandlerInfo->Address)
Kernel/workqueue
queue
Namespace
2.1.4.4.2.1) AcpiNsGetNode
2.1.4.4.2.4) AcpiNsCheckReturnValue
2.1.4.4.2) AcpiNsEvaluate
parser
2.1.4.4) AcpiEvAsynchExecuteGpeMethod
2.1.4.3) acpi_os_execute

54
Example: EC and _Qxx
• A general-purpose event is raised from the GPE bit
tied to an embedded controller, the embedded
controller driver uses another naming convention
defined by ACPI for the embedded controller driver
to determine which control method to queue for
execution.
• The name of the control method to queue is always
of the form _Qxx where xx is the number of the
query acknowledged by the embedded controller.

55
Class diagram for _Qxx event handling

56
Summary
• The interactive between two framework: Linux
Kernel and ACPICA
• ACPI Namespace: An abstract layer between
hardware platform and OS
• ACPI event handing: To define and handle the
dynamic behavior between platform and OS

58
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

Thank you.
59
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
61

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.

Profiling the ACPICA Namespace and Event Handing

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Profiling the ACPICA Namespace and Event Handing

Similar to Profiling the ACPICA Namespace and Event Handing (20)

More from SUSE Labs Taipei

More from SUSE Labs Taipei (18)

Recently uploaded

Recently uploaded (20)

Profiling the ACPICA Namespace and Event Handing