R
ACPI Component Architecture
Programmer Reference
Core Subsystem, Debugger, and Utilities
Revision 1.16
April 18, 2003
ACPI Component Architecture Programmer Reference
R
2 Ref No SC-<xxxx>
Information in this document is provided in connection with Intel® products. No license, express or implied, by estoppel or otherwise, to any intellectual
property rights is granted by this document. Except as provided in Intel’s Terms and Conditions of Sale for such products, Intel assumes no liability
whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to
fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not
intended for use in medical, life saving, or life sustaining applications.
Intel may make changes to specifications and product descriptions at any time, without notice.
Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for
future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.
The <Product Name> may contain design defects or errors known as errata which may cause the product to deviate from published specifications.
Current characterized errata are available on request.
Copyright © 2000 - 2003 Intel Corporation
*Other brands and names are the property of their respective owners.
R
ACPI Component Architecture Programmer Reference
Ref No SC-<xxxx> 3
Contents
1 Introduction......................................................................................................................11
1.1 Document Structure .............................................................................................11
1.2 Rationale and Justification ...................................................................................11
1.3 Reference Documents..........................................................................................12
1.4 Overview of the ACPI Component Architecture...................................................12
1.5 Overview of the ACPI Core Subsystem ...............................................................13
1.5.1 ACPI Core Subsystem ............................................................................14
1.5.2 Operating System Services Layer...........................................................14
1.5.3 Relationships Between the Host OS, Core Subsystem, and OSL..........15
1.5.3.1 Host Operating System Interaction..........................................15
1.5.3.2 OS Services Layer Interaction.................................................15
1.5.3.3 ACPI Core Subsystem Interaction...........................................16
1.6 Architecture of the ACPI Core Subsystem...........................................................17
1.6.1 AML Interpreter .......................................................................................17
1.6.2 ACPI Table Management........................................................................17
1.6.3 Namespace Management .......................................................................18
1.6.4 Resource Management...........................................................................18
1.6.5 ACPI Hardware Management .................................................................18
1.6.6 Event Handling ........................................................................................18
1.7 Architecture of the OS Services Layer (OSL) ......................................................19
1.7.1 Functional Service Groups......................................................................19
1.7.1.1 OS Bootload-Time Services ....................................................20
1.7.1.2 Device Driver Load-Time Services ..........................................20
1.7.1.3 OS Run-Time Services............................................................20
1.7.1.4 Asynchronous Services ...........................................................20
1.7.2 Required Functionality.............................................................................20
1.7.2.1 Requests from OS to ACPI Subsystem...................................20
1.7.2.2 Requests from Application to ACPI Subsystem ......................21
1.7.2.3 Requests from ACPI Subsystem to OS...................................21
2 Design Overview .............................................................................................................23
2.1 ACPI Namespace Fundamentals.........................................................................23
2.1.1 Named Objects........................................................................................23
2.1.2 Scopes.....................................................................................................23
2.1.3 Predefined Objects..................................................................................24
2.1.4 Logical Namespace Layout.....................................................................24
2.2 Execution Model...................................................................................................25
2.2.1 Initialization..............................................................................................25
2.2.2 Memory Allocation...................................................................................25
2.2.2.1 Caller Allocates All Buffers ......................................................26
2.2.2.2 ACPI Allocates Return Buffers ................................................26
2.2.3 Parameter Validation...............................................................................27
2.2.4 Exception Handling .................................................................................27
2.2.5 Multitasking and Reentrancy...................................................................27
2.2.6 Event Handling ........................................................................................27
2.2.6.1 Fixed Events ............................................................................28
2.2.6.2 General Purpose Events .........................................................28
2.2.6.3 Notify Events............................................................................28
2.2.7 Address Spaces and Operation Regions ................................................28
2.2.7.1 Installation of Address Space Handlers...................................29
2.2.7.2 ACPI-Defined Address Spaces ...............................................29
ACPI Component Architecture Programmer Reference
R
4 Ref No SC-<xxxx>
2.3
Policies and Philosophies.....................................................................................30
2.3.1 External Interfaces ..................................................................................30
2.3.1.1 Exception Codes......................................................................30
2.3.1.2 Memory Buffers .......................................................................30
2.3.2 Subsystem Initialization...........................................................................30
2.3.2.1 ACPI Table Validation..............................................................30
2.3.2.2 Required ACPI Tables.............................................................31
3 Design and Implementation Details...............................................................................32
3.1 Required Host OS Initialization Sequence...........................................................32
3.1.1 Bootload and Low Level Kernel Initialization ..........................................32
3.1.2 ACPI CA Subsystem Initialization ...........................................................32
3.1.3 Other OS Initialization .............................................................................32
3.1.4 Device Enumeration, Configuration, and Initialization ............................32
3.1.5 Final OS Initialization...............................................................................33
3.2 Required ACPI CA Initialization Sequence ..........................................................33
3.2.1 ACPI CA Subsystem Initialization ...........................................................33
3.2.1.1 AcpiInitializeSubsystem...........................................................33
3.2.2 ACPI Table and Namespace Initialization...............................................33
3.2.2.1 AcpiLoadFirmwareTables........................................................33
3.2.2.2 AcpiLoadTable.........................................................................33
3.2.2.3 Internal ACPI Namespace Initialization ...................................34
3.2.3 Handler Installation..................................................................................34
3.2.3.1 Handler Types .........................................................................34
3.2.4 Subsystem Initialization Completion .......................................................34
3.2.4.1 AcpiEnableSubsystem.............................................................34
3.2.4.2 ACPI Hardware and Event Initialization...................................35
3.2.4.3 Just-in-time Address Space Initialization.................................35
3.2.4.4 AcpiIntializeObjects .................................................................36
3.2.4.5 Other Operating System ACPI-related Initialization ................36
3.2.5 System Shutdown ...................................................................................37
3.2.5.1 AcpiTerminate..........................................................................37
3.3 Multithreading Support .........................................................................................37
3.3.1 Reentrancy..............................................................................................37
3.3.2 Control Method Execution.......................................................................37
3.3.2.1 Control Method Blocking .........................................................37
3.3.2.2 Control Method Execution Rules .............................................38
3.3.2.3 A Simple Multithreading Model................................................38
3.3.2.4 A More Complex Multithreading Model ...................................39
3.3.3 Global Lock Support................................................................................40
3.3.3.1 Obtaining The Global Lock ......................................................41
3.3.3.2 Releasing the Global Lock.......................................................41
3.3.3.3 Global Lock Interrupt Handler..................................................42
3.3.4 Single Thread Environments...................................................................42
3.4 Debugging Support ..............................................................................................42
3.4.1 Function Tracing (ACPI_FUNCTION_TRACE Macro)............................42
3.4.2 Execution Debug Output (ACPI_DEBUG_PRINT Macro) ......................43
3.4.3 ACPI Debugger .......................................................................................44
3.5 Environmental Support Requirements .................................................................44
3.5.1 Resource Requirements..........................................................................44
3.5.2 C Library Functions .................................................................................44
3.5.3 System Include Files ...............................................................................45
3.5.3.1 Customization to the Target Environment ...............................45
4 Interface Parameters and Data Types...........................................................................47
4.1 ACPI Subsystem Interface Parameters ...............................................................47
R
ACPI Component Architecture Programmer Reference
Ref No SC-<xxxx> 5
4.1.1
ACPI Names and Pathnames .................................................................47
4.1.2 Pointers ...................................................................................................47
4.1.3 Buffers .....................................................................................................47
4.2 ACPI Subsystem Data Types...............................................................................48
4.2.1 UINT64 and COMPILER_DEPENDENT_UINT64 ..................................48
4.2.2 ACPI_PHYSICAL_ADDRESS.................................................................48
4.2.3 ACPI_POINTER ......................................................................................48
4.2.4 ACPI_INTEGER ......................................................................................48
4.2.5 ACPI_STRING – ASCII String ................................................................48
4.2.6 ACPI_BUFFER – Input and Output Memory Buffers ..............................48
4.2.6.1 Input Buffer ..............................................................................49
4.2.6.2 Output Buffer ...........................................................................49
4.2.7 ACPI_HANDLE – Object Handle ............................................................49
4.2.7.1 Predefined Handles .................................................................50
4.2.8 ACPI_OBJECT_TYPE – Object Type Codes .........................................50
4.2.9 ACPI_OBJECT – Method Parameters and Return Objects....................50
4.2.10 ACPI_OBJECT_LIST – List of Objects ...................................................52
4.2.11 ACPI_EVENT_TYPE – Fixed Event Type Codes...................................52
4.2.12 ACPI_TABLE_TYPE – ACPI Table Type Codes ....................................52
4.2.13 ACPI_TABLE_HEADER – Common ACPI Table Header ......................52
4.2.14 ACPI_STATUS – Interface Exception Return Codes .............................53
4.3 ACPI Resource Data Types .................................................................................53
4.3.1 PCI IRQ Routing Tables..........................................................................53
4.3.2 Device Resources ...................................................................................54
4.3.2.1 RESOURCE_TYPE – Resource Data Types..........................54
4.4 Exception Codes ..................................................................................................56
5 Subsystem Configuration...............................................................................................59
5.1 Configuration Files ...............................................................................................59
5.2 Per-Compiler Configuration..................................................................................59
5.2.1 ACPI_DIV_64_BY_32 (Short 64-bit Divide)............................................59
5.2.2 ACPI_SHIFT_RIGHT_64 (64-bit Shift)....................................................59
5.2.3 ACPI_EXTERNAL_XFACE.....................................................................59
5.2.4 ACPI_INTERNAL_XFACE ......................................................................60
5.2.5 ACPI_INTERNAL_VAR_XFACE.............................................................60
5.2.6 ACPI_SYSTEM_XFACE .........................................................................60
5.2.7 ACPI_PRINTF_LIKE_FUNC ...................................................................60
5.2.8 ACPI_UNUSED_VAR .............................................................................60
5.2.9 COMPILER_DEPENDENT_INT64 .........................................................60
5.2.10 COMPILER_DEPENDENT_UINT64.......................................................60
5.3 Per-Machine Configuration...................................................................................60
5.3.1 ACPI_ASM_MACROS ............................................................................60
5.3.2 ACPI_FLUSH_CPU_CACHE..................................................................61
5.3.3 ACPI_MACHINE_WIDTH........................................................................61
5.3.4 ACPI_OS_NAME ....................................................................................61
5.3.5 ACPI_USE_STANDARD_HEADERS .....................................................61
5.3.6 ACPI_ACQUIRE_GLOBAL_LOCK .........................................................61
5.3.7 ACPI_RELEASE_GLOBAL_LOCK .........................................................61
5.4 Other Compile-time Configuration........................................................................61
5.4.1 ACPI_APPLICATION ..............................................................................61
5.4.2 ACPI_DEBUG .........................................................................................61
5.4.3 PARSER_ONLY......................................................................................62
5.5 Configuration of Subsystem Constants................................................................62
5.5.1 MAX_STATE_CACHE_DEPTH..............................................................62
5.5.2 MAX_PARSE_CACHE_DEPTH .............................................................62
