9. ACPI System Description Table Protocol

9.1. EFI_ACPI_SDT_PROTOCOL

Summary

Provides services for creating ACPI system description tables.

GUID

#define EFI_ACPI_SDT_PROTOCOL_GUID \
  { 0xeb97088e, 0xcfdf, 0x49c6, \
  { 0xbe, 0x4b, 0xd9, 0x6, 0xa5, 0xb2, 0xe, 0x86 } }

Protocol Interface Structure

typedef struct _EFI_ACPI_SDT_PROTOCOL {
  EFI_ACPI_TABLE_VERSION        AcpiVersion;
  EFI_ACPI_GET_TABLE2           GetAcpiTable;
  EFI_ACPI_REGISTER_NOTIFY      RegisterNotify;
  EFI_ACPI_OPEN                 Open;
  EFI_ACPI_OPEN_SDT             OpenSdt;
  EFI_ACPI_CLOSE                Close;
  EFI_ACPI_GET_CHILD            GetChild;
  EFI_ACPI_GET_OPTION           GetOption;
  EFI_ACPI_SET_OPTION           SetOption;
  EFI_ACPI_FIND_PATH            FindPath;
} EFI_ACPI_SDT_PROTOCOL;

#define UINT32 EFI_ACPI_TABLE_VERSION;

#define EFI_ACPI_TABLE_VERSION_NONE (1 << 0)
#define EFI_ACPI_TABLE_VERSION_1_0B (1 << 1)
#define EFI_ACPI_TABLE_VERSION_2_0 (1 << 2)
#define EFI_ACPI_TABLE_VERSION_3_0 (1 << 3)
#define EFI_ACPI_TABLE_VERSION_4_0 (1 << 4)
#define EFI_ACPI_TABLE_VERSION_5_0 (1 << 5)

Members

AcpiVersion: A bit map containing all the ACPI versions supported by this protocol.
GetTable: Enumerate the ACPI tables.
RegisterNotify: Register a notification when a table is installed.
Open: Create a handle from an ACPI opcode.
OpenSdt: Create a handle from an ACPI table.
Close: Close an ACPI handle.
GetChild: Cycle through the child objects of an ACPI handle.
GetOption: Return one of the optional pieces of the opcode.
SetOption: Change one of the optional pieces of the opcode.
FindPath: Given an ACPI path, return an ACPI handle.

9.1.1. EFI_ACPI_SDT_PROTOCOL.GetAcpiTable()

Summary

Returns a requested ACPI table.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_GET_ACPI_TABLE) (
  IN UINTN                    Index,
  OUT EFI_ACPI_SDT_HEADER     **Table,
  OUT EFI_ACPI_TABLE_VERSION  *Version,
  OUT UINTN                   *TableKey
  );

Parameters

Index: The zero-based index of the table to retrieve.
Table: Pointer for returning the table buffer. Type EFI_ACPI_SDT_HEADER is defined in “Related Definitions” below.
Version: On return, updated with the ACPI versions to which this table belongs. Type EFI_ACPI_TABLE_VERSION is defined in “Related Definitions” in the EFI_ACPI_SDT_PROTOCOL .
TableKey: On return, points to the table key for the specified ACPI system definition table. This is identical to the table key used in the EFI_ACPI_TABLE_PROTOCOL . The TableKey can be passed to EFI_ACPI_TABLE_PROTOCOL.UninstallAcpiTable() to uninstall the table.

Description

The GetAcpiTable( ) function returns a pointer to a buffer containing the ACPI table associated with the Index that was input. The following structures are not considered elements in the list of ACPI tables:

Root System Description Pointer (RSD_PTR)
Root System Description Table (RSDT)
Extended System Description Table (XSDT)

Version is updated with a bit map containing all the versions of ACPI of which the table is a member.

For tables installed via the EFI_ACPI_TABLE_PROTOCOL.InstallAcpiTable() interface, the function returns the value of EFI_ACPI_STD_PROTOCOL.AcpiVersion .

typedef struct {
  UINT32  Signature;
  UINT32  Length;
  UINT8   Revision;
  UINT8   Checksum;
  CHAR8   OemId[6];
  CHAR8   OemTableId[8];
  UINT32  OemRevision;
  UINT32  CreatorId;
  UINT32  CreatorRevision;
} EFI_ACPI_SDT_HEADER;

This structure is based on the DESCRIPTION_HEADER structure, defined in section 5.2.6 of the ACPI 3.0 specification .

Status Codes Returned

EFI_SUCCESS	The function completed successfully
EFI_NOT_FOUND	The requested index is too large and a table was not found

9.1.2. EFI_ACPI_SDT_PROTOCOL.RegisterNotify()

Summary

Register or unregister a callback when an ACPI table is installed.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_REGISTER_NOTIFY) (
  IN BOOLEAN                     Register,
  IN EFI_ACPI_NOTIFICATION_FN    Notification
);

Parameters

Register: If TRUE , then the specified function will be registered. If FALSE , then the specified function will be unregistered.
Notification: Points to the callback function to be registered or unregistered. Type EFI_ACPI_NOTIFICATION_FN is defined in “Related Definitions” below.

Description

This function registers or unregisters a function which will be called whenever a new ACPI table is installed.

Status Codes Returned

EFI_SUCCESS	Callback successfully registered or unregistered
EFI_INVALID_PARAMETER	Notification is NULL
EFI_INVALID_PARAMETER	Register is FALSE and Notification does not match a known registration function

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_NOTIFICATION_FN)(
  IN EFI_ACPI_SDT_HEADER           *Table,
  IN EFI_ACPI_TABLE_VERSION        Version,
  IN UINTN                         TableKey
  );

Table: A pointer to the ACPI table header.
Version: The ACPI table’s version. Type EFI_ACPI_TABLE_VERSION is defined in “Related Definitions” in the EFI_ACPI_SDT_PROTOCOL .
TableKey: The table key for this ACPI table. This is identical to the table key used in the EFI_ACPI_TABLE_PROTOCOL . This function is called each time a new ACPI table is added using EFI_ACPI_TABLE_PROTOCOl.InstallAcpiTable() .

9.1.3. EFI_ACPI_SDT_PROTOCOL.Open()

Summary

Create a handle from an ACPI opcode

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_OPEN) (
  IN VOID              *Buffer,
  OUT EFI_ACPI_HANDLE  *Handle
);

Parameters

Buffer: Points to the ACPI opcode.
Handle: Upon return, holds the handle.

typedef VOID *EFI_ACPI_HANDLE;

Description

Creates a handle from a single ACPI opcode.

Status Code Values

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	Buffer is NULL or Handle is NULL or Buffer points to an invalid opcode.

9.1.4. EFI_ACPI_SDT_PROTOCOL.OpenSdt()

Summary

Create a handle for the first ACPI opcode in an ACPI system description table.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_OPEN_SDT) (
  IN UINTN               TableKey,
  OUT EFI_ACPI_HANDLE    *Handle
);

Parameters

TableKey: The table key for the ACPI table, as returned by GetTable() .
Handle: On return, points to the newly created ACPI handle. Type EFI_ACPI_HANDLE is defined in “Related Definitions” below.

Description

Creates an ACPI handle for the top-level opcodes in the ACPI system description table specified by TableKey .

typedef VOID   *EFI_ACPI_HANDLE;

Status Codes Returned

EFI_SUCCESS	Handle created successfully.
EFI_NOT_FOUND	TableKey does not refer to a valid ACPI table.

9.1.5. EFI_ACPI_SDT_PROTOCOL.Close()

Summary

Close an ACPI handle.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_CLOSE) (
  IN EFI_ACPI_HANDLE        Handle
);

Parameters

Handle: Returns the handle. Type EFI_ACPI_HANDLE is defined in Open() .

Description

Closes the ACPI handle and, if any changes were made, updates the table checksum.

Status Code Values

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	Handle is NULL or does not refer to a valid ACPI object.

9.1.6. EFI_ACPI_SDT_PROTOCOL.GetChild()

Summary

Return the child ACPI objects.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_ENUM) (
  IN EFI_ACPI_HANDLE        ParentHandle,
  IN OUT EFI_ACPI_HANDLE    *Handle
);

Parameters

ParentHandle: Parent handle.
Handle: On entry, points to the previously returned handle or NULL to start with the first handle. On return, points to the next returned ACPI handle or NULL if there are no child objects.

Description

Iterates through all children ACPI objects of the ACPI object specified by the handle ParentHandle .

Status Code Values

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	ParentHandle is NULL or does not refer to a valid ACPI object.

9.1.7. EFI_ACPI_SDT_PROTOCOL.GetOption()

Summary

Retrieve information about an ACPI object.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_GET_OPTION) (
  IN EFI_ACPI_HANDLE          Handle,
  IN UINTN                    Index,
  OUT EFI_ACPI_DATA_TYPE      *DataType,
  OUT CONST VOID              **Data,
  OUT UINTN                   *DataSize
  );

Parameters

Handle: ACPI object handle.
Index: Index of the data to retrieve from the object. In general, indexes read from left-to-right in the ACPI encoding, with index 0 always being the ACPI opcode.
DataType: Points to the returned data type or EFI_ACPI_DATA_TYPE_NONE if no data exists for the specified index. See EFI_ACPI_DATA_TYPE in Related Definitions.
Data: Upon return, points to the pointer to the data.
DataSize: Upon return, points to the size of Data .

typedef UINT32 EFI_ACPI_DATA_TYPE;

#define EFI_ACPI_DATA_TYPE_NONE           0
#define EFI_ACPI_DATA_TYPE_OPCODE         1
#define EFI_ACPI_DATA_TYPE_NAME_STRING    2
#define EFI_ACPI_DATA_TYPE_OP             3
#define EFI_ACPI_DATA_TYPE_UINT           4
#define EFI_ACPI_DATA_TYPE_STRING         5
#define EFI_ACPI_DATA_TYPE_CHILD          6

Description

Retrieves various fields encoded within the ACPI object. All ACPI objects support at least index 0.

The EFI_ACPI_DATA_TYPE_NONE indicates that the specified ACPI object does not support the specified option. The EFI_ACPI_DATA_TYPE_OPCODE indicates that the option is an ACPI opcode. The EFI_ACPI_DATA_TYPE_NAME_STRING indicates that the option is an ACPI name string. The EFI_ACPI_DATA_TYPE_OP indicates that the option is an ACPI opcode. The Open() function can be used to manipulate the contents of this ACPI opcode. The EFI_ACPI_DATA_TYPE_UINT indicates that the option is an unsigned integer. The size of the integer is indicated by DataSize . The EFI_ACPI_DATA_TYPE_STRING indicates that the option is a string whose length is indicated by DataSize . The EFI_ACPI_DATA_TYPE_CHILD indicates that the opcode has child data, pointed to by Data , with the size DataSize.

Table 9.7 AML terms and supported options
Term	0	1	2	3	4	5	6
ACPI_OP_ZERO	0000
ACPI_OP_ONE	0001
ACPI_OP_ALIAS	0006	N	N
ACPI_OP_NAME	0008	N	O
ACPI_OP_BYTE	000A	U8
ACPI_OP_WORD	000B	U16
ACPI_OP_DWORD	000C	U32
ACPI_OP_STRING	000D	S
ACPI_OP_QWORD	000E	U64
ACPI_OP_SCOPE	0010	N
ACPI_OP_BUFFER	0011	O
ACPI_OP_PACKAGE	0012	U8
ACPI_OP_PACKAGE1	0013	O
ACPI_OP_METHOD	0014	N	U8
ACPI_OP_LOCAL0	0060
ACPI_OP_LOCAL1	0061
ACPI_OP_LOCAL2	0062
ACPI_OP_LOCAL3	0063
ACPI_OP_LOCAL4	0064
ACPI_OP_LOCAL5	0065
ACPI_OP_LOCAL6	0066
ACPI_OP_LOCAL7	0067
ACPI_OP_ARG0	0068
ACPI_OP_ARG1	0069
ACPI_OP_ARG2	006A
ACPI_OP_ARG3	006B
ACPI_OP_ARG4	006C
ACPI_OP_ARG5	006D
ACPI_OP_ARG6	006E
ACPI_OP_STORE	0070	O	O
ACPI_OP_REFOF	0071	O
ACPI_OP_ADD	0072	O	O	O
ACPI_OP_CONTACT	0073	O	O	O
ACPI_OP_SUBTRACT	0074	O	O	O
ACPI_OP_INCREMENT	0075	O
ACPI_OP_DECREMENT	0076	O
ACPI_OP_MULTIPLY	0077	O	O	O
ACPI_OP_DIVIDE	0078	O	O	O	O
ACPI_OP_SHIFTLEFT	0079	O	O	O
ACPI_OP_SHIFTRIGHT	007A	O	O	O
ACPI_OP_AND	007B	O	O	O
ACPI_OP_NAND	007C	O	O	O
ACPI_OP_OR	007D	O	O	O
ACPI_OP_NOR	007E	O	O	O
ACPI_OP_XOR	007F	O	O	O
ACPI_OP_NOT	0080	O	O
ACPI_OP_FINDSETLEFTBIT	0081	O	O
ACPI_OP_FINDSETRIGHTBIT	0082	O	O
ACPI_OP_DEREFOF	0083	O
ACPI_OP_CONCATENATE	0084	O	O	O
ACPI_OP_MODULO	0085	O	O	O
ACPI_OP_NOTIFY	0086	O	O
ACPI_OP_SIDEOF	0087	O
ACPI_OP_INDEX	0088	O	O	O
ACPI_OP_MATCH	0089	O	U8	O	U8	O	O
ACPI_OP_OBJECTTYPE	008E	O
ACPI_OP_LAND	0090	O	O
ACPI_OP_LOR	0091	O	O
ACPI_OP_LNOT	0092	O
ACPI_OP_LEQUAL	0093	O	O
ACPI_OP_LGREATER	0094	O	O
ACPI_OP_LLESS	0095	O	O
ACPI_OP_TOBUFFER	0096	O	O
ACPI_OP_TODECIMALSTRING	0097	O	O
ACPI_OP_TOHEXSTRING	0098	O	O
ACPI_OP_TOINTEGER	0099	O	O
ACPI_OP_TOSTRING	009C	O	O	O
ACPI_OP_COPYOBJECT	009D	O	O
ACPI_OP_MID	009E	O	O	O
ACPI_OP_CONTINUE	009F
ACPI_OP_IF	00A0	O
ACPI_OP_ELSE	00A1
ACPI_OP_WHILE	00A2	O
ACPI_OP_NOP	00A3
ACPI_OP_RETURN	00A4	O
ACPI_OP_BREAK	00A5
ACPI_OP_BREAKPOINT	00CC
ACPI_OP_ONES	00FF
ACPI_OP_MUTEX	5B01	N	U8
ACPI_OP_EVENT	5B02	N
ACPI_OP_CONDREFOF	5B12	O	O
ACPI_OP_CREATEFIELD	5B13	O	O	O	N
ACPI_OP_LOADTABLE	5B1F	O	O	O	O	O	O
ACPI_OP_LOAD	5B20	N	O
ACPI_OP_STALL	5B21	O
ACPI_OP_SLEEP	5B22	O
ACPI_OP_ACQUIRE	5B23	O	U16
ACPI_OP_SIGNAL	5B24	O
ACPI_OP_WAIT	5B25	O	O
ACPI_OP_RESET	5B26	O
ACPI_OP_RELEASE	5B27	O
ACPI_OP_FROMBCD	5B28	O	O
ACPI_OP_TOBCD	5B29	O	O
ACPI_OP_UNLOAD	5B2A	O
ACPI_OP_REVISION	5B30
ACPI_OP_DEBUG	5B31
ACPI_OP_FATAL	5B32	U8	U32	O
ACPI_OP_TIMER	5B33
ACPI_OP_OPERATIONREGION	5B80	N	U8	U32	O
ACPI_OP_FIELD	5B81	N	U8
ACPI_OP_DEVICE	5B82	N
ACPI_OP_PROCESSOR	5B83	N	U8	U32	U8
ACPI_OP_POWERRESOURCE	5B84	N	U8	U16
ACPI_OP_THERMALZONE	5B85	N
ACPI_OP_INDEXFIELD	5B86	N	N	U8
ACPI_OP_BANKFIELD	5B87	N	N	O	U8
ACPI_OP_DATAREGION	5B88	N	O	O	O
ACPI_OP_CREATEDWORDFIELD	5B8A	O	O	N
ACPI_OP_CREATEWORDFIELD	5B8B	O	O	N
ACPI_OP_CREATEBYTEFIELD	5B8C	O	O	N
ACPI_OP_CREATEBITFIELD	5B8D	O	O	N
ACPI_OP_CREATEQWORDFIELD	5B8F	O	O	N

Status Code Returns

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	Handle is NULL or does not refer to a valid ACPI object.

9.1.8. EFI_ACPI_SDT_PROTOCOL.SetOption()

Summary

Change information about an ACPI object.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_SET_OPTION) (
  IN EFI_ACPI_HANDLE    Handle,
  IN UINTN              Index,
  IN CONST VOID         *Data,
  IN UINTN              DataSize
);

Parameters

Handle: ACPI object handle.
Index: Index of the data to retrieve from the object. In general, indexes read from left-to-right in the ACPI encoding, with index 0 always being the ACPI opcode.
Data: Points to the data.
DataSize: The size of the Data .

Description

Changes fields within the ACPI object. If the new size will not fit in the space occupied by the previous option, then his function will return EFI_BAD_BUFFER_SIZE . The list of opcodes and their related options can be found in GetOption() .

Status Code Returns

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	Handle is NULL or does not refer to a valid ACPI object.
EFI_BAD_BUFFER_SIZE	Data cannot be accommodated in the space occupied by the option.

9.1.9. EFI_ACPI_SDT_PROTOCOL.FindPath()

Summary

Returns the handle of the ACPI object representing the specified ACPI path.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_ACPI_FIND_PATH) (
  IN EFI_ACPI_HANDLE         HandleIn,
  IN VOID                    *AcpiPath,
  OUT EFI_ACPI_HANDLE        *HandleOut
  );

Parameters

HandleIn: Points to the handle of the object representing the starting point for the path search.
AcpiPath: Points to the ACPI path, which conforms to the ACPI encoded path format.
HandleOut: On return, points to the ACPI object which represents AcpiPath , relative to HandleIn .

Description

Starting with the ACPI object represented by HandleIn , walk the specified ACPI path AcpiPath and return the handle of the ACPI object it refers to. This function supports absolute paths, relative paths and the special rules applied to single name segments.

Status Code Returns

EFI_SUCCESS	Success
EFI_INVALID_PARAMETER	HandleIn is NULL or does not refer to a valid ACPI object.