DynamicTablesPkg: AML Parser

Both ASL and AML are declarative language. The ASL code
is compiled to AML bytecode. The AML bytecode is processed
by the ACPI AML interpreter that runs as part of an OS.
AML has a complex encoding making dynamic generation of
Definition Block tables difficult.

Dynamic AML generation involves techniques like AML Fixup
and AML Codegen, both requiring parsing of AML bytecode.

The AML parser is a module that parses an AML byte stream
and represents it as an AML tree. Representing the AML
bytecode as an AML tree is key to reducing the complexity
and enabling Dynamic AML generation.

In an AML Tree each AML statement (that also corresponds
to an ASL statement) is represented as an 'Object Node'.
Each Object Node has an OpCode and up to 6 Fixed Arguments
followed by a list of Variable Arguments.

(ObjectNode)
    \
    |- [0][1][2][3][4][5]             # Fixed Arguments
    |- {(VarArg1)->(VarArg2)->...N}   # Variable Arguments

A Fixed Argument or Variable Argument can be either an
Object Node or a Data Node.

A 'Data Node' consists of a data buffer.

A 'Root Node' is a special type of Object Node that does
not have an Opcode or Fixed Arguments. It only has a list
of Variable Arguments. The Root Node is at the top of the
AML tree and contains the Definition Block Header.

The AML parser uses the 'AML Encoding' to parse an AML byte
stream and represents it as an AML Tree. Representing in the
form of an AML tree simplifies modification, addition and
removal of the tree nodes. The modified tree can then be
serialised to a buffer representing a Definition Block table.

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>

DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlParser.h

@@ -0,0 +1,72 @@
+/** @file
+  AML Parser.
+
+  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef AML_PARSER_H_
+#define AML_PARSER_H_
+
+#include <AmlNodeDefines.h>
+#include <Stream/AmlStream.h>
+
+/** Parse the list of fixed arguments of the input ObjectNode.
+
+  For each argument, create a node and add it to the fixed argument list
+  of the Node.
+  If a fixed argument has children, parse them.
+
+  @param  [in]  ObjectNode        Object node to parse the fixed arguments
+                                  from.
+  @param  [in]  FStream           Forward stream containing the AML
+                                  bytecode to parse.
+                                  The stream must not be at its end.
+  @param  [in]  NameSpaceRefList  List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
+**/
+EFI_STATUS
+EFIAPI
+AmlParseFixedArguments (
+  IN  AML_OBJECT_NODE   * ObjectNode,
+  IN  AML_STREAM        * FStream,
+  IN  LIST_ENTRY        * NameSpaceRefList
+  );
+
+/** Parse the variable list of arguments of the input ObjectNode.
+
+  For each variable argument, create a node and add it to the variable list of
+  arguments of the Node.
+  If a variable argument has children, parse them recursively.
+
+  The arguments of method invocation nodes are added to the variable list of
+  arguments of the method invocation node. It is necessary to first get
+  the number of arguments to parse for this kind of node. A method invocation
+  can have at most 7 fixed arguments.
+
+  @param  [in]  Node              Node to parse the variable arguments
+                                  from.
+  @param  [in]  FStream           Forward stream containing the AML
+                                  bytecode to parse.
+                                  The stream must not be at its end.
+  @param  [in]  NameSpaceRefList  List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
+**/
+EFI_STATUS
+EFIAPI
+AmlParseVariableArguments (
+  IN  AML_NODE_HEADER   * Node,
+  IN  AML_STREAM        * FStream,
+  IN  LIST_ENTRY        * NameSpaceRefList
+  );
+
+#endif // AML_PARSER_H_