diff options
Diffstat (limited to 'DynamicTablesPkg/Library/Common/AmlLib/AmlEncoding/Aml.h')
| -rw-r--r-- | DynamicTablesPkg/Library/Common/AmlLib/AmlEncoding/Aml.h | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/DynamicTablesPkg/Library/Common/AmlLib/AmlEncoding/Aml.h b/DynamicTablesPkg/Library/Common/AmlLib/AmlEncoding/Aml.h new file mode 100644 index 0000000000..ba12286213 --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/AmlEncoding/Aml.h @@ -0,0 +1,330 @@ +/** @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_
+
|