#include <AmlDefines.h>
#include <AmlInclude.h>
#include <IndustryStandard/AcpiAml.h>

Data Structures
struct	_AML_BYTE_ENCODING

Macros
#define	AML_OPCODE_DEF(str, OpCode) str, OpCode

#define	AML_HAS_PKG_LENGTH 0x00001U

#define	AML_IS_NAME_CHAR 0x00002U

#define	AML_HAS_CHILD_OBJ 0x00004U

#define	AML_HAS_BYTE_LIST 0x00008U

#define	AML_HAS_FIELD_LIST 0x00010U

#define	AML_IS_FIELD_ELEMENT 0x00020U

#define	AML_IN_NAMESPACE 0x10000U

#define	AML_IS_PSEUDO_OPCODE 0x20000U

Typedefs
typedef enum EAmlParseFormat	AML_PARSE_FORMAT

typedef UINT32	AML_OP_ATTRIBUTE

typedef struct _AML_BYTE_ENCODING	AML_BYTE_ENCODING

Enumerations
enum	EAmlParseFormat { EAmlNone = 0 , EAmlUInt8 , EAmlUInt16 , EAmlUInt32 , EAmlUInt64 , EAmlObject , EAmlName , EAmlString , EAmlFieldPkgLen , EAmlParseFormatMax }

Functions
CONST AML_BYTE_ENCODING *EFIAPI	AmlGetByteEncoding (IN CONST UINT8 *Buffer)

CONST AML_BYTE_ENCODING *EFIAPI	AmlGetByteEncodingByOpCode (IN UINT8 OpCode, IN UINT8 SubOpCode)

CONST AML_BYTE_ENCODING *EFIAPI	AmlGetFieldEncoding (IN CONST UINT8 *Buffer)

CONST AML_BYTE_ENCODING *EFIAPI	AmlGetFieldEncodingByOpCode (IN UINT8 OpCode, IN UINT8 SubOpCode)

CONST CHAR8 *	AmlGetOpCodeStr (IN UINT8 OpCode, IN UINT8 SubOpCode)

CONST CHAR8 *	AmlGetFieldOpCodeStr (IN UINT8 OpCode, IN UINT8 SubOpCode)

BOOLEAN EFIAPI	AmlIsOpCodeValid (IN UINT8 OpCode, IN UINT8 SubOpCode)

EAML_NODE_DATA_TYPE EFIAPI	AmlTypeToNodeDataType (IN AML_PARSE_FORMAT AmlType)

UINT32 EFIAPI	AmlGetPkgLength (IN CONST UINT8 Buffer, OUT UINT32 PkgLength)

UINT8 EFIAPI	AmlSetPkgLength (IN UINT32 Length, OUT UINT8 *Buffer)

UINT8 EFIAPI	AmlComputePkgLengthWidth (IN UINT32 Length)

EFI_STATUS EFIAPI	AmlComputePkgLength (IN UINT32 Length, OUT UINT32 *PkgLen)

Detailed Description

AML grammar definitions.

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

Definition in file Aml.h.

Macro Definition Documentation

◆ AML_HAS_BYTE_LIST

#define AML_HAS_BYTE_LIST 0x00008U

This is a sub-type of a variable list of arguments. It can only be found in buffer objects. A ByteList is either a list of bytes or a list of resource data elements. Resource data elements have specific opcodes.

Definition at line 82 of file Aml.h.

◆ AML_HAS_CHILD_OBJ

#define AML_HAS_CHILD_OBJ 0x00004U

A variable list of arguments is following the last fixed argument. Each argument is evaluated as an EAmlObject.

Definition at line 75 of file Aml.h.

◆ AML_HAS_FIELD_LIST

#define AML_HAS_FIELD_LIST 0x00010U

This is a sub-type of a variable list of arguments. It can only be found in Fields, IndexFields and BankFields. A FieldList is made of FieldElements. FieldElements have specific opcodes.

Definition at line 88 of file Aml.h.

◆ AML_HAS_PKG_LENGTH

#define AML_HAS_PKG_LENGTH 0x00001U

A PkgLength is expected between the OpCode/SubOpCode couple and the first fixed argument of the object.

Definition at line 64 of file Aml.h.

◆ AML_IN_NAMESPACE

#define AML_IN_NAMESPACE 0x10000U

The object has a name and which is part of the AML namespace. The name can be found in the fixed argument list at the NameIndex.

Definition at line 98 of file Aml.h.

◆ AML_IS_FIELD_ELEMENT

#define AML_IS_FIELD_ELEMENT 0x00020U

This object node is a field element. Its opcode is to be fetched from the field encoding table.

Definition at line 93 of file Aml.h.

◆ AML_IS_NAME_CHAR

#define AML_IS_NAME_CHAR 0x00002U

The object's OpCode is actually a character. Encodings with this attribute don't describe objects. The dual/multi name prefix have this attribute, indicating the start of a longer NameString.

Definition at line 70 of file Aml.h.

◆ AML_IS_PSEUDO_OPCODE

#define AML_IS_PSEUDO_OPCODE 0x20000U

Some OpCodes have been created in this library. They are called pseudo opcodes and must stay internal to this library.

Definition at line 103 of file Aml.h.

◆ AML_OPCODE_DEF

#define AML_OPCODE_DEF	(	str,
		OpCode
	)	str, OpCode

Definition at line 18 of file Aml.h.

Typedef Documentation

◆ AML_BYTE_ENCODING

typedef struct _AML_BYTE_ENCODING AML_BYTE_ENCODING

Encoding of an AML object.

Every AML object has a specific encoding. This encoding information is used to parse AML objects. A table of AML_BYTE_ENCODING entries allows to parse an AML bytestream. This structure is also used to describe field objects.

Cf. ACPI 6.3 specification, s20.2.

◆ AML_OP_ATTRIBUTE

typedef UINT32 AML_OP_ATTRIBUTE

AML attributes

To add some more information to the byte encoding, it is possible to add these attributes.

Definition at line 59 of file Aml.h.

◆ AML_PARSE_FORMAT

typedef enum EAmlParseFormat AML_PARSE_FORMAT

AML types.

In the AML bytestream, data is represented using one of the following types. These types are used in the parsing logic to know what kind of data is expected next in the bytestream. This allows to parse data according to the AML_PARSE_FORMAT type. E.g.: A string will not be parsed in the same way as a UINT8.

These are internal types.

Enumeration Type Documentation

◆ EAmlParseFormat

enum EAmlParseFormat

AML types.

In the AML bytestream, data is represented using one of the following types. These types are used in the parsing logic to know what kind of data is expected next in the bytestream. This allows to parse data according to the AML_PARSE_FORMAT type. E.g.: A string will not be parsed in the same way as a UINT8.

These are internal types.

Enumerator
EAmlNone	No data expected.
EAmlUInt8	One byte value evaluated as a UINT8.
EAmlUInt16	Two byte value evaluated as a UINT16.
EAmlUInt32	Four byte value evaluated as a UINT32.
EAmlUInt64	Eight byte value evaluated as a UINT64.
EAmlObject	AML object, starting with an OpCode/SubOpCode couple, potentially followed by package length. EAmlName is a subtype of an EAmlObject. Indeed, an EAmlName can also be evaluated as an EAmlObject in the parsing.
EAmlName	Name corresponding to the NameString keyword in the ACPI specification. E.g.: "\_SB_.DEV0"
EAmlString	NULL terminated string.
EAmlFieldPkgLen	A field package length (PkgLen). A data node of this type can only be found in a field list, in a NamedField statement. The PkgLen is otherwise part of the object node structure.
EAmlParseFormatMax	Max enum.

Definition at line 33 of file Aml.h.

Function Documentation

◆ AmlComputePkgLength()

EFI_STATUS EFIAPI AmlComputePkgLength	(	IN UINT32	Length,
		OUT UINT32 *	PkgLen
	)

Given a length, compute the value of a PkgLen.

In AML, some object have a PkgLen, telling the size of the AML object. It can be encoded in 1 to 4 bytes. The bytes used to encode the PkgLen is itself counted in the PkgLen value. This means that if an AML object sees its size increment/decrement, the number of bytes used to encode the PkgLen value can itself increment/decrement.

For instance, the AML encoding of a DeviceOp is: DefDevice := DeviceOp PkgLength NameString TermList If:

sizeof (NameString) = 4 (the name is "DEV0" for instance);
sizeof (TermList) = (2^6-6) then the PkgLen is encoded on 1 byte. Indeed, its value is: sizeof (PkgLen) + sizeof (NameString) + sizeof (TermList) = sizeof (PkgLen) + 4 + (2^6-6) So: PkgLen = sizeof (PkgLen) + (2^6-2)

The input arguments Length and PkgLen represent, for the DefDevice: DefDevice := DeviceOp PkgLength NameString TermList |---—Length--—| |-----—*PgkLength------—|

Parameters

[in]	Length	The length to encode as a PkgLen. Length cannot exceed 2^28 - 4 (4 bytes for the PkgLen encoding). The size of the PkgLen encoding bytes should not be counted in this length value.
[out]	PkgLen	If success, contains the value of the PkgLen, ready to encode in the PkgLen format. This value takes into account the size of PkgLen encoding.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 862 of file Aml.c.

◆ AmlComputePkgLengthWidth()

UINT8 EFIAPI AmlComputePkgLengthWidth ( IN UINT32 Length )

Compute the number of bytes required to write a package length.

Parameters

[in] Length The length to convert in the AML package length encoding style. Length cannot exceed 2^28.

Returns: The number of bytes required to write the Length.

Definition at line 799 of file Aml.c.

◆ AmlGetByteEncoding()

CONST AML_BYTE_ENCODING *EFIAPI AmlGetByteEncoding ( IN CONST UINT8 * Buffer )

Get the AML_BYTE_ENCODING entry in the AML encoding table.

Note: For Pseudo OpCodes this function returns NULL.

Parameters

[in] Buffer Pointer to an OpCode/SubOpCode couple. If *Buffer = 0x5b (extended OpCode), Buffer must be at least two bytes long.

Returns: The corresponding AML_BYTE_ENCODING entry. NULL if not found.

Definition at line 290 of file Aml.c.

◆ AmlGetByteEncodingByOpCode()

CONST AML_BYTE_ENCODING *EFIAPI AmlGetByteEncodingByOpCode	(	IN UINT8	OpCode,
		IN UINT8	SubOpCode
	)

Get the AML_BYTE_ENCODING entry in the AML encoding table by providing an OpCode/SubOpCode couple.

Parameters

[in]	OpCode	OpCode.
[in]	SubOpCode	SubOpCode.

Returns: The corresponding AML_BYTE_ENCODING entry. NULL if not found.

Definition at line 347 of file Aml.c.

◆ AmlGetFieldEncoding()

CONST AML_BYTE_ENCODING *EFIAPI AmlGetFieldEncoding ( IN CONST UINT8 * Buffer )

Get the AML_BYTE_ENCODING entry in the field encoding table.

Note: For Pseudo OpCodes this function returns NULL.

Parameters

[in] Buffer Pointer to a field OpCode. No SubOpCode is expected.

Returns: The corresponding AML_BYTE_ENCODING entry in the field encoding table. NULL if not found.

Definition at line 383 of file Aml.c.

◆ AmlGetFieldEncodingByOpCode()

CONST AML_BYTE_ENCODING *EFIAPI AmlGetFieldEncodingByOpCode	(	IN UINT8	OpCode,
		IN UINT8	SubOpCode
	)

Get the AML_BYTE_ENCODING entry in the field encoding table by providing an OpCode/SubOpCode couple.

Parameters

[in]	OpCode	OpCode.
[in]	SubOpCode	SubOpCode.

Returns: The corresponding AML_BYTE_ENCODING entry in the field encoding table. NULL if not found.

Definition at line 434 of file Aml.c.

◆ AmlGetFieldOpCodeStr()

CONST CHAR8 * AmlGetFieldOpCodeStr	(	IN UINT8	OpCode,
		IN UINT8	SubOpCode
	)

Look for an OpCode/SubOpCode couple in the AML field element grammar, and return a corresponding string.

Parameters

[in]	OpCode	The OpCode.
[in]	SubOpCode	The SubOpCode. Must be zero.

Returns: A string describing the OpCode/SubOpCode couple. NULL if not found.

Definition at line 504 of file Aml.c.

◆ AmlGetOpCodeStr()

CONST CHAR8 * AmlGetOpCodeStr	(	IN UINT8	OpCode,
		IN UINT8	SubOpCode
	)

Look for an OpCode/SubOpCode couple in the AML grammar, and return a corresponding string.

Parameters

[in]	OpCode	The OpCode.
[in]	SubOpCode	The SubOpCode.

Returns: A string describing the OpCode/SubOpCode couple. NULL if not found.

Definition at line 470 of file Aml.c.

◆ AmlGetPkgLength()

UINT32 EFIAPI AmlGetPkgLength	(	IN CONST UINT8 *	Buffer,
		OUT UINT32 *	PkgLength
	)

Get the package length from the buffer.

Parameters

[in]	Buffer	AML buffer.
[out]	PkgLength	The interpreted PkgLen value. Length cannot exceed 2^28.

Returns: The number of bytes to represent the package length. 0 if an issue occurred.

Definition at line 621 of file Aml.c.

◆ AmlIsOpCodeValid()

BOOLEAN EFIAPI AmlIsOpCodeValid	(	IN UINT8	OpCode,
		IN UINT8	SubOpCode
	)

Check whether the OpCode/SubOpcode couple is a valid entry in the AML grammar encoding table.

Parameters

[in]	OpCode	OpCode to check.
[in]	SubOpCode	SubOpCode to check.

Return values

TRUE	The OpCode/SubOpCode couple is valid.
FALSE	Otherwise.

Definition at line 543 of file Aml.c.

◆ AmlSetPkgLength()

UINT8 EFIAPI AmlSetPkgLength	(	IN UINT32	Length,
		OUT UINT8 *	Buffer
	)

Convert the Length to the AML PkgLen encoding, then and write it in the Buffer.

Parameters

[in]	Length	Length to convert. Length cannot exceed 2^28.
[out]	Buffer	Write the result in this Buffer.

Returns: The number of bytes used to write the Length.

Definition at line 724 of file Aml.c.

◆ AmlTypeToNodeDataType()

EAML_NODE_DATA_TYPE EFIAPI AmlTypeToNodeDataType ( IN AML_PARSE_FORMAT AmlType )

Convert an AML_PARSE_FORMAT to its corresponding EAML_NODE_DATA_TYPE.

Parameters

[in] AmlType Input AML Type.

Returns: The corresponding EAML_NODE_DATA_TYPE. EAmlNodeDataTypeNone if not found.

Definition at line 596 of file Aml.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AML_HAS_BYTE_LIST

◆ AML_HAS_CHILD_OBJ

◆ AML_HAS_FIELD_LIST

◆ AML_HAS_PKG_LENGTH

◆ AML_IN_NAMESPACE

◆ AML_IS_FIELD_ELEMENT

◆ AML_IS_NAME_CHAR

◆ AML_IS_PSEUDO_OPCODE

◆ AML_OPCODE_DEF

Typedef Documentation

◆ AML_BYTE_ENCODING

◆ AML_OP_ATTRIBUTE

◆ AML_PARSE_FORMAT

Enumeration Type Documentation

◆ EAmlParseFormat

Function Documentation

◆ AmlComputePkgLength()

◆ AmlComputePkgLengthWidth()

◆ AmlGetByteEncoding()

◆ AmlGetByteEncodingByOpCode()

◆ AmlGetFieldEncoding()

◆ AmlGetFieldEncodingByOpCode()

◆ AmlGetFieldOpCodeStr()

◆ AmlGetOpCodeStr()

◆ AmlGetPkgLength()

◆ AmlIsOpCodeValid()

◆ AmlSetPkgLength()

◆ AmlTypeToNodeDataType()