DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeTraversal.h

   1 /** @file
   2   AML Tree Traversal.
   3
   4   Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7 **/
   8
   9 #ifndef AML_TREE_TRAVERSAL_H_
  10 #define AML_TREE_TRAVERSAL_H_
  11
  12 #include <AmlNodeDefines.h>
  13
  14 /** Get the next sibling node among the children of the input Node.
  15
  16   This function traverses the FixedArguments followed by the
  17   VariableArguments at the same level in the hierarchy.
  18
  19   Fixed arguments are before variable arguments.
  20
  21   (Node)        /-i           # Child of fixed argument b
  22       \        /
  23        |- [a][b][c][d]        # Fixed Arguments
  24        |- {(e)->(f)->(g)}     # Variable Arguments
  25              \
  26               \-h             # Child of variable argument e
  27
  28   Traversal Order: a, b, c, d, e, f, g, NULL
  29
  30
  31   @param  [in]  Node        Pointer to a root node or an object node.
  32   @param  [in]  ChildNode   Get the node after the ChildNode.
  33
  34   @return The node after the ChildNode among the children of the input Node.
  35            - If ChildNode is NULL, return the first available node among
  36              the fixed argument list then variable list of arguments;
  37            - If ChildNode is the last node of the fixed argument list,
  38              return the first argument of the variable list of arguments;
  39            - If ChildNode is the last node of the variable list of arguments,
  40              return NULL.
  41
  42 **/
  43 AML_NODE_HEADER *
  44 EFIAPI
  45 AmlGetNextSibling (
  46   IN  CONST AML_NODE_HEADER  *Node,
  47   IN  CONST AML_NODE_HEADER  *ChildNode
  48   );
  49
  50 /** Get the previous sibling node among the children of the input Node.
  51
  52   This function traverses the FixedArguments followed by the
  53   VariableArguments at the same level in the hierarchy.
  54
  55   Fixed arguments are before variable arguments.
  56
  57   (Node)        /-i           # Child of fixed argument b
  58       \        /
  59        |- [a][b][c][d]        # Fixed Arguments
  60        |- {(e)->(f)->(g)}     # Variable Arguments
  61              \
  62               \-h             # Child of variable argument e
  63
  64   Traversal Order: g, f, e, d, c, b, a, NULL
  65
  66   @param  [in]  Node        The node to get the fixed argument from.
  67   @param  [in]  ChildNode   Get the node before the ChildNode.
  68
  69   @return The node before the ChildNode among the children of the input Node.
  70            - If ChildNode is NULL, return the last available node among
  71              the variable list of arguments then fixed argument list;
  72            - If ChildNode is the first node of the variable list of arguments,
  73              return the last argument of the fixed argument list;
  74            - If ChildNode is the first node of the fixed argument list,
  75              return NULL.
  76 **/
  77 AML_NODE_HEADER *
  78 EFIAPI
  79 AmlGetPreviousSibling (
  80   IN  CONST  AML_NODE_HEADER  *Node,
  81   IN  CONST  AML_NODE_HEADER  *ChildNode
  82   );
  83
  84 /** Iterate through the nodes in the same order as the AML bytestream.
  85
  86   The iteration is similar to a depth-first path.
  87
  88   (Node)        /-i           # Child of fixed argument b
  89       \        /
  90        |- [a][b][c][d]        # Fixed Arguments
  91        |- {(e)->(f)->(g)}     # Variable Arguments
  92              \
  93               \-h             # Child of variable argument e
  94
  95   Traversal Order: a, b, i, c, d, e, h, f, g, NULL
  96   Note: The branch i and h will be traversed if it has any children.
  97
  98   @param  [in]  Node  Pointer to a node.
  99
 100   @return The next node in the AML bytestream order.
 101           Return NULL if Node is the Node corresponding to the last
 102           bytecode of the tree.
 103 **/
 104 AML_NODE_HEADER *
 105 EFIAPI
 106 AmlGetNextNode (
 107   IN  CONST AML_NODE_HEADER  *Node
 108   );
 109
 110 /** Iterate through the nodes in the reverse order of the AML bytestream.
 111
 112   The iteration is similar to a depth-first path,
 113   but done in a reverse order.
 114
 115   (Node)        /-i           # Child of fixed argument b
 116       \        /
 117        |- [a][b][c][d]        # Fixed Arguments
 118        |- {(e)->(f)->(g)}     # Variable Arguments
 119              \
 120               \-h             # Child of variable argument e
 121
 122   Traversal Order: g, f, h, e, d, c, i, b, a, NULL
 123   Note: The branch i and h will be traversed if it has any children.
 124
 125   @param  [in]  Node  Pointer to a node.
 126
 127   @return The previous node in the AML bytestream order.
 128           Return NULL if Node is the Node corresponding to the last
 129           bytecode of the tree.
 130 **/
 131 AML_NODE_HEADER *
 132 EFIAPI
 133 AmlGetPreviousNode (
 134   IN  CONST  AML_NODE_HEADER  *Node
 135   );
 136
 137 #endif // AML_TREE_TRAVERSAL_H_