[PATCH v1 02/30] DynamicTablesPkg: AmlLib definitions

["Sami Mujawar" <sami.mujawar@arm.com>]

From: Pierre Gondois <pierre.gondois@arm.com>

Dynamic AML is a solution to generate Definition Block tables
at runtime. Dynamic AML provides the following techniques for
generating AML tables.
  - AML Fixup
  - AML Codegen
  - AML Fixup + Codegen

AML fixup involves patching small sections of a template AML
code at runtime, while AML Codegen provides APIs to generate
small sections of AML code at runtime. A combination of
Fixup and Codegen can also be used.

AML has a complex grammar. To simplify the generation of
AML tables, Dynamic AML introduces AmlLib that provides a
rich set of APIs for parsing, traversing, fixup, codegen
and serialisation of AML byte code.

This patch introduces the definitions used by AmlLib.

Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
---
 DynamicTablesPkg/Library/Common/AmlLib/AmlDefines.h | 188 ++++++++++++++++++++
 DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h |  18 ++
 2 files changed, 206 insertions(+)

diff --git a/DynamicTablesPkg/Library/Common/AmlLib/AmlDefines.h b/DynamicTablesPkg/Library/Common/AmlLib/AmlDefines.h
new file mode 100644
index 0000000000000000000000000000000000000000..cbae14d78802005c9b7610e8085a484610e8b18f
--- /dev/null
+++ b/DynamicTablesPkg/Library/Common/AmlLib/AmlDefines.h
@@ -0,0 +1,188 @@
+/** @file
+  AML Defines.
+
+  Copyright (c) 2020, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef AML_DEFINES_H_
+#define AML_DEFINES_H_
+
+/**
+  @defgroup TreeStructures Tree structures
+  @ingroup AMLLib
+  @{
+    The AML tree created by the AMLLib relies on enum/define values and
+    structures defined here.
+  @}
+*/
+
+/** AML tree node types.
+
+  Data nodes are tagged with the data type they contain.
+  Some data types cannot be used for data nodes (None, Object).
+  EAmlUIntX types are converted to the EAML_NODE_DATA_TYPE enum type.
+  These types are accessible externally.
+
+  @ingroup TreeStructures
+*/
+typedef enum EAmlNodeDataType {
+  EAmlNodeDataTypeNone = 0,         ///< EAmlNone,   not accessible.
+  EAmlNodeDataTypeReserved1,        ///< EAmlUInt8,  converted to the UInt type.
+  EAmlNodeDataTypeReserved2,        ///< EAmlUInt16, converted to the UInt type.
+  EAmlNodeDataTypeReserved3,        ///< EAmlUInt32, converted to the UInt type.
+  EAmlNodeDataTypeReserved4,        ///< EAmlUInt64, converted to the UInt type.
+  EAmlNodeDataTypeReserved5,        ///< EAmlObject, not accessible.
+  EAmlNodeDataTypeNameString,       ///< EAmlName, name corresponding to the
+                                    ///  NameString keyword in the ACPI
+                                    ///  specification. E.g.: "\_SB_.DEV0"
+  EAmlNodeDataTypeString,           ///< EAmlString, NULL terminated string.
+  EAmlNodeDataTypeUInt,             ///< Integer data of any length, EAmlUIntX
+                                    ///  are converted to this type.
+  EAmlNodeDataTypeRaw,              ///< Raw bytes contained in a buffer.
+  EAmlNodeDataTypeResourceData,     ///< Resource data element.
+  EAmlNodeDataTypeFieldPkgLen,      ///< FieldPkgLen data element.
+                                    ///  PkgLen are usually stored as
+                                    ///  part of object node structures.
+                                    ///  However, they can be found
+                                    ///  standalone in a FieldList.
+  EAmlNodeDataTypeMax               ///< Max enum.
+} EAML_NODE_DATA_TYPE;
+
+/** Indexes of fixed arguments.
+
+  AML objects defined the ACPI 6.3 specification,
+  s20.3 "AML Byte Stream Byte Values" can have at most 6 fixed arguments.
+
+  Method and functions can have at most 7 arguments, cf
+  s19.6.83 "Method (Declare Control Method)". The enum goes to 8 to store the
+  name of the method invocation.
+
+  @ingroup TreeStructures
+*/
+typedef enum EAmlParseIndex {
+  EAmlParseIndexTerm0  = 0,     ///< First fixed argument index.
+  EAmlParseIndexTerm1,          ///< Second fixed argument index.
+  EAmlParseIndexTerm2,          ///< Third fixed argument index.
+  EAmlParseIndexTerm3,          ///< Fourth fixed argument index.
+  EAmlParseIndexTerm4,          ///< Fifth fixed argument index.
+  EAmlParseIndexTerm5,          ///< Sixth fixed argument index.
+  EAmlParseIndexMax             ///< Maximum fixed argument index (=6).
+} EAML_PARSE_INDEX;
+
+/** Maximum size of an AML NameString.
+
+ An AML NameString can be at most (255 * 4) + 255 + 2 = 1277 bytes long.
+ Indeed, according to ACPI 6.3 specification, s20.2.2,
+ an AML NameString can be resolved as a MultiNamePath.
+
+ The encoding of this MultiNamePath can be made of at most:
+  - 255 carets ('^'), one for each level in the namespace;
+  - 255 NameSeg of 4 bytes;
+  - 2 bytes for the MultiNamePrefix and SegCount.
+
+  @ingroup TreeStructures
+*/
+#define MAX_AML_NAMESTRING_SIZE       1277U
+
+/** Maximum size of an ASL NameString.
+
+ An ASL NameString can be at most (255 * 4) + 255 + 254 = 1529 bytes long.
+ Cf the ASL grammar available in ACPI 6.3 specification, 19.2.2.
+
+ The encoding of an ASL NameString can be made of at most:
+  - 255 carets ('^'), one for each level in the namespace;
+  - 255 NameSeg of 4 bytes;
+  - 254 NameSeg separators ('.').
+
+  @ingroup TreeStructures
+*/
+#define MAX_ASL_NAMESTRING_SIZE       1529U
+
+/** Pseudo OpCode for method invocations.
+
+  The AML grammar does not attribute an OpCode/SubOpCode couple for
+  method invocations. This library is representing method invocations
+  as if they had one.
+
+  The AML encoding for method invocations in the ACPI specification 6.3 is:
+    MethodInvocation := NameString TermArgList
+  In this library, it is:
+    MethodInvocation := MethodInvocationOp NameString ArgumentCount TermArgList
+    ArgumentCount    := ByteData
+
+  When computing the size of a tree or serializing it, the additional data is
+  not taken into account (i.e. the MethodInvocationOp and the ArgumentCount).
+
+  @ingroup TreeStructures
+*/
+#define AML_METHOD_INVOC_OP           0xD0
+
+/** Pseudo OpCode for NamedField field elements.
+
+  The AML grammar does not attribute an OpCode/SubOpCode couple for
+  the NamedField field element. This library is representing NamedField field
+  elements as if they had one.
+
+  The AML encoding for NamedField field elements in the ACPI specification 6.3
+  is:
+    NamedField      := NameSeg PkgLength
+  In this library, it is:
+    NamedField      := NamedFieldOp NameSeg PkgLength
+
+  When computing the size of a tree or serializing it, the additional data is
+  not taken into account (i.e. the NamedFieldOp).
+
+  @ingroup TreeStructures
+*/
+#define AML_FIELD_NAMED_OP            0x04
+
+/** Size of a NameSeg.
+    Cf. ACPI 6.3 specification, s20.2.
+
+  @ingroup TreeStructures
+*/
+ #define AML_NAME_SEG_SIZE            4U
+
+/** AML object types.
+
+  The ACPI specification defines several object types. They are listed
+  with the definition of ObjectTypeKeyword.
+
+  @ingroup TreeStructures
+*/
+typedef enum EAmlObjType {
+  EAmlObjTypeUnknown        = 0x0,
+  EAmlObjTypeInt,
+  EAmlObjTypeStrObj,
+  EAmlObjTypeBuffObj,
+  EAmlObjTypePkgObj,
+  EAmlObjTypeFieldUnitObj,
+  EAmlObjTypeDeviceObj,
+  EAmlObjTypeEventObj,
+  EAmlObjTypeMethodObj,
+  EAmlObjTypeMutexObj,
+  EAmlObjTypeOpRegionObj,
+  EAmlObjTypePowerResObj,
+  EAmlObjTypeProcessorObj,
+  EAmlObjTypeThermalZoneObj,
+  EAmlObjTypeBuffFieldObj,
+  EAmlObjTypeDDBHandleObj,
+} EAML_OBJ_TYPE;
+
+/** Node types.
+
+  @ingroup TreeStructures
+*/
+typedef enum EAmlNodeType {
+  EAmlNodeUnknown,  ///< Unknown/Invalid AML Node Type.
+  EAmlNodeRoot,     ///< AML Root Node, typically represents a DefinitionBlock.
+  EAmlNodeObject,   ///< AML Object Node, typically represents an ASL statement
+                    ///  or its arguments.
+  EAmlNodeData,     ///< AML Data Node, typically represents arguments for an
+                    ///  ASL statement.
+  EAmlNodeMax       ///< Max enum.
+} EAML_NODE_TYPE;
+
+#endif // AML_DEFINES_H_
diff --git a/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h b/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h
new file mode 100644
index 0000000000000000000000000000000000000000..274482f0d1244cdabc5436c5542a2b829083ae93
--- /dev/null
+++ b/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h
@@ -0,0 +1,18 @@
+/** @file
+  AML Include file
+
+  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef AML_INCLUDE_H_
+#define AML_INCLUDE_H_
+
+#include <Base.h>
+#include <Library/BaseLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
+
+#endif // AML_INCLUDE_H_
-- 
'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'