DynamicTablesPkg: AmlLib definitions

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>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>

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

diff --git a/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h b/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h
new file mode 100644 (file)
index 0000000..274482f
--- /dev/null
+++ b/DynamicTablesPkg/Library/Common/AmlLib/AmlInclude.h
@@ -0,0 +1,18 @@
+/** @file\r
+  AML Include file\r
+\r
+  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>\r
+\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+**/\r
+\r
+#ifndef AML_INCLUDE_H_\r
+#define AML_INCLUDE_H_\r
+\r
+#include <Base.h>\r
+#include <Library/BaseLib.h>\r
+#include <Library/BaseMemoryLib.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/MemoryAllocationLib.h>\r
+\r
+#endif // AML_INCLUDE_H_\r