mirror of https://github.com/acidanthera/audk.git
331 lines
9.7 KiB
C
331 lines
9.7 KiB
C
/** @file
|
|
AML grammar definitions.
|
|
|
|
Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved. <BR>
|
|
Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
**/
|
|
|
|
#ifndef AML_H_
|
|
#define AML_H_
|
|
|
|
#include <AmlDefines.h>
|
|
#include <AmlInclude.h>
|
|
#include <IndustryStandard/AcpiAml.h>
|
|
|
|
#if !defined (MDEPKG_NDEBUG)
|
|
#define AML_DEBUG_STR(str) str,
|
|
#else
|
|
#define AML_DEBUG_STR(x)
|
|
#endif // MDEPKG_NDEBUG
|
|
|
|
/** 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.
|
|
*/
|
|
typedef enum EAmlParseFormat {
|
|
EAmlNone = 0, ///< 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.
|
|
} AML_PARSE_FORMAT;
|
|
|
|
/** AML attributes
|
|
|
|
To add some more information to the byte encoding, it is possible to add
|
|
these attributes.
|
|
*/
|
|
typedef UINT32 AML_OP_ATTRIBUTE;
|
|
|
|
/** A PkgLength is expected between the OpCode/SubOpCode couple and the first
|
|
fixed argument of the object.
|
|
*/
|
|
#define AML_HAS_PKG_LENGTH 0x00001U
|
|
|
|
/** 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.
|
|
*/
|
|
#define AML_IS_NAME_CHAR 0x00002U
|
|
|
|
/** A variable list of arguments is following the last fixed argument. Each
|
|
argument is evaluated as an EAmlObject.
|
|
*/
|
|
#define AML_HAS_CHILD_OBJ 0x00004U
|
|
|
|
/** 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.
|
|
*/
|
|
#define AML_HAS_BYTE_LIST 0x00008U
|
|
|
|
/** 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.
|
|
*/
|
|
#define AML_HAS_FIELD_LIST 0x00010U
|
|
|
|
/** This object node is a field element. Its opcode is to be fetched from
|
|
the field encoding table.
|
|
*/
|
|
#define AML_IS_FIELD_ELEMENT 0x00020U
|
|
|
|
/** 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.
|
|
*/
|
|
#define AML_IN_NAMESPACE 0x10000U
|
|
|
|
/** Some OpCodes have been created in this library. They are called
|
|
pseudo opcodes and must stay internal to this library.
|
|
*/
|
|
#define AML_IS_PSEUDO_OPCODE 0x20000U
|
|
|
|
/** 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.
|
|
*/
|
|
typedef struct _AML_BYTE_ENCODING {
|
|
// Enable this field for debug.
|
|
#if !defined (MDEPKG_NDEBUG)
|
|
/// String field allowing to print the AML object.
|
|
CONST CHAR8 * Str;
|
|
#endif // MDEPKG_NDEBUG
|
|
|
|
/// OpCode of the AML object.
|
|
UINT8 OpCode;
|
|
|
|
/// SubOpCode of the AML object.
|
|
/// The SubOpcode field has a valid value when the OpCode is 0x5B,
|
|
/// otherwise this field must be zero.
|
|
/// For field objects, the SubOpCode is not used.
|
|
UINT8 SubOpCode;
|
|
|
|
/// Number of fixed arguments for the AML statement represented
|
|
/// by the OpCode & SubOpcode.
|
|
/// Maximum is 6 for AML objects.
|
|
/// Maximum is 3 for field objects.
|
|
EAML_PARSE_INDEX MaxIndex;
|
|
|
|
/// If the encoding has the AML_IN_NAMESPACE attribute (cf Attribute
|
|
/// field below), indicate where to find the name in the fixed list
|
|
/// of arguments.
|
|
EAML_PARSE_INDEX NameIndex;
|
|
|
|
/// Type of each fixed argument.
|
|
AML_PARSE_FORMAT Format[EAmlParseIndexMax];
|
|
|
|
/// Additional information on the AML object.
|
|
AML_OP_ATTRIBUTE Attribute;
|
|
} AML_BYTE_ENCODING;
|
|
|
|
/** Get the AML_BYTE_ENCODING entry in the AML encoding table.
|
|
|
|
Note: For Pseudo OpCodes this function returns NULL.
|
|
|
|
@param [in] Buffer Pointer to an OpCode/SubOpCode couple.
|
|
If *Buffer = 0x5b (extended OpCode),
|
|
Buffer must be at least two bytes long.
|
|
|
|
@return The corresponding AML_BYTE_ENCODING entry.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
AML_BYTE_ENCODING *
|
|
EFIAPI
|
|
AmlGetByteEncoding (
|
|
IN CONST UINT8 * Buffer
|
|
);
|
|
|
|
/** Get the AML_BYTE_ENCODING entry in the AML encoding table
|
|
by providing an OpCode/SubOpCode couple.
|
|
|
|
@param [in] OpCode OpCode.
|
|
@param [in] SubOpCode SubOpCode.
|
|
|
|
@return The corresponding AML_BYTE_ENCODING entry.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
AML_BYTE_ENCODING *
|
|
EFIAPI
|
|
AmlGetByteEncodingByOpCode (
|
|
IN UINT8 OpCode,
|
|
IN UINT8 SubOpCode
|
|
);
|
|
|
|
/** Get the AML_BYTE_ENCODING entry in the field encoding table.
|
|
|
|
Note: For Pseudo OpCodes this function returns NULL.
|
|
|
|
@param [in] Buffer Pointer to a field OpCode.
|
|
No SubOpCode is expected.
|
|
|
|
@return The corresponding AML_BYTE_ENCODING entry
|
|
in the field encoding table.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
AML_BYTE_ENCODING *
|
|
EFIAPI
|
|
AmlGetFieldEncoding (
|
|
IN CONST UINT8 * Buffer
|
|
);
|
|
|
|
/** Get the AML_BYTE_ENCODING entry in the field encoding table
|
|
by providing an OpCode/SubOpCode couple.
|
|
|
|
@param [in] OpCode OpCode.
|
|
@param [in] SubOpCode SubOpCode.
|
|
|
|
@return The corresponding AML_BYTE_ENCODING entry
|
|
in the field encoding table.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
AML_BYTE_ENCODING *
|
|
EFIAPI
|
|
AmlGetFieldEncodingByOpCode (
|
|
IN UINT8 OpCode,
|
|
IN UINT8 SubOpCode
|
|
);
|
|
|
|
// Enable this function for debug.
|
|
#if !defined (MDEPKG_NDEBUG)
|
|
/** Look for an OpCode/SubOpCode couple in the AML grammar,
|
|
and return a corresponding string.
|
|
|
|
@param [in] OpCode The OpCode.
|
|
@param [in] SubOpCode The SubOpCode.
|
|
|
|
@return A string describing the OpCode/SubOpCode couple.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
CHAR8 *
|
|
AmlGetOpCodeStr (
|
|
IN UINT8 OpCode,
|
|
IN UINT8 SubOpCode
|
|
);
|
|
|
|
/** Look for an OpCode/SubOpCode couple in the AML field element grammar,
|
|
and return a corresponding string.
|
|
|
|
@param [in] OpCode The OpCode.
|
|
@param [in] SubOpCode The SubOpCode. Must be zero.
|
|
|
|
@return A string describing the OpCode/SubOpCode couple.
|
|
NULL if not found.
|
|
**/
|
|
CONST
|
|
CHAR8 *
|
|
AmlGetFieldOpCodeStr (
|
|
IN UINT8 OpCode,
|
|
IN UINT8 SubOpCode
|
|
);
|
|
#endif // MDEPKG_NDEBUG
|
|
|
|
/** Check whether the OpCode/SubOpcode couple is a valid entry
|
|
in the AML grammar encoding table.
|
|
|
|
@param [in] OpCode OpCode to check.
|
|
@param [in] SubOpCode SubOpCode to check.
|
|
|
|
@retval TRUE The OpCode/SubOpCode couple is valid.
|
|
@retval FALSE Otherwise.
|
|
**/
|
|
BOOLEAN
|
|
EFIAPI
|
|
AmlIsOpCodeValid (
|
|
IN UINT8 OpCode,
|
|
IN UINT8 SubOpCode
|
|
);
|
|
|
|
/** Convert an AML_PARSE_FORMAT to its corresponding EAML_NODE_DATA_TYPE.
|
|
|
|
@param [in] AmlType Input AML Type.
|
|
|
|
@return The corresponding EAML_NODE_DATA_TYPE.
|
|
EAmlNodeDataTypeNone if not found.
|
|
**/
|
|
EAML_NODE_DATA_TYPE
|
|
EFIAPI
|
|
AmlTypeToNodeDataType (
|
|
IN AML_PARSE_FORMAT AmlType
|
|
);
|
|
|
|
/** Get the package length from the buffer.
|
|
|
|
@param [in] Buffer AML buffer.
|
|
@param [out] PkgLength The interpreted PkgLen value.
|
|
Length cannot exceed 2^28.
|
|
|
|
@return The number of bytes to represent the package length.
|
|
0 if an issue occurred.
|
|
**/
|
|
UINT32
|
|
EFIAPI
|
|
AmlGetPkgLength (
|
|
IN CONST UINT8 * Buffer,
|
|
OUT UINT32 * PkgLength
|
|
);
|
|
|
|
/** Convert the Length to the AML PkgLen encoding,
|
|
then and write it in the Buffer.
|
|
|
|
@param [in] Length Length to convert.
|
|
Length cannot exceed 2^28.
|
|
@param [out] Buffer Write the result in this Buffer.
|
|
|
|
@return The number of bytes used to write the Length.
|
|
**/
|
|
UINT8
|
|
EFIAPI
|
|
AmlSetPkgLength (
|
|
IN UINT32 Length,
|
|
OUT UINT8 * Buffer
|
|
);
|
|
|
|
/** Compute the number of bytes required to write a package length.
|
|
|
|
@param [in] Length The length to convert in the AML package length
|
|
encoding style.
|
|
Length cannot exceed 2^28.
|
|
|
|
@return The number of bytes required to write the Length.
|
|
**/
|
|
UINT8
|
|
EFIAPI
|
|
AmlComputePkgLengthWidth (
|
|
IN UINT32 Length
|
|
);
|
|
|
|
#endif // AML_H_
|
|
|