public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: "Sami Mujawar" <sami.mujawar@arm.com>
To: <devel@edk2.groups.io>
Cc: Sami Mujawar <sami.mujawar@arm.com>, <Alexei.Fedorov@arm.com>,
	<pierre.gondois@arm.com>, <ard.biesheuvel@arm.com>,
	<Matteo.Carlini@arm.com>, <Ben.Adderson@arm.com>, <nd@arm.com>
Subject: [PATCH v1 19/30] DynamicTablesPkg: AML Method parser
Date: Wed, 12 Aug 2020 16:22:25 +0100	[thread overview]
Message-ID: <20200812152236.31164-20-sami.mujawar@arm.com> (raw)
In-Reply-To: <20200812152236.31164-1-sami.mujawar@arm.com>

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

The AML language allows a Definition Block to implement
methods that an Operating System can invoke at runtime.

Although Dynamic AML does not provide interfaces to
modify AML methods; an AML template code may contain
methods and/or method invocations.

Method definitions have an opcode defined in the AML
encoding and can be easily parsed. However, the language
does not define an opcode for method invocation. Method
invocations are represented as a NameString followed by
the arguments to the method. This poses a significant
challenge for the AML parser as it has to determine if
a NameString appearing in the AML byte stream is a method
invocation and if it is a method invocation, then how
many arguments follow.

This also means the Method definition must occur prior to
the method invocation in the AML byte stream. This is a
hard requirement for the AML parser.

The AML method parser maintains a NameSpaceRefList that
keeps a track of every namespace node and its raw AML
absolute path. The AmlIsMethodInvocation() searches the
NameSpaceRefList to determine if a NameString matches
a Method definition.

A pseudo opcode has been defined in the AML encoding to
represent the Method invocation in the AML tree.

The AML encoding for method invocations in the ACPI
specification 6.3 is:
    MethodInvocation := NameString TermArgList

The AmlLib library redefines this as:
    MethodInvocation := MethodInvocationOp NameString
                          ArgumentCount TermArgList
    ArgumentCount    := ByteData

    Where MethodInvocationOp is the pseudo opcode and
    ArgumentCount is the number of arguments passed to
    the method.

NOTE:
  The AmlLib library's definition for a method
  invocation only applies to the representation
  of method invocation node in the AML tree.
  When computing the size of a tree or serialising
  it, the additional data is not taken into account
  i.e. the MethodInvocationOp and the ArgumentCount
  are stripped before serialising.

  Method invocation nodes have the AML_METHOD_INVOVATION
  attribute set in the AmlLib library's representation of
  the AML encoding.

Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
---
 DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.c | 1458 ++++++++++++++++++++
 DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.h |  188 +++
 2 files changed, 1646 insertions(+)

diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.c b/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.c
new file mode 100644
index 0000000000000000000000000000000000000000..bc98d950b579dec3243dab355a711a56dca978ea
--- /dev/null
+++ b/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.c
@@ -0,0 +1,1458 @@
+/** @file
+  AML Method Parser.
+
+  Copyright (c) 2020, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#include <Parser/AmlMethodParser.h>
+
+#include <AmlCoreInterface.h>
+#include <AmlDbgPrint/AmlDbgPrint.h>
+#include <NameSpace/AmlNameSpace.h>
+#include <Parser/AmlParser.h>
+#include <Tree/AmlNode.h>
+#include <Tree/AmlTree.h>
+#include <String/AmlString.h>
+
+/** Delete a namespace reference node and its pathname.
+
+  It is the caller's responsibility to check the NameSpaceRefNode has been
+  removed from any list the node is part of.
+
+  @param  [in]  NameSpaceRefNode   Pointer to an AML_NAMESPACE_REF_NODE.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlDeleteNameSpaceRefNode (
+  IN  AML_NAMESPACE_REF_NODE    * NameSpaceRefNode
+  )
+{
+  if (NameSpaceRefNode == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  if (NameSpaceRefNode->RawAbsolutePath != NULL) {
+    FreePool ((CHAR8*)NameSpaceRefNode->RawAbsolutePath);
+  } else {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  FreePool (NameSpaceRefNode);
+  return EFI_SUCCESS;
+}
+
+/** Delete a list of namespace reference nodes.
+
+  @param  [in]  NameSpaceRefList    List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlDeleteNameSpaceRefList (
+  IN  LIST_ENTRY      * NameSpaceRefList
+  )
+{
+  EFI_STATUS        Status;
+  LIST_ENTRY      * CurrentLink;
+
+  if (NameSpaceRefList == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  while (!IsListEmpty (NameSpaceRefList)) {
+    CurrentLink = NameSpaceRefList->ForwardLink;
+    RemoveEntryList (CurrentLink);
+    Status = AmlDeleteNameSpaceRefNode (
+               (AML_NAMESPACE_REF_NODE*)CurrentLink
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+  } // while
+
+  return EFI_SUCCESS;
+}
+
+/** Create an AML_NAMESPACE_REF_NODE.
+
+  A Buffer is allocated to store the raw AML absolute path.
+
+  @param  [in]  ObjectNode          Node being part of the namespace.
+                                    Must be have the AML_IN_NAMESPACE
+                                    attribute.
+  @param  [in]  RawAbsolutePath     AML raw absolute path of the ObjectNode.
+                                    A raw NameString is a concatenated list
+                                    of 4 chars long names.
+  @param  [in]  RawAbsolutePathSize Size of the RawAbsolutePath buffer.
+  @param  [out] NameSpaceRefNodePtr The created AML_METHOD_REF_NODE.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlCreateMethodRefNode (
+  IN  CONST AML_OBJECT_NODE         * ObjectNode,
+  IN  CONST CHAR8                   * RawAbsolutePath,
+  IN        UINT32                    RawAbsolutePathSize,
+  OUT       AML_NAMESPACE_REF_NODE ** NameSpaceRefNodePtr
+  )
+{
+  AML_NAMESPACE_REF_NODE     * NameSpaceRefNode;
+
+  if (!AmlNodeHasAttribute (ObjectNode, AML_IN_NAMESPACE) ||
+      (RawAbsolutePath == NULL)                           ||
+      (RawAbsolutePathSize == 0)                          ||
+      (NameSpaceRefNodePtr == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  NameSpaceRefNode = AllocateZeroPool (sizeof (AML_NAMESPACE_REF_NODE));
+  if (NameSpaceRefNode == NULL) {
+    ASSERT (0);
+    return EFI_OUT_OF_RESOURCES;
+  }
+
+  NameSpaceRefNode->RawAbsolutePathSize = RawAbsolutePathSize;
+  NameSpaceRefNode->RawAbsolutePath = AllocateCopyPool (
+                                        RawAbsolutePathSize,
+                                        RawAbsolutePath
+                                        );
+  if (NameSpaceRefNode->RawAbsolutePath == NULL) {
+    FreePool (NameSpaceRefNode);
+    ASSERT (0);
+    return EFI_OUT_OF_RESOURCES;
+  }
+
+  InitializeListHead (&NameSpaceRefNode->Link);
+
+  NameSpaceRefNode->NodeRef = ObjectNode;
+  *NameSpaceRefNodePtr = NameSpaceRefNode;
+
+  return EFI_SUCCESS;
+}
+
+#if !defined (MDEPKG_NDEBUG)
+
+/** Print the list of raw absolute paths of the NameSpace reference list.
+
+  @param  [in]  NameSpaceRefList    List of NameSpace reference nodes.
+**/
+VOID
+EFIAPI
+AmlDbgPrintNameSpaceRefList (
+  IN  CONST LIST_ENTRY    * NameSpaceRefList
+  )
+{
+  LIST_ENTRY              * CurrLink;
+  AML_NAMESPACE_REF_NODE  * CurrNameSpaceNode;
+
+  if (NameSpaceRefList == NULL) {
+    ASSERT (0);
+    return;
+  }
+
+  DEBUG ((DEBUG_INFO, "AmlMethodParser: List of available raw AML paths:\n"));
+
+  CurrLink = NameSpaceRefList->ForwardLink;
+  while (CurrLink != NameSpaceRefList) {
+    CurrNameSpaceNode = (AML_NAMESPACE_REF_NODE*)CurrLink;
+
+    AmlDbgPrintChars (
+      DEBUG_INFO,
+      CurrNameSpaceNode->RawAbsolutePath,
+      CurrNameSpaceNode->RawAbsolutePathSize
+      );
+    DEBUG ((DEBUG_INFO, "\n"));
+
+    CurrLink = CurrLink->ForwardLink;
+  }
+
+  DEBUG ((DEBUG_INFO, "\n"));
+}
+
+#endif // MDEPKG_NDEBUG
+
+/** From a forward stream pointing to a NameString,
+    initialize a raw backward stream.
+
+        StartOfStream
+  Fstream: CurrPos                                 EndOfStream
+             v                                        v
+             +-----------------------------------------+
+             |^^^[Multi-name prefix]AAAA.BBBB.CCCC     |
+             +-----------------------------------------+
+                                    ^            ^
+  RawPathNameBStream:           EndOfStream    CurrPos
+                                            StartOfStream
+
+  No memory is allocated when initializing the stream.
+
+  @param  [in]  FStream             Forward stream pointing to a NameString.
+                                    The stream must not be at its end.
+  @param  [out] RawPathNameBStream  Backward stream containing the
+                                    raw AML path.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlInitRawPathBStream (
+  IN  CONST AML_STREAM    * FStream,
+  OUT       AML_STREAM    * RawPathNameBStream
+  )
+{
+  EFI_STATUS    Status;
+
+  UINT8       * RawPathBuffer;
+  CONST CHAR8 * Buffer;
+
+  UINT32        Root;
+  UINT32        ParentPrefix;
+  UINT32        SegCount;
+
+  if (!IS_STREAM (FStream)          ||
+      IS_END_OF_STREAM (FStream)    ||
+      !IS_STREAM_FORWARD  (FStream) ||
+      (RawPathNameBStream == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Buffer = (CONST CHAR8*)AmlStreamGetCurrPos (FStream);
+  if (Buffer == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Parse the NameString information.
+  Status = AmlParseNameStringInfo (
+             Buffer,
+             &Root,
+             &ParentPrefix,
+             &SegCount
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // Get the beginning of the raw NameString.
+  RawPathBuffer = (UINT8*)AmlGetFirstNameSeg (
+                            Buffer,
+                            Root,
+                            ParentPrefix
+                            );
+  if (RawPathBuffer == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Initialize a backward stream containing the raw path.
+  Status = AmlStreamInit (
+             RawPathNameBStream,
+             RawPathBuffer,
+             (SegCount * AML_NAME_SEG_SIZE),
+             EAmlStreamDirectionBackward
+             );
+  ASSERT_EFI_ERROR (Status);
+
+  return Status;
+}
+
+/** Get the first node in the ParentNode branch that is part of the
+    AML namespace and has its name defined.
+
+  This is different from getting the first namespace node. This function is
+  necessary because an absolute path is built while the tree is not complete
+  yet. The parsing is ongoing.
+
+  For instance, the ASL statement "CreateXXXField ()" adds a field in the
+  AML namespace, but the name it defines is the last fixed argument of the
+  corresponding object.
+  If an AML path is referenced in its first fixed argument, it is not
+  possible to resolve the name of the CreateXXXField object. However, the AML
+  path is not part of the scope created by the CreateXXXField object, so this
+  scope can be skipped.
+
+  In the following ASL code, the method invocation to MET0 is done in the
+  "CreateField" statement. The "CreateField" statement defines the "FIEL"
+  path in the AML namespace. However, MET0 must be not be resolved in the
+  "CreateField" object scope. It needs to be resolved in its parent.
+  ASL code:
+  Method (MET0, 0,,, BuffObj) {
+    Return (Buffer (0x1000) {})
+  }
+  CreateField (MET0(), 0x100, 0x4, FIEL)
+
+  @param  [in]  Node          Node to get the first named node from, in
+                              its hierarchy.
+  @param  [out] OutNamedNode  First named node in Node's hierarchy.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlGetFirstNamedAncestorNode (
+  IN  CONST AML_NODE_HEADER   * Node,
+  OUT       AML_NODE_HEADER  ** OutNamedNode
+  )
+{
+  EFI_STATUS                Status;
+  CONST AML_NODE_HEADER   * NameSpaceNode;
+
+  if ((!IS_AML_OBJECT_NODE (Node)   &&
+       !IS_AML_ROOT_NODE (Node))    ||
+      (OutNamedNode == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // If Node is not the root node and doesn't have a name defined yet,
+  // get the ancestor NameSpace node.
+  while (!IS_AML_ROOT_NODE (Node)             &&
+         !(AmlNodeHasAttribute (
+             (CONST AML_OBJECT_NODE*)Node,
+              AML_IN_NAMESPACE)               &&
+           AmlNodeGetName ((CONST AML_OBJECT_NODE*)Node) != NULL)) {
+    Status = AmlGetFirstAncestorNameSpaceNode (
+                Node,
+                (AML_NODE_HEADER**)&NameSpaceNode
+                );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+    // The NameSpaceNode may not have its name defined as yet. In this
+    // case get the next ancestor node.
+    Node = NameSpaceNode;
+  }
+
+  *OutNamedNode = (AML_NODE_HEADER*)Node;
+
+  return EFI_SUCCESS;
+}
+
+/** From a ParentNode and a forward stream pointing to a relative path,
+    build a raw AML absolute path and return it in a backward stream.
+
+  No memory is allocated in this function, the out stream must be initialized
+  with a buffer long enough to hold any raw absolute AML path.
+
+  @param  [in]  ParentNode                  Parent node of the namespace
+                                            node from which the absolute
+                                            path is built. ParentNode isn't
+                                            necessarily a namespace node.
+                                            Must be a root or an object node.
+  @param  [in]  PathnameFStream             Forward stream pointing to the
+                                            beginning of a pathname (any
+                                            NameString).
+                                            The stream must not be at its end.
+  @param  [in, out] AbsolutePathBStream     Backward stream where the raw
+                                            absolute path is written. The
+                                            stream must be already initialized.
+                                            The stream must not be at its end.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_BUFFER_TOO_SMALL    No space left in the buffer.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlBuildRawMethodAbsolutePath (
+  IN      CONST AML_NODE_HEADER   * ParentNode,
+  IN      CONST AML_STREAM        * PathnameFStream,
+  IN  OUT       AML_STREAM        * AbsolutePathBStream
+  )
+{
+  EFI_STATUS          Status;
+
+  AML_NODE_HEADER   * NamedParentNode;
+  UINT8             * RawPathBuffer;
+  CONST CHAR8       * CurrPos;
+
+  UINT32              Root;
+  UINT32              ParentPrefix;
+  UINT32              SegCount;
+
+  if ((!IS_AML_OBJECT_NODE (ParentNode)         &&
+       !IS_AML_ROOT_NODE (ParentNode))          ||
+      !IS_STREAM (PathnameFStream)              ||
+      IS_END_OF_STREAM (PathnameFStream)        ||
+      !IS_STREAM_FORWARD (PathnameFStream)      ||
+      !IS_STREAM (AbsolutePathBStream)          ||
+      IS_END_OF_STREAM (AbsolutePathBStream)    ||
+      !IS_STREAM_BACKWARD (AbsolutePathBStream)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  CurrPos = (CONST CHAR8*)AmlStreamGetCurrPos (PathnameFStream);
+  if (CurrPos == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Parse the NameString information.
+  Status = AmlParseNameStringInfo (
+             CurrPos,
+             &Root,
+             &ParentPrefix,
+             &SegCount
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // Copy the method invocation raw relative path at the end of the Stream.
+  if (SegCount != 0) {
+    // Get the beginning of the raw NameString.
+    RawPathBuffer = (UINT8*)AmlGetFirstNameSeg (
+                              CurrPos,
+                              Root,
+                              ParentPrefix
+                              );
+
+    Status = AmlStreamWrite (
+               AbsolutePathBStream,
+               RawPathBuffer,
+               SegCount * AML_NAME_SEG_SIZE
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+  }
+
+  // If the pathname contained an absolute path, this is finished, return.
+  if (Root) {
+    return Status;
+  }
+
+  // Get the first named node of the parent node in its hierarchy.
+  Status = AmlGetFirstNamedAncestorNode (ParentNode, &NamedParentNode);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // Build the raw absolute path of the namespace node.
+  Status = AmlGetRawNameSpacePath (
+             NamedParentNode,
+             ParentPrefix,
+             AbsolutePathBStream
+             );
+  ASSERT_EFI_ERROR (Status);
+
+  return Status;
+}
+
+/** Compare two raw NameStrings stored in forward streams.
+    Compare them NameSeg by NameSeg (a NameSeg is 4 bytes long).
+
+  The two raw NameStrings can be of different size.
+
+  @param  [in]  RawFStream1     First forward stream to compare.
+                                Points to the beginning of the raw NameString.
+  @param  [in]  RawFStream2     Second forward stream to compare.
+                                Points to the beginning of the raw NameString.
+  @param  [out] CompareCount    Count of identic bytes.
+                                Must be a multiple of 4 (size of a NameSeg).
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlCompareRawNameString (
+  IN  CONST AML_STREAM    * RawFStream1,
+  IN  CONST AML_STREAM    * RawFStream2,
+  OUT       UINT32        * CompareCount
+  )
+{
+  EFI_STATUS    Status;
+  UINT32        Index;
+
+  AML_STREAM    RawFStream1Clone;
+  AML_STREAM    RawFStream2Clone;
+  UINT32        Stream1Size;
+  UINT32        Stream2Size;
+  UINT32        CompareLen;
+
+  // Raw NameStrings have a size that is a multiple of the size of NameSegs.
+  if (!IS_STREAM (RawFStream1)          ||
+      IS_END_OF_STREAM (RawFStream1)    ||
+      !IS_STREAM_FORWARD (RawFStream1)  ||
+      !IS_STREAM (RawFStream2)          ||
+      IS_END_OF_STREAM (RawFStream2)    ||
+      (CompareCount == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Stream1Size = AmlStreamGetFreeSpace (RawFStream1);
+  if ((Stream1Size & (AML_NAME_SEG_SIZE - 1)) != 0) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Stream2Size = AmlStreamGetFreeSpace (RawFStream2);
+  if ((Stream2Size & (AML_NAME_SEG_SIZE - 1)) != 0) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Status = AmlStreamClone (RawFStream1, &RawFStream1Clone);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  Status = AmlStreamClone (RawFStream2, &RawFStream2Clone);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  CompareLen = MIN (Stream1Size, Stream2Size);
+  Index = 0;
+  // Check there is enough space for a NameSeg in both Stream1 and Stream2.
+  while (Index < CompareLen) {
+    if (!AmlStreamCmp (
+           &RawFStream1Clone,
+           &RawFStream2Clone,
+           AML_NAME_SEG_SIZE)
+           ) {
+      // NameSegs are different. Break.
+      break;
+    }
+
+    Status = AmlStreamProgress (&RawFStream1Clone, AML_NAME_SEG_SIZE);
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+    Status = AmlStreamProgress (&RawFStream2Clone, AML_NAME_SEG_SIZE);
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+
+    Index += AML_NAME_SEG_SIZE;
+  }
+
+  *CompareCount = Index;
+
+  return EFI_SUCCESS;
+}
+
+/** Check whether an alias can be resolved to a method definition.
+
+  Indeed, the following ASL code must be handled:
+    Method (MET0, 1) {
+      Return (0x9)
+    }
+    Alias (\MET0, \ALI0)
+    Alias (\ALI0, \ALI1)
+    \ALI1(0x5)
+  When searching for \ALI1 in the AML NameSpace, it resolves to \ALI0.
+  When searching for \ALI0 in the AML NameSpace, it resolves to \MET0.
+  When searching for \MET0 in the AML NameSpace, it resolves to a method
+  definition.
+
+  This method is a wrapper to recursively call AmlFindMethodDefinition.
+
+  @param  [in]  AliasNode             Pointer to an Alias object node.
+  @param  [in]  NameSpaceRefList      List of NameSpaceRef nodes.
+  @param  [out] OutNameSpaceRefNode   If success, and if the alias is resolved
+                                      to a method definition (this can go
+                                      through other alias indirections),
+                                      containing the corresponding
+                                      NameSpaceRef node.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlResolveAliasMethod (
+  IN  CONST AML_OBJECT_NODE           * AliasNode,
+  IN  CONST LIST_ENTRY                * NameSpaceRefList,
+  OUT       AML_NAMESPACE_REF_NODE   ** OutNameSpaceRefNode
+  )
+{
+  EFI_STATUS              Status;
+  AML_STREAM              SourceAliasFStream;
+  CONST AML_DATA_NODE   * DataNode;
+
+  if (!AmlNodeCompareOpCode (AliasNode, AML_ALIAS_OP, 0)  ||
+      (NameSpaceRefList == NULL)                          ||
+      (OutNameSpaceRefNode == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // The aliased NameString (the source name) is the first fixed argument,
+  // cf. ACPI6.3 spec, s19.6.4: Alias (SourceObject, AliasObject)
+  DataNode = (CONST AML_DATA_NODE*)AmlGetFixedArgument (
+                                     (AML_OBJECT_NODE*)AliasNode,
+                                     EAmlParseIndexTerm0
+                                     );
+  if (DataNode == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Initialize a stream on the source alias NameString.
+  Status = AmlStreamInit (
+             &SourceAliasFStream,
+             DataNode->Buffer,
+             DataNode->Size,
+             EAmlStreamDirectionForward
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // Recursively check whether the source alias NameString
+  // is a method invocation.
+  Status = AmlIsMethodInvocation (
+             AmlGetParent ((AML_NODE_HEADER*)AliasNode),
+             &SourceAliasFStream,
+             NameSpaceRefList,
+             OutNameSpaceRefNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+  }
+
+  return Status;
+}
+
+/** Iterate through the MethodList to find the best namespace resolution.
+    If the pathname resolves to a method definition, returns it.
+
+  For instance, if the AML namespace is:
+  \
+  \-MET0         <- Device definition, absolute path: \MET0
+  \-AAAA
+    \-MET0       <- Method definition, absolute path: \AAAA.MET0
+    \-MET1       <- Method definition, absolute path: \AAAA.MET1
+    \-BBBB
+      \-CCCC
+        \-DDDD
+          \-MET0 <- Method definition, absolute path: \AAAA.BBBB.CCCC.DDDD.MET0
+
+  The list of the available pathnames is:
+  [NameSpaceRefList]
+   - \MET0                          <-  Device definition
+   - \AAAA
+   - \AAAA.MET0                     <-  Method definition
+   - \AAAA.MET1                     <-  Method definition
+   - \AAAA.BBBB
+   - \AAAA.BBBB.CCCC
+   - \AAAA.BBBB.CCCC.DDDD
+   - \AAAA.BBBB.CCCC.DDDD.MET0      <-  Method definition
+
+  Depending on where the method invocation is done, the method definition
+  referenced changes. If the method call "MET0" is done from
+  \AAAA.BBBB.CCCC:
+    1. Identify which pathnames end with "MET0":
+     - \MET0                          <-  Device definition
+     - \AAAA.MET0                     <-  Method definition
+     - \AAAA.BBBB.CCCC.DDDD.MET0      <-  Method definition
+    2. Resolve the method invocation:
+     - \AAAA.MET0                     <-  Method definition
+    3. \AAAA.MET0 is a method definition, so return the corresponding
+       reference node.
+
+  @param  [in]  RawAbsolutePathFStream    Forward stream pointing to a raw
+                                          absolute path.
+                                          The stream must not be at its end.
+  @param  [in]  RawPathNameBStream        Backward stream pointing to a raw
+                                          pathname. This raw pathname is the
+                                          raw NameString of namespace node.
+                                          The stream must not be at its end.
+  @param  [in]  NameSpaceRefList          List of NameSpaceRef nodes.
+  @param  [out] OutNameSpaceRefNode       If the two input paths are
+                                          referencing a method definition,
+                                          returns the corresponding
+                                          NameSpaceRef node.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlFindMethodDefinition (
+  IN  CONST AML_STREAM                * RawAbsolutePathFStream,
+  IN  CONST AML_STREAM                * RawPathNameBStream,
+  IN  CONST LIST_ENTRY                * NameSpaceRefList,
+  OUT       AML_NAMESPACE_REF_NODE   ** OutNameSpaceRefNode
+  )
+{
+  EFI_STATUS                Status;
+
+  LIST_ENTRY              * NextLink;
+
+  // To resolve a pathname, scope levels need to be compared.
+  UINT32                    NameSegScopeCount;
+  UINT32                    PathNameSegScopeCount;
+  UINT32                    ProbedScopeCount;
+  UINT32                    BestScopeCount;
+
+  AML_STREAM                ProbedRawAbsoluteFStream;
+  AML_STREAM                ProbedRawAbsoluteBStream;
+
+  AML_NAMESPACE_REF_NODE  * ProbedNameSpaceRefNode;
+  AML_NAMESPACE_REF_NODE  * BestNameSpaceRefNode;
+
+  if (!IS_STREAM (RawAbsolutePathFStream)                               ||
+      IS_END_OF_STREAM (RawAbsolutePathFStream)                         ||
+      !IS_STREAM_FORWARD (RawAbsolutePathFStream)                       ||
+      ((AmlStreamGetIndex (RawAbsolutePathFStream) &
+        (AML_NAME_SEG_SIZE - 1)) != 0)                                  ||
+      !IS_STREAM (RawPathNameBStream)                                   ||
+      IS_END_OF_STREAM (RawPathNameBStream)                             ||
+      !IS_STREAM_BACKWARD (RawPathNameBStream)                          ||
+      ((AmlStreamGetIndex (RawPathNameBStream) &
+        (AML_NAME_SEG_SIZE - 1)) != 0)                                  ||
+      (NameSpaceRefList == NULL)                                        ||
+      (OutNameSpaceRefNode == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  DEBUG ((DEBUG_VERBOSE, "AmlMethodParser: Checking absolute name: "));
+  AmlDbgPrintChars (
+    DEBUG_VERBOSE,
+    (CONST CHAR8*)AmlStreamGetCurrPos (RawAbsolutePathFStream),
+    AmlStreamGetMaxBufferSize (RawAbsolutePathFStream)
+    );
+  DEBUG ((DEBUG_VERBOSE, ".\n"));
+
+  BestNameSpaceRefNode = NULL;
+  BestScopeCount = 0;
+  NameSegScopeCount = AmlStreamGetMaxBufferSize (RawAbsolutePathFStream);
+  PathNameSegScopeCount = AmlStreamGetMaxBufferSize (RawPathNameBStream);
+
+  // Iterate through the raw AML absolute path to find the best match.
+  DEBUG ((DEBUG_VERBOSE, "AmlMethodParser: Comparing with: "));
+  NextLink = NameSpaceRefList->ForwardLink;
+  while (NextLink != NameSpaceRefList) {
+    ProbedNameSpaceRefNode = (AML_NAMESPACE_REF_NODE*)NextLink;
+
+    // Print the raw absolute path of the probed node.
+    AmlDbgPrintChars (
+      DEBUG_VERBOSE,
+      ProbedNameSpaceRefNode->RawAbsolutePath,
+      ProbedNameSpaceRefNode->RawAbsolutePathSize
+      );
+    DEBUG ((DEBUG_VERBOSE, "; "));
+
+    // If the raw AML absolute path of the probed node is longer than the
+    // searched pathname, continue.
+    // E.g.: The method call \MET0 cannot resolve to a method defined at
+    //       \AAAA.MET0. The method definition is out of scope.
+    if (PathNameSegScopeCount > ProbedNameSpaceRefNode->RawAbsolutePathSize) {
+      NextLink = NextLink->ForwardLink;
+      continue;
+    }
+
+    // Initialize a backward stream for the probed node.
+    // This stream is used to compare the ending of the pathnames.
+    // E.g. if the method searched ends with "MET0", pathnames not ending with
+    //      "MET0" should be skipped.
+    Status = AmlStreamInit (
+               &ProbedRawAbsoluteBStream,
+               (UINT8*)ProbedNameSpaceRefNode->RawAbsolutePath,
+               ProbedNameSpaceRefNode->RawAbsolutePathSize,
+               EAmlStreamDirectionBackward
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+
+    // Compare the pathname endings. If they don't match, continue.
+    if (!AmlStreamCmp (
+           RawPathNameBStream,
+           &ProbedRawAbsoluteBStream,
+           AmlStreamGetMaxBufferSize (RawPathNameBStream))) {
+      NextLink = NextLink->ForwardLink;
+      continue;
+    }
+
+    // Initialize a forward stream for the probed node.
+    // This stream is used to count how many scope levels from the root
+    // are common with the probed node. The more there are, the better it is.
+    // E.g.: For the method invocation \AAAA.BBBB.MET0, if there are 2
+    //       pathnames ending with MET0:
+    //        - \AAAA.MET0 has 1 NameSeg in common with \AAAA.BBBB.MET0
+    //          from the root (this is "AAAA");
+    //        - \MET0 has 0 NameSeg in common with \AAAA.BBBB.MET0
+    //          from the root;
+    //       Thus, the best match is \AAAA.MET0.
+    Status = AmlStreamInit (
+               &ProbedRawAbsoluteFStream,
+               (UINT8*)ProbedNameSpaceRefNode->RawAbsolutePath,
+               ProbedNameSpaceRefNode->RawAbsolutePathSize,
+               EAmlStreamDirectionForward
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return Status;
+    }
+
+    // Count how many namespace levels are in common from the root.
+    Status = AmlCompareRawNameString (
+               RawAbsolutePathFStream,
+               &ProbedRawAbsoluteFStream,
+               &ProbedScopeCount
+               );
+    if (EFI_ERROR (Status)) {
+      ASSERT (0);
+      return EFI_INVALID_PARAMETER;
+    }
+
+    if (ProbedScopeCount == NameSegScopeCount) {
+      // This is a perfect match. Exit the loop.
+      BestNameSpaceRefNode = ProbedNameSpaceRefNode;
+      break;
+    } else if (ProbedScopeCount > BestScopeCount) {
+      // The probed node has more scope levels in common than the
+      // last best match. Update the best match.
+      BestScopeCount = ProbedScopeCount;
+      BestNameSpaceRefNode = ProbedNameSpaceRefNode;
+    } else if (ProbedScopeCount == BestScopeCount) {
+      // The probed node has the same number of scope levels in
+      // common as the last best match.
+      if (ProbedScopeCount == 0) {
+        // There was not best match previously. Set it.
+        BestNameSpaceRefNode = ProbedNameSpaceRefNode;
+      } else {
+        // (ProbedScopeCount != 0)
+        // If there is an equivalent candidate, the best has the shortest
+        // absolute path. Indeed, a similar ProbedScopeCount and a longer
+        // path means the definition is out of the scope.
+        // E.g.: For the method invocation \AAAA.BBBB.MET0, if there are 2
+        //       pathnames ending with MET0:
+        //        - \AAAA.MET0 has 1 NameSegs in common with \AAAA.BBBB.MET0
+        //          from the root (this is "AAAA");
+        //        - \AAAA.CCCC.MET0 has 1 NameSegs in common with
+        //          \AAAA.BBBB.MET0 from the root (this is "AAAA");
+        //       As \AAAA.CCCC.MET0 is longer than \AAAA.MET0, it means that
+        //       the pathname could have matched on more NameSegs, but it
+        //       didn't because it is out of scope.
+        //       Thus, the best match is \AAAA.MET0.
+        if (AmlStreamGetIndex (&ProbedRawAbsoluteFStream) <
+              BestNameSpaceRefNode->RawAbsolutePathSize) {
+          BestScopeCount = ProbedScopeCount;
+          BestNameSpaceRefNode = ProbedNameSpaceRefNode;
+        } else if (AmlStreamGetIndex (&ProbedRawAbsoluteFStream) ==
+                     BestNameSpaceRefNode->RawAbsolutePathSize) {
+          ASSERT (0);
+          return EFI_INVALID_PARAMETER;
+        }
+      }
+    }
+
+    NextLink = NextLink->ForwardLink;
+  }
+
+  DEBUG ((DEBUG_VERBOSE, "\n"));
+
+  // Check whether the BestNameSpaceRefNode is a method definition.
+  if (BestNameSpaceRefNode != NULL) {
+    if (AmlIsMethodDefinitionNode (BestNameSpaceRefNode->NodeRef)) {
+      *OutNameSpaceRefNode = BestNameSpaceRefNode;
+    } else if (AmlNodeCompareOpCode (
+                 BestNameSpaceRefNode->NodeRef,
+                 AML_ALIAS_OP, 0)) {
+      // The path matches an alias. Resolve the alias and check whether
+      // this is a method defintion.
+      Status = AmlResolveAliasMethod (
+                 BestNameSpaceRefNode->NodeRef,
+                 NameSpaceRefList,
+                 OutNameSpaceRefNode
+                 );
+      if (EFI_ERROR (Status)) {
+        ASSERT (0);
+        return Status;
+      }
+    }
+  } else {
+    // If no, return NULL, even if a matching pathname has been found.
+    *OutNameSpaceRefNode = NULL;
+  }
+
+  return EFI_SUCCESS;
+}
+
+/** Check whether a pathname is a method invocation.
+
+  If there is a matching method definition, returns the corresponding
+  NameSpaceRef node.
+
+  To do so, the NameSpaceRefList is keeping track of every namespace node
+  and its raw AML absolute path.
+  To check whether a pathname is a method invocation, a corresponding raw
+  absolute pathname is built. This raw absolute pathname is then compared
+  to the list of available pathnames. If a pathname defining a method
+  matches the scope of the input pathname, return.
+
+  @param  [in]  ParentNode          Parent node. Node to which the node to be
+                                    created will be attached.
+  @param  [in]  FStream             Forward stream pointing to the NameString
+                                    to find.
+  @param  [in]  NameSpaceRefList    List of NameSpaceRef nodes.
+  @param  [out] OutNameSpaceRefNode If the NameString pointed by FStream is
+                                    a method invocation, OutNameSpaceRefNode
+                                    contains the NameSpaceRef corresponding
+                                    to the method definition.
+                                    NULL otherwise.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlIsMethodInvocation (
+  IN  CONST AML_NODE_HEADER     * ParentNode,
+  IN  CONST AML_STREAM          * FStream,
+  IN  CONST LIST_ENTRY          * NameSpaceRefList,
+  OUT AML_NAMESPACE_REF_NODE   ** OutNameSpaceRefNode
+  )
+{
+  EFI_STATUS                Status;
+
+  AML_STREAM                RawPathNameBStream;
+  AML_STREAM                RawAbsolutePathFStream;
+
+  AML_STREAM                RawAbsolutePathBStream;
+  UINT8                   * RawAbsolutePathBuffer;
+  UINT32                    RawAbsolutePathBufferSize;
+
+  AML_NAMESPACE_REF_NODE  * NameSpaceRefNode;
+
+  if ((!IS_AML_OBJECT_NODE (ParentNode) &&
+       !IS_AML_ROOT_NODE (ParentNode))  ||
+      !IS_STREAM (FStream)              ||
+      IS_END_OF_STREAM (FStream)        ||
+      !IS_STREAM_FORWARD (FStream)      ||
+      (NameSpaceRefList == NULL)        ||
+      (OutNameSpaceRefNode == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // There cannot be a method invocation in a field list. Return.
+  if (AmlNodeHasAttribute (
+        (CONST AML_OBJECT_NODE*)ParentNode,
+        AML_HAS_FIELD_LIST)) {
+    *OutNameSpaceRefNode = NULL;
+    return EFI_SUCCESS;
+  }
+
+  // Allocate memory for the raw absolute path.
+  RawAbsolutePathBufferSize = MAX_AML_NAMESTRING_SIZE;
+  RawAbsolutePathBuffer = AllocateZeroPool (RawAbsolutePathBufferSize);
+  if (RawAbsolutePathBuffer == NULL) {
+    ASSERT (0);
+    return EFI_OUT_OF_RESOURCES;
+  }
+
+  // Initialize a backward stream to get the raw absolute path.
+  Status = AmlStreamInit (
+             &RawAbsolutePathBStream,
+             RawAbsolutePathBuffer,
+             RawAbsolutePathBufferSize,
+             EAmlStreamDirectionBackward
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  // Build the raw AML absolute path of the namespace node.
+  Status = AmlBuildRawMethodAbsolutePath (
+             ParentNode,
+             FStream,
+             &RawAbsolutePathBStream
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  // If this is the root path: it cannot be a method invocation. Just return.
+  if (AmlStreamGetIndex (&RawAbsolutePathBStream) == 0) {
+    DEBUG ((
+      DEBUG_VERBOSE,
+      "AmlMethodParser: "
+      "Root node cannot be a method invocation\n"
+      ));
+    *OutNameSpaceRefNode = NULL;
+    Status = EFI_SUCCESS;
+    goto exit_handler;
+  }
+
+  // Create a forward stream for the raw absolute path.
+  // This forward stream only contains the raw absolute path with
+  // no extra free space.
+  Status = AmlStreamInit (
+             &RawAbsolutePathFStream,
+             AmlStreamGetCurrPos (&RawAbsolutePathBStream),
+             AmlStreamGetIndex (&RawAbsolutePathBStream),
+             EAmlStreamDirectionForward
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  // Create a backward stream for the node name.
+  Status = AmlInitRawPathBStream (
+             FStream,
+             &RawPathNameBStream
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // Go through the NameSpaceRefList elements to check for
+  // a corresponding method definition.
+  NameSpaceRefNode = NULL;
+  Status = AmlFindMethodDefinition (
+             &RawAbsolutePathFStream,
+             &RawPathNameBStream,
+             NameSpaceRefList,
+             &NameSpaceRefNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+#if !defined(MDEPKG_NDEBUG)
+  // Print whether a method definition has been found.
+  if (NameSpaceRefNode != NULL) {
+    DEBUG ((
+      DEBUG_VERBOSE,
+      "AmlMethodParser: Corresponding method definition: "
+      ));
+    AmlDbgPrintChars (
+      DEBUG_VERBOSE,
+      NameSpaceRefNode->RawAbsolutePath,
+      NameSpaceRefNode->RawAbsolutePathSize
+      );
+    DEBUG ((DEBUG_VERBOSE, ".\n"));
+
+  } else {
+    DEBUG ((DEBUG_VERBOSE, "AmlMethodParser: No method definition found.\n"));
+  }
+#endif // MDEPKG_NDEBUG
+
+  *OutNameSpaceRefNode = NameSpaceRefNode;
+
+exit_handler:
+  // Free allocated memory.
+  FreePool (RawAbsolutePathBuffer);
+  return Status;
+}
+
+/** Create a namespace reference node and add it to the NameSpaceRefList.
+
+  When a namespace node is encountered, the namespace it defines must be
+  associated to the node. This allow to keep track of the nature of each
+  name present in the AML namespace.
+
+  In the end, this allows to recognize method invocations and parse the right
+  number of arguments after the method name.
+
+  @param [in]       Node              Namespace node.
+  @param [in, out]  NameSpaceRefList  List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlAddNameSpaceReference (
+  IN      CONST AML_OBJECT_NODE   * Node,
+  IN  OUT       LIST_ENTRY        * NameSpaceRefList
+  )
+{
+  EFI_STATUS                Status;
+  AML_NAMESPACE_REF_NODE  * NameSpaceRefNode;
+
+  AML_STREAM                NodeNameFStream;
+  EAML_PARSE_INDEX          NameIndex;
+  CONST AML_DATA_NODE     * NameNode;
+
+  AML_STREAM                RawAbsolutePathBStream;
+  UINT32                    RawAbsolutePathBStreamSize;
+
+  CHAR8                   * AbsolutePathBuffer;
+  UINT32                    AbsolutePathBufferSize;
+
+  CONST AML_NODE_HEADER   * ParentNode;
+
+  if (!AmlNodeHasAttribute (Node, AML_IN_NAMESPACE)   ||
+      (NameSpaceRefList == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Allocate a buffer to get the raw AML absolute pathname of the
+  // namespace node.
+  AbsolutePathBufferSize = MAX_AML_NAMESTRING_SIZE;
+  AbsolutePathBuffer = AllocateZeroPool (AbsolutePathBufferSize);
+  if (AbsolutePathBuffer == NULL) {
+    ASSERT (0);
+    return EFI_OUT_OF_RESOURCES;
+  }
+
+  Status = AmlStreamInit (
+             &RawAbsolutePathBStream,
+             (UINT8*)AbsolutePathBuffer,
+             AbsolutePathBufferSize,
+             EAmlStreamDirectionBackward
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    Status = EFI_INVALID_PARAMETER;
+    goto exit_handler;
+  }
+
+  // Get the index where the name of the Node is stored in its
+  // fixed list of arguments.
+  Status = AmlNodeGetNameIndex (Node, &NameIndex);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    Status = EFI_INVALID_PARAMETER;
+    goto exit_handler;
+  }
+
+  // Get the Node name.
+  NameNode = (CONST AML_DATA_NODE*)AmlGetFixedArgument (
+                                     (AML_OBJECT_NODE*)Node,
+                                     NameIndex
+                                     );
+  if (!IS_AML_DATA_NODE (NameNode)    ||
+      (NameNode->DataType != EAmlNodeDataTypeNameString)) {
+    ASSERT (0);
+    Status = EFI_INVALID_PARAMETER;
+    goto exit_handler;
+  }
+
+  // Initialize a stream on the node name of the namespace node.
+  // This is an AML NameString.
+  Status = AmlStreamInit (
+             &NodeNameFStream,
+             NameNode->Buffer,
+             NameNode->Size,
+             EAmlStreamDirectionForward
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    Status = EFI_INVALID_PARAMETER;
+    goto exit_handler;
+  }
+
+  ParentNode = AmlGetParent ((AML_NODE_HEADER*)Node);
+  if (ParentNode == NULL) {
+    ASSERT (0);
+    Status = EFI_INVALID_PARAMETER;
+    goto exit_handler;
+  }
+
+  // Build the raw AML absolute path of the namespace node.
+  Status = AmlBuildRawMethodAbsolutePath (
+             ParentNode,
+             &NodeNameFStream,
+             &RawAbsolutePathBStream
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  RawAbsolutePathBStreamSize = AmlStreamGetIndex (&RawAbsolutePathBStream);
+  // This is the root path: this cannot be a method invocation.
+  if (RawAbsolutePathBStreamSize == 0) {
+    Status = EFI_SUCCESS;
+    goto exit_handler;
+  }
+
+  // Create a NameSpace reference node.
+  Status = AmlCreateMethodRefNode (
+             Node,
+             (CONST CHAR8*)AmlStreamGetCurrPos (&RawAbsolutePathBStream),
+             RawAbsolutePathBStreamSize,
+             &NameSpaceRefNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  // Add the created NameSpaceRefNode to the list.
+  InsertTailList (NameSpaceRefList, &NameSpaceRefNode->Link);
+
+  DEBUG ((
+    DEBUG_VERBOSE,
+    "AmlMethodParser: Adding namespace reference with name:\n"
+    ));
+  AmlDbgPrintChars (
+    DEBUG_VERBOSE,
+    (CONST CHAR8*)AmlStreamGetCurrPos (&RawAbsolutePathBStream),
+    AmlStreamGetIndex (&RawAbsolutePathBStream)
+    );
+  DEBUG ((DEBUG_VERBOSE, "\n"));
+
+exit_handler:
+  // Free allocated memory.
+  FreePool (AbsolutePathBuffer);
+
+  return Status;
+}
+
+/** Create a method invocation node.
+
+  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).
+
+  Method invocation nodes have the AML_METHOD_INVOVATION attribute.
+
+  @param  [in]  NameSpaceRefNode          NameSpaceRef node pointing to the
+                                          the definition of the invoked
+                                          method.
+  @param  [in]  MethodInvocationName      Data node containing the method
+                                          invocation name.
+  @param  [out] MethodInvocationNodePtr   Created method invocation node.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
+**/
+EFI_STATUS
+EFIAPI
+AmlCreateMethodInvocationNode (
+  IN  CONST AML_NAMESPACE_REF_NODE   * NameSpaceRefNode,
+  IN        AML_DATA_NODE            * MethodInvocationName,
+  OUT       AML_OBJECT_NODE         ** MethodInvocationNodePtr
+  )
+{
+  EFI_STATUS            Status;
+
+  UINT8                 ArgCount;
+  AML_DATA_NODE       * ArgCountNode;
+  AML_NODE_HEADER    ** FixedArgs;
+  AML_OBJECT_NODE     * MethodDefinitionNode;
+  AML_OBJECT_NODE     * MethodInvocationNode;
+
+  if ((NameSpaceRefNode == NULL)                                      ||
+      !AmlIsMethodDefinitionNode (NameSpaceRefNode->NodeRef)          ||
+      !IS_AML_DATA_NODE (MethodInvocationName)                        ||
+      (MethodInvocationName->DataType != EAmlNodeDataTypeNameString)  ||
+      (MethodInvocationNodePtr == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Get the number of arguments of the method.
+  MethodDefinitionNode = (AML_OBJECT_NODE*)NameSpaceRefNode->NodeRef;
+  FixedArgs = MethodDefinitionNode->FixedArgs;
+  // The method definition is an actual method definition.
+  if (AmlNodeCompareOpCode (MethodDefinitionNode, AML_METHOD_OP, 0)) {
+    // Cf ACPI 6.3 specification:
+    //  DefMethod := MethodOp PkgLength NameString MethodFlags TermList
+    //  MethodOp := 0x14
+    //  MethodFlags := ByteData  bit 0-2: ArgCount (0-7)
+    //                           bit 3: SerializeFlag
+    //                                    0 NotSerialized
+    //                                    1 Serialized
+    //                           bit 4-7: SyncLevel (0x00-0x0f)
+
+    // Read the MethodFlags to decode the ArgCount.
+    ArgCountNode = (AML_DATA_NODE*)FixedArgs[EAmlParseIndexTerm1];
+    ArgCount = *((UINT8*)ArgCountNode->Buffer) & 0x7;
+  } else if (AmlNodeCompareOpCode (MethodDefinitionNode, AML_EXTERNAL_OP, 0)) {
+    // The method definition is an external statement.
+    // Cf ACPI 6.3 specification:
+    //  DefExternal := ExternalOp NameString ObjectType ArgumentCount
+    //  ExternalOp := 0x15
+    //  ObjectType := ByteData
+    //  ArgumentCount := ByteData (0 – 7)
+
+    // Read the ArgumentCount.
+    ArgCountNode = (AML_DATA_NODE*)FixedArgs[EAmlParseIndexTerm2];
+    ArgCount = *((UINT8*)ArgCountNode->Buffer);
+  } else {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Create the object node for the method invocation.
+  // MethodInvocation := MethodInvocationOp NameString ArgumentCount
+  // MethodInvocationOp := Pseudo Opcode for Method Invocation
+  // NameString := Method Name
+  // ArgumentCount := ByteData (0 – 7)
+  Status = AmlCreateObjectNode (
+             AmlGetByteEncodingByOpCode (AML_METHOD_INVOC_OP, 0),
+             0,
+             &MethodInvocationNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  // The first fixed argument is the method name.
+  Status = AmlSetFixedArgument (
+             MethodInvocationNode,
+             EAmlParseIndexTerm0,
+             (AML_NODE_HEADER*)MethodInvocationName
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  // Create a data node holding the number of arguments
+  // of the method invocation.
+  ArgCountNode = NULL;
+  Status = AmlCreateDataNode (
+             EAmlNodeDataTypeUInt,
+             &ArgCount,
+             sizeof (UINT8),
+             &ArgCountNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  // The second fixed argument is the number of arguments.
+  Status = AmlSetFixedArgument (
+              MethodInvocationNode,
+              EAmlParseIndexTerm1,
+              (AML_NODE_HEADER*)ArgCountNode
+              );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  *MethodInvocationNodePtr = MethodInvocationNode;
+  return Status;
+
+error_handler:
+  // Delete the sub-tree: the method invocation name is already attached.
+  AmlDeleteTree ((AML_NODE_HEADER*)MethodInvocationNode);
+  if (ArgCountNode != NULL) {
+    AmlDeleteNode ((AML_NODE_HEADER*)ArgCountNode);
+  }
+
+  return Status;
+}
+
+/** Get the number of arguments of a method invocation node.
+
+  This function also allow to identify whether a node is a method invocation
+  node. If the input node is not a method invocation node, just return.
+
+  @param  [in]  MethodInvocationNode  Method invocation node.
+  @param  [out] IsMethodInvocation    Boolean stating whether the input
+                                      node is a method invocation.
+  @param  [out] ArgCount              Number of arguments of the method
+                                      invocation.
+                                      Set to 0 if MethodInvocationNode
+                                      is not a method invocation.
+
+  @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
+AmlGetMethodInvocationArgCount (
+  IN  CONST AML_OBJECT_NODE   * MethodInvocationNode,
+  OUT       BOOLEAN           * IsMethodInvocation,
+  OUT       UINT8             * ArgCount
+  )
+{
+  AML_DATA_NODE   * NumArgsNode;
+
+  if (!IS_AML_NODE_VALID (MethodInvocationNode) ||
+      (IsMethodInvocation == NULL)              ||
+      (ArgCount == NULL)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Check whether MethodInvocationNode is a method invocation.
+  if (!AmlNodeCompareOpCode (MethodInvocationNode, AML_METHOD_INVOC_OP, 0)) {
+    *IsMethodInvocation = FALSE;
+    *ArgCount = 0;
+    return EFI_SUCCESS;
+  }
+
+  // MethodInvocation := MethodInvocationOp NameString ArgumentCount
+  // MethodInvocationOp := Pseudo Opcode for Method Invocation
+  // NameString := Method Name
+  // ArgumentCount := ByteData (0 - 7)
+  NumArgsNode = (AML_DATA_NODE*)AmlGetFixedArgument (
+                                  (AML_OBJECT_NODE*)MethodInvocationNode,
+                                  EAmlParseIndexTerm1
+                                  );
+  if (!IS_AML_NODE_VALID (NumArgsNode)                ||
+      (NumArgsNode->Buffer == NULL)                   ||
+      (NumArgsNode->DataType != EAmlNodeDataTypeUInt) ||
+      (NumArgsNode->Size != 1)) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+  *ArgCount = *NumArgsNode->Buffer;
+
+  *IsMethodInvocation = TRUE;
+  return EFI_SUCCESS;
+}
diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.h b/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.h
new file mode 100644
index 0000000000000000000000000000000000000000..b082f2debde88da8a7dcabee7b4a8b5003d4c592
--- /dev/null
+++ b/DynamicTablesPkg/Library/Common/AmlLib/Parser/AmlMethodParser.h
@@ -0,0 +1,188 @@
+/** @file
+  AML Method Parser.
+
+  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef AML_METHOD_PARSER_H_
+#define AML_METHOD_PARSER_H_
+
+#include <AmlNodeDefines.h>
+#include <Stream/AmlStream.h>
+
+/** AML namespace reference node.
+
+  Namespace reference nodes allow to associate an AML absolute pathname
+  to the tree node defining this object in the namespace.
+
+  Namespace reference nodes are stored in a separate list. They are not part of
+  the tree.
+*/
+typedef struct AmlNameSpaceRefNode {
+  /// Double linked list.
+  /// This must be the first field in this structure.
+  LIST_ENTRY                Link;
+
+  /// Node part of the AML namespace. It must have the AML_IN_NAMESPACE
+  /// attribute.
+  CONST AML_OBJECT_NODE   * NodeRef;
+
+  /// Raw AML absolute pathname of the NodeRef.
+  /// This is a raw AML NameString (cf AmlNameSpace.c: A concatenated list
+  /// of 4 chars long names. The dual/multi NameString prefix have been
+  /// stripped.).
+  CONST CHAR8             * RawAbsolutePath;
+
+  /// Size of the raw AML absolute pathname buffer.
+  UINT32                    RawAbsolutePathSize;
+} AML_NAMESPACE_REF_NODE;
+
+/** Delete a list of namespace reference nodes.
+
+  @param  [in]  NameSpaceRefList    List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlDeleteNameSpaceRefList (
+  IN  LIST_ENTRY      * NameSpaceRefList
+  );
+
+
+#if !defined (MDEPKG_NDEBUG)
+/** Print the list of raw absolute paths of the NameSpace reference list.
+
+  @param  [in]    NameSpaceRefList    List of NameSpace reference nodes.
+**/
+VOID
+EFIAPI
+AmlDbgPrintNameSpaceRefList (
+  IN  CONST LIST_ENTRY    * NameSpaceRefList
+  );
+
+#endif // MDEPKG_NDEBUG
+
+/** Check whether a pathname is a method invocation.
+
+  If there is a matching method definition, returns the corresponding
+  NameSpaceRef node.
+
+  To do so, the NameSpaceRefList is keeping track of every namespace node
+  and its raw AML absolute path.
+  To check whether a pathname is a method invocation, a corresponding raw
+  absolute pathname is built. This raw absolute pathname is then compared
+  to the list of available pathnames. If a pathname defining a method
+  matches the scope of the input pathname, return.
+
+  @param  [in]  ParentNode          Parent node. Node to which the node to be
+                                    created will be attached.
+  @param  [in]  FStream             Forward stream pointing to the NameString
+                                    to find.
+  @param  [in]  NameSpaceRefList    List of NameSpaceRef nodes.
+  @param  [out] OutNameSpaceRefNode If the NameString pointed by FStream is
+                                    a method invocation, OutNameSpaceRefNode
+                                    contains the NameSpaceRef corresponding
+                                    to the method definition.
+                                    NULL otherwise.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlIsMethodInvocation (
+  IN  CONST AML_NODE_HEADER     * ParentNode,
+  IN  CONST AML_STREAM          * FStream,
+  IN  CONST LIST_ENTRY          * NameSpaceRefList,
+  OUT AML_NAMESPACE_REF_NODE   ** OutNameSpaceRefNode
+  );
+
+/** Create a namespace reference node and add it to the NameSpaceRefList.
+
+  When a namespace node is encountered, the namespace it defines must be
+  associated to the node. This allow to keep track of the nature of each
+  name present in the AML namespace.
+
+  In the end, this allows to recognize method invocations and parse the right
+  number of arguments after the method name.
+
+  @param [in]       Node              Namespace node.
+  @param [in, out]  NameSpaceRefList  List of namespace reference nodes.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+AmlAddNameSpaceReference (
+  IN      CONST AML_OBJECT_NODE   * Node,
+  IN  OUT       LIST_ENTRY        * NameSpaceRefList
+  );
+
+/** Create a method invocation node.
+
+  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).
+
+  Method invocation nodes have the AML_METHOD_INVOVATION attribute.
+
+  @param  [in]  NameSpaceRefNode          NameSpaceRef node pointing to the
+                                          the definition of the invoked
+                                          method.
+  @param  [in]  MethodInvocationName      Data node containing the method
+                                          invocation name.
+  @param  [out] MethodInvocationNodePtr   Created method invocation node.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
+**/
+EFI_STATUS
+EFIAPI
+AmlCreateMethodInvocationNode (
+  IN  CONST AML_NAMESPACE_REF_NODE   * NameSpaceRefNode,
+  IN        AML_DATA_NODE            * MethodInvocationName,
+  OUT       AML_OBJECT_NODE         ** MethodInvocationNodePtr
+  );
+
+/** Get the number of arguments of a method invocation node.
+
+  This function also allow to identify whether a node is a method invocation
+  node. If the input node is not a method invocation node, just return.
+
+  @param  [in]  MethodInvocationNode  Method invocation node.
+  @param  [out] IsMethodInvocation    Boolean stating whether the input
+                                      node is a method invocation.
+  @param  [out] ArgCount              Number of arguments of the method
+                                      invocation.
+                                      Set to 0 if MethodInvocationNode
+                                      is not a method invocation.
+
+  @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
+AmlGetMethodInvocationArgCount (
+  IN  CONST AML_OBJECT_NODE   * MethodInvocationNode,
+  OUT       BOOLEAN           * IsMethodInvocation,
+  OUT       UINT8             * ArgCount
+  );
+
+#endif // AML_METHOD_PARSER_H_
-- 
'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'


  parent reply	other threads:[~2020-08-12 15:23 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-12 15:22 [PATCH v1 00/30] Add Dynamic AML generation support Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 01/30] DynamicTablesPkg: Introduction to Dynamic AML Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 02/30] DynamicTablesPkg: AmlLib definitions Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 03/30] DynamicTablesPkg: AML grammar definition Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 04/30] DynamicTablesPkg: AML node definitions Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 05/30] DynamicTablesPkg: AML tree interface Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 06/30] DynamicTablesPkg: AML tree enumerator Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 07/30] DynamicTablesPkg: AML tree traversal Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 08/30] DynamicTablesPkg: AML tree iterator Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 09/30] DynamicTablesPkg: AML tree/node cloning Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 10/30] DynamicTablesPkg: AML utility interfaces Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 11/30] DynamicTablesPkg: AML and ASL string helper Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 12/30] DynamicTablesPkg: AML stream interface Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 13/30] DynamicTablesPkg: AML serialise interface Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 14/30] DynamicTablesPkg: AML debug logging Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 15/30] DynamicTablesPkg: AML ACPI Namespace interface Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 16/30] DynamicTablesPkg: AML Parser Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 17/30] DynamicTablesPkg: AML resource data helper Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 18/30] DynamicTablesPkg: AML resource data parser Sami Mujawar
2020-08-12 15:22 ` Sami Mujawar [this message]
2020-08-12 15:22 ` [PATCH v1 20/30] DynamicTablesPkg: AML Field list parser Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 21/30] DynamicTablesPkg: AML Codegen Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 22/30] DynamicTablesPkg: AML Resource Data Codegen Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 23/30] DynamicTablesPkg: AML Core interface Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 24/30] DynamicTablesPkg: AmlLib APIs Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 25/30] DynamicTablesPkg: Dynamic AML: Add AmlLib library Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 26/30] DynamicTablesPkg: Add AsciiFromHex helper function Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 27/30] DynamicTablesPkg: SSDT Serial Port Fixup library Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 28/30] DynamicTablesPkg: SSDT Serial Port generator Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 29/30] DynamicTablesPkg: Add SSDT Serial port for SPCR Sami Mujawar
2020-08-12 15:22 ` [PATCH v1 30/30] DynamicTablesPkg: Add SSDT Serial port for DBG2 Sami Mujawar
2020-08-13 15:16 ` [edk2-devel] [PATCH v1 00/30] Add Dynamic AML generation support Alexei Fedorov

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200812152236.31164-20-sami.mujawar@arm.com \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox