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

   1 /** @file
   2   AML Tree.
   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_H_
  10 #define AML_TREE_H_
  11
  12 #include <AmlNodeDefines.h>
  13
  14 /** Get the root node from any node of the tree.
  15     This is done by climbing up the tree until the root node is reached.
  16
  17   @param  [in]  Node    Pointer to a node.
  18
  19   @return The root node of the tree.
  20           NULL if error.
  21 */
  22 AML_ROOT_NODE *
  23 EFIAPI
  24 AmlGetRootNode (
  25   IN  CONST AML_NODE_HEADER   * Node
  26   );
  27
  28 /** Check whether the input Node is in the fixed argument list of its parent
  29     node.
  30
  31   If so, IndexPtr contains this Index.
  32
  33   @param  [in]  Node          Pointer to a Node.
  34   @param  [out] IndexPtr      Pointer holding the Index of the Node in
  35                               its parent's fixed argument list.
  36
  37   @retval TRUE   The node is a fixed argument and the index
  38                  in IndexPtr is valid.
  39   @retval FALSE  The node is not a fixed argument.
  40 **/
  41 BOOLEAN
  42 EFIAPI
  43 AmlIsNodeFixedArgument (
  44   IN  CONST  AML_NODE_HEADER     * Node,
  45   OUT        EAML_PARSE_INDEX    * IndexPtr
  46   );
  47
  48 /** Set the fixed argument of the ObjectNode at the Index to the NewNode.
  49
  50   It is the caller's responsibility to save the old node, if desired,
  51   otherwise the reference to the old node will be lost.
  52   If NewNode is not NULL, set its parent to ObjectNode.
  53
  54   @param  [in]  ObjectNode    Pointer to an object node.
  55   @param  [in]  Index         Index in the fixed argument list of
  56                               the ObjectNode to set.
  57   @param  [in]  NewNode       Pointer to the NewNode.
  58                               Can be NULL, a data node or an object node.
  59
  60   @retval EFI_SUCCESS             The function completed successfully.
  61   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  62 **/
  63 EFI_STATUS
  64 EFIAPI
  65 AmlSetFixedArgument (
  66   IN  AML_OBJECT_NODE   * ObjectNode,
  67   IN  EAML_PARSE_INDEX    Index,
  68   IN  AML_NODE_HEADER   * NewNode
  69   );
  70
  71 /** If the given AML_NODE_HEADER has a variable list of arguments,
  72     return a pointer to this list.
  73     Return NULL otherwise.
  74
  75   @param  [in]  Node  Pointer to the AML_NODE_HEADER to check.
  76
  77   @return The list of variable arguments if there is one.
  78           NULL otherwise.
  79 **/
  80 LIST_ENTRY *
  81 EFIAPI
  82 AmlNodeGetVariableArgList (
  83   IN  CONST AML_NODE_HEADER   * Node
  84   );
  85
  86 /** Add the NewNode to the tail of the variable list of arguments
  87     of the ParentNode.
  88
  89   NOTE: This is an internal function which does not propagate the size
  90         when a new node is added.
  91
  92   @param  [in]  ParentNode  Pointer to the parent node.
  93                             Must be a root or an object node.
  94   @param  [in]  NewNode     Pointer to the node to add.
  95
  96   @retval EFI_SUCCESS             The function completed successfully.
  97   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  98 **/
  99 EFI_STATUS
 100 EFIAPI
 101 AmlVarListAddTailInternal (
 102   IN  AML_NODE_HEADER  * ParentNode,
 103   IN  AML_NODE_HEADER  * NewNode
 104   );
 105
 106 /** Replace the OldNode by the NewNode.
 107
 108   Note: This function unlinks the OldNode from the tree. It is the callers
 109         responsibility to delete the OldNode if needed.
 110
 111   @param  [in]  OldNode   Pointer to the node to replace.
 112                           Must be a data node or an object node.
 113   @param  [in]  NewNode   The new node to insert.
 114                           Must be a data node or an object node.
 115
 116   @retval EFI_SUCCESS             The function completed successfully.
 117   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 AmlReplaceArgument (
 122   IN  AML_NODE_HEADER   * OldNode,
 123   IN  AML_NODE_HEADER   * NewNode
 124   );
 125
 126 #endif // AML_TREE_H_
 127