AmlLib.h File Reference

Typedefs
typedef void *	AML_NODE_HANDLE
typedef void *	AML_ROOT_NODE_HANDLE
typedef void *	AML_OBJECT_NODE_HANDLE
typedef void *	AML_DATA_NODE_HANDLE

Functions
EFI_STATUS EFIAPI	AmlParseDefinitionBlock (IN CONST EFI_ACPI_DESCRIPTION_HEADER *DefinitionBlock, OUT AML_ROOT_NODE_HANDLE *RootPtr)
EFI_STATUS EFIAPI	AmlSerializeDefinitionBlock (IN AML_ROOT_NODE_HANDLE RootNode, OUT EFI_ACPI_DESCRIPTION_HEADER **Table)
EFI_STATUS EFIAPI	AmlCloneTree (IN AML_NODE_HANDLE Node, OUT AML_NODE_HANDLE *ClonedNode)
EFI_STATUS EFIAPI	AmlDeleteTree (IN AML_NODE_HANDLE Node)
EFI_STATUS EFIAPI	AmlDetachNode (IN AML_NODE_HANDLE Node)
EFI_STATUS EFIAPI	AmlFindNode (IN AML_NODE_HANDLE ReferenceNode, IN CHAR8 *AslPath, OUT AML_NODE_HANDLE *OutNode)
EFI_STATUS EFIAPI	AmlDeviceOpUpdateName (IN AML_OBJECT_NODE_HANDLE DeviceOpNode, IN CHAR8 *NewNameString)
EFI_STATUS EFIAPI	AmlNameOpUpdateInteger (IN AML_OBJECT_NODE_HANDLE NameOpNode, IN UINT64 NewInt)
EFI_STATUS EFIAPI	AmlNameOpUpdateString (IN AML_OBJECT_NODE_HANDLE NameOpNode, IN CONST CHAR8 *NewName)
EFI_STATUS EFIAPI	AmlNameOpGetFirstRdNode (IN AML_OBJECT_NODE_HANDLE NameOpNode, OUT AML_DATA_NODE_HANDLE *OutRdNode)
EFI_STATUS EFIAPI	AmlNameOpGetNextRdNode (IN AML_DATA_NODE_HANDLE CurrRdNode, OUT AML_DATA_NODE_HANDLE *OutRdNode)
EFI_STATUS EFIAPI	AmlUpdateRdInterrupt (IN AML_DATA_NODE_HANDLE InterruptRdNode, IN UINT32 Irq)
EFI_STATUS EFIAPI	AmlUpdateRdQWord (IN AML_DATA_NODE_HANDLE QWordRdNode, IN UINT64 BaseAddress, IN UINT64 BaseAddressLength)
EFI_STATUS EFIAPI	AmlCodeGenRdInterrupt (IN BOOLEAN ResourceConsumer, IN BOOLEAN EdgeTriggered, IN BOOLEAN ActiveLow, IN BOOLEAN Shared, IN UINT32 *IrqList, IN UINT8 IrqCount, IN AML_OBJECT_NODE_HANDLE NameOpNode, OUT AML_DATA_NODE_HANDLE *NewRdNode)
EFI_STATUS EFIAPI	AmlCodeGenDefinitionBlock (IN CONST CHAR8 *TableSignature, IN CONST CHAR8 *OemId, IN CONST CHAR8 *OemTableId, IN UINT32 OemRevision, OUT AML_ROOT_NODE_HANDLE *NewRootNode)
EFI_STATUS EFIAPI	AmlCodeGenNameString (IN CONST CHAR8 *NameString, IN CHAR8 *String, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewObjectNode)
EFI_STATUS EFIAPI	AmlCodeGenNameInteger (IN CONST CHAR8 *NameString, IN UINT64 Integer, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewObjectNode)
EFI_STATUS EFIAPI	AmlCodeGenDevice (IN CONST CHAR8 *NameString, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewObjectNode)
EFI_STATUS EFIAPI	AmlCodeGenScope (IN CONST CHAR8 *NameString, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewObjectNode)
EFI_STATUS EFIAPI	AmlCodeGenMethodRetNameString (IN CONST CHAR8 *MethodNameString, IN CONST CHAR8 *ReturnedNameString, IN UINT8 NumArgs, IN BOOLEAN IsSerialized, IN UINT8 SyncLevel, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewObjectNode)
EFI_STATUS EFIAPI	AmlCreateLpiNode (IN CONST CHAR8 *LpiNameString, IN UINT16 Revision, IN UINT64 LevelId, IN AML_NODE_HANDLE ParentNode, OUT AML_OBJECT_NODE_HANDLE *NewLpiNode)
EFI_STATUS EFIAPI	AmlAddLpiState (IN UINT32 MinResidency, IN UINT32 WorstCaseWakeLatency, IN UINT32 Flags, IN UINT32 ArchFlags, IN UINT32 ResCntFreq, IN UINT32 EnableParentState, IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *GenericRegisterDescriptor, IN UINT64 Integer, IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *ResidencyCounterRegister, IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *UsageCounterRegister, IN CHAR8 *StateName, IN AML_OBJECT_NODE_HANDLE LpiNode)
EFI_STATUS EFIAPI	AmlNameOpCrsGetFirstRdNode (IN AML_OBJECT_NODE_HANDLE NameOpCrsNode, OUT AML_DATA_NODE_HANDLE *OutRdNode)
EFI_STATUS EFIAPI	AmlNameOpCrsGetNextRdNode (IN AML_DATA_NODE_HANDLE CurrRdNode, OUT AML_DATA_NODE_HANDLE *OutRdNode)
EFI_STATUS EFIAPI	AmlCodeGenCrsAddRdInterrupt (IN AML_OBJECT_NODE_HANDLE NameOpCrsNode, IN BOOLEAN ResourceConsumer, IN BOOLEAN EdgeTriggered, IN BOOLEAN ActiveLow, IN BOOLEAN Shared, IN UINT32 *IrqList, IN UINT8 IrqCount)

Detailed Description

AML Lib.

Copyright (c) 2019 - 2021, Arm Limited. All rights reserved.

SPDX-License-Identifier: BSD-2-Clause-Patent

Typedef Documentation

typedef void* AML_DATA_NODE_HANDLE

Data Node handle.

typedef void* AML_NODE_HANDLE

Node handle.

typedef void* AML_OBJECT_NODE_HANDLE

Object Node handle.

typedef void* AML_ROOT_NODE_HANDLE

Root Node handle.

Function Documentation

EFI_STATUS EFIAPI AmlAddLpiState	(	IN UINT32	MinResidency,
		IN UINT32	WorstCaseWakeLatency,
		IN UINT32	Flags,
		IN UINT32	ArchFlags,
		IN UINT32	ResCntFreq,
		IN UINT32	EnableParentState,
		IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *	GenericRegisterDescriptor,
		IN UINT64	Integer,
		IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *	ResidencyCounterRegister,
		IN EFI_ACPI_6_3_GENERIC_ADDRESS_STRUCTURE *	UsageCounterRegister,
		IN CHAR8 *	StateName,
		IN AML_OBJECT_NODE_HANDLE	LpiNode
	)

Add an _LPI state to a LPI node created using AmlCreateLpiNode ().

AmlAddLpiState () increments the Count of LPI states in the LPI node by one, and adds the following package: Package() { MinResidency, WorstCaseWakeLatency, Flags, ArchFlags, ResCntFreq, EnableParentState, (GenericRegisterDescriptor != NULL) ? // Entry method. If a ResourceTemplate(GenericRegisterDescriptor) : // Register is given, Integer, // use it. Use the Integer otherwise. ResourceTemplate() { // NULL Residency Counter Register (SystemMemory, 0, 0, 0, 0) }, ResourceTemplate() { // NULL Usage Counter Register (SystemMemory, 0, 0, 0, 0) }, "" // NULL State Name },

Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".

Parameters

[in]	MinResidency	Minimum Residency.
[in]	WorstCaseWakeLatency	Worst case wake-up latency.
[in]	Flags	Flags.
[in]	ArchFlags	Architectural flags.
[in]	ResCntFreq	Residency Counter Frequency.
[in]	EnableParentState	Enabled Parent State.
[in]	GenericRegisterDescriptor	Entry Method. If not NULL, use this Register to describe the entry method address.
[in]	Integer	Entry Method. If GenericRegisterDescriptor is NULL, take this value.
[in]	ResidencyCounterRegister	If not NULL, use it to populate the residency counter register.
[in]	UsageCounterRegister	If not NULL, use it to populate the usage counter register.
[in]	StateName	If not NULL, use it to populate the state name.
[in]	LpiNode	Lpi node created with the function AmlCreateLpiNode to which the new LPI state is appended.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenCrsAddRdInterrupt	(	IN AML_OBJECT_NODE_HANDLE	NameOpCrsNode,
		IN BOOLEAN	ResourceConsumer,
		IN BOOLEAN	EdgeTriggered,
		IN BOOLEAN	ActiveLow,
		IN BOOLEAN	Shared,
		IN UINT32 *	IrqList,
		IN UINT8	IrqCount
	)

DEPRECATED API

Add an Interrupt Resource Data node.

This function creates a Resource Data element corresponding to the "Interrupt ()" ASL function, stores it in an AML Data Node.

It then adds it after the input CurrRdNode in the list of resource data element.

The Resource Data effectively created is an Extended Interrupt Resource Data. See ACPI 6.3 specification, s6.4.3.6 "Extended Interrupt Descriptor" for more information about Extended Interrupt Resource Data.

The Extended Interrupt contains one single interrupt.

This function allocates memory to create a data node. It is the caller's responsibility to either:

• attach this node to an AML tree;
• delete this node.

Note: The _CRS node must be defined using the ASL Name () function. e.g. Name (_CRS, ResourceTemplate () { ... }

Parameters

[in]	NameOpCrsNode	NameOp object node defining a "_CRS" object. Must have an OpCode=AML_NAME_OP, SubOpCode=0. NameOp object nodes are defined in ASL using the "Name ()" function.
[in]	ResourceConsumer	The device consumes the specified interrupt or produces it for use by a child device.
[in]	EdgeTriggered	The interrupt is edge triggered or level triggered.
[in]	ActiveLow	The interrupt is active-high or active-low.
[in]	Shared	The interrupt can be shared with other devices or not (Exclusive).
[in]	IrqList	Interrupt list. Must be non-NULL.
[in]	IrqCount	Interrupt count. Must be non-zero.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Could not allocate memory.

EFI_STATUS EFIAPI AmlCodeGenDefinitionBlock	(	IN CONST CHAR8 *	TableSignature,
		IN CONST CHAR8 *	OemId,
		IN CONST CHAR8 *	OemTableId,
		IN UINT32	OemRevision,
		OUT AML_ROOT_NODE_HANDLE *	NewRootNode
	)

AML code generation for DefinitionBlock.

Create a Root Node handle. It is the caller's responsibility to free the allocated memory with the AmlDeleteTree function.

AmlCodeGenDefinitionBlock (TableSignature, OemId, TableID, OEMRevision) is equivalent to the following ASL code: DefinitionBlock (AMLFileName, TableSignature, ComplianceRevision, OemId, TableID, OEMRevision) {} with the ComplianceRevision set to 2 and the AMLFileName is ignored.

Parameters

[in]	TableSignature	4-character ACPI signature. Must be 'DSDT' or 'SSDT'.
[in]	OemId	6-character string OEM identifier.
[in]	OemTableId	8-character string OEM table identifier.
[in]	OemRevision	OEM revision number.
[out]	DefinitionBlockTerm	The ASL Term handle representing a Definition Block.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenDevice	(	IN CONST CHAR8 *	NameString,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewObjectNode
	)

AML code generation for a Device object node.

AmlCodeGenDevice ("COM0", ParentNode, NewObjectNode) is equivalent of the following ASL code: Device(COM0) {}

Parameters

[in]	NameString	The new Device's name. Must be a NULL-terminated ASL NameString e.g.: "DEV0", "DV15.DEV0", etc. The input string is copied.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewObjectNode	If success, contains the created node.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenMethodRetNameString	(	IN CONST CHAR8 *	MethodNameString,
		IN CONST CHAR8 *	ReturnedNameString,
		IN UINT8	NumArgs,
		IN BOOLEAN	IsSerialized,
		IN UINT8	SyncLevel,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewObjectNode
	)

AML code generation for a method returning a NameString.

AmlCodeGenMethodRetNameString ( "MET0", "_CRS", 1, TRUE, 3, ParentNode, NewObjectNode ); is equivalent of the following ASL code: Method(MET0, 1, Serialized, 3) { Return (_CRS) }

The ASL parameters "ReturnType" and "ParameterTypes" are not asked in this function. They are optional parameters in ASL.

Parameters

[in]	MethodNameString	The new Method's name. Must be a NULL-terminated ASL NameString e.g.: "MET0", "_SB.MET0", etc. The input string is copied.
[in]	ReturnedNameString	The name of the object returned by the method. Optional parameter, can be: NULL (ignored). A NULL-terminated ASL NameString. e.g.: "MET0", "_SB.MET0", etc. The input string is copied.
[in]	NumArgs	Number of arguments. Must be 0 <= NumArgs <= 6.
[in]	IsSerialized	TRUE is equivalent to Serialized. FALSE is equivalent to NotSerialized. Default is NotSerialized in ASL spec.
[in]	SyncLevel	Synchronization level for the method. Must be 0 <= SyncLevel <= 15. Default is 0 in ASL.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewObjectNode	If success, contains the created node.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenNameInteger	(	IN CONST CHAR8 *	NameString,
		IN UINT64	Integer,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewObjectNode
	)

AML code generation for a Name object node, containing an Integer.

AmlCodeGenNameInteger ("_UID", 1, ParentNode, NewObjectNode) is equivalent of the following ASL code: Name(_UID, One)

Parameters

[in]	NameString	The new variable name. Must be a NULL-terminated ASL NameString e.g.: "DEV0", "DV15.DEV0", etc. The input string is copied.
[in]	Integer	Integer to associate to the NameString.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewObjectNode	If success, contains the created node.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenNameString	(	IN CONST CHAR8 *	NameString,
		IN CHAR8 *	String,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewObjectNode
	)

AML code generation for a Name object node, containing a String.

AmlCodeGenNameString ("_HID", "HID0000", ParentNode, NewObjectNode) is equivalent of the following ASL code: Name(_HID, "HID0000")

Parameters

[in]	NameString	The new variable name. Must be a NULL-terminated ASL NameString e.g.: "DEV0", "DV15.DEV0", etc. The input string is copied.
[in]	String	NULL terminated String to associate to the NameString.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewObjectNode	If success, contains the created node.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCodeGenRdInterrupt	(	IN BOOLEAN	ResourceConsumer,
		IN BOOLEAN	EdgeTriggered,
		IN BOOLEAN	ActiveLow,
		IN BOOLEAN	Shared,
		IN UINT32 *	IrqList,
		IN UINT8	IrqCount,
		IN AML_OBJECT_NODE_HANDLE	NameOpNode,
		OUT AML_DATA_NODE_HANDLE *	NewRdNode
	)

Code generation for the "Interrupt ()" ASL function.

The Resource Data effectively created is an Extended Interrupt Resource Data. Cf ACPI 6.4:

• s6.4.3.6 "Extended Interrupt Descriptor"
• s19.6.64 "Interrupt (Interrupt Resource Descriptor Macro)"

The created resource data node can be:

• appended to the list of resource data elements of the NameOpNode. In such case NameOpNode must be defined by a the "Name ()" ASL statement and initially contain a "ResourceTemplate ()".
• returned through the NewRdNode parameter.

Parameters

[in]	ResourceConsumer	The device consumes the specified interrupt or produces it for use by a child device.
[in]	EdgeTriggered	The interrupt is edge triggered or level triggered.
[in]	ActiveLow	The interrupt is active-high or active-low.
[in]	Shared	The interrupt can be shared with other devices or not (Exclusive).
[in]	IrqList	Interrupt list. Must be non-NULL.
[in]	IrqCount	Interrupt count. Must be non-zero.
[in]	NameOpNode	NameOp object node defining a named object. If provided, append the new resource data node to the list of resource data elements of this node.
[out]	NewRdNode	If provided and success, contain the created node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Could not allocate memory.

EFI_STATUS EFIAPI AmlCodeGenScope	(	IN CONST CHAR8 *	NameString,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewObjectNode
	)

AML code generation for a Scope object node.

AmlCodeGenScope ("_SB", ParentNode, NewObjectNode) is equivalent of the following ASL code: Scope(_SB) {}

Parameters

[in]	NameString	The new Scope's name. Must be a NULL-terminated ASL NameString e.g.: "DEV0", "DV15.DEV0", etc. The input string is copied.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewObjectNode	If success, contains the created node.

Return values

EFI_SUCCESS	Success.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlCreateLpiNode	(	IN CONST CHAR8 *	LpiNameString,
		IN UINT16	Revision,
		IN UINT64	LevelId,
		IN AML_NODE_HANDLE	ParentNode,
		OUT AML_OBJECT_NODE_HANDLE *	NewLpiNode
	)

Create a _LPI name.

AmlCreateLpiNode ("_LPI", 0, 1, ParentNode, &LpiNode) is equivalent of the following ASL code: Name (_LPI, Package ( 0, // Revision 1, // LevelId 0 // Count ))

This function doesn't define any LPI state. As shown above, the count of _LPI state is set to 0. The AmlAddLpiState () function must be used to add LPI states.

Cf ACPI 6.3 specification, s8.4.4 "Lower Power Idle States".

Parameters

[in]	LpiNameString	The new LPI 's object name. Must be a NULL-terminated ASL NameString e.g.: "_LPI", "DEV0.PLPI", etc. The input string is copied.
[in]	Revision	Revision number of the _LPI states.
[in]	LevelId	A platform defined number that identifies the level of hierarchy of the processor node to which the LPI states apply.
[in]	ParentNode	If provided, set ParentNode as the parent of the node created.
[out]	NewLpiNode	If success, contains the created node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Failed to allocate memory.

EFI_STATUS EFIAPI AmlFindNode	(	IN AML_NODE_HANDLE	ReferenceNode,
		IN CHAR8 *	AslPath,
		OUT AML_NODE_HANDLE *	OutNode
	)

Find a node in the AML namespace, given an ASL path and a reference Node.

• The AslPath can be an absolute path, or a relative path from the reference Node;
• Node must be a root node or a namespace node;
• A root node is expected to be at the top of the tree.

E.g.: For the following AML namespace, with the ReferenceNode being the node with the name "AAAA":

• the node with the name "BBBB" can be found by looking for the ASL path "BBBB";
• the root node can be found by looking for the ASL relative path "^", or the absolute path "\\".

AML namespace: \ -AAAA <- ReferenceNode -BBBB

Parameters

[in]	ReferenceNode	Reference node. If a relative path is given, the search is done from this node. If an absolute path is given, the search is done from the root node. Must be a root node or an object node which is part of the namespace.
[in]	AslPath	ASL path to the searched node in the namespace. An ASL path name is NULL terminated. Can be a relative or absolute path. E.g.: "\\_SB.CLU0.CPU0" or "^CPU0"
[out]	OutNode	Pointer to the found node. Contains NULL if not found.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_BUFFER_TOO_SMALL	No space left in the buffer.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Out of memory.