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

   1 /** @file
   2   AML Node.
   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_NODE_H_
  10 #define AML_NODE_H_
  11
  12 #include <AmlNodeDefines.h>
  13 #include <IndustryStandard/Acpi.h>
  14
  15 /** Create an AML_ROOT_NODE.
  16     This node will be the root of the tree.
  17
  18   @param  [in]  SdtHeader       Pointer to an ACPI DSDT/SSDT header to copy
  19                                 the data from.
  20   @param  [out] NewRootNodePtr  If success, contains the created
  21                                 AML_ROOT_NODE.
  22                                 Otherwise reset to NULL.
  23
  24   @retval EFI_SUCCESS             The function completed successfully.
  25   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  26   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  27 **/
  28 EFI_STATUS
  29 EFIAPI
  30 AmlCreateRootNode (
  31   IN  CONST EFI_ACPI_DESCRIPTION_HEADER   * SdtHeader,
  32   OUT       AML_ROOT_NODE                ** NewRootNodePtr
  33   );
  34
  35 /** Create an AML_OBJECT_NODE.
  36
  37   @param  [in]  AmlByteEncoding   Byte encoding entry.
  38   @param  [in]  PkgLength         PkgLength of the node if the AmlByteEncoding
  39                                   has the PkgLen attribute.
  40                                   0 otherwise.
  41   @param  [out] NewObjectNodePtr  If success, contains the created
  42                                   AML_OBJECT_NODE.
  43                                   Otherwise reset to NULL.
  44
  45   @retval EFI_SUCCESS             The function completed successfully.
  46   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  47   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  48 **/
  49 EFI_STATUS
  50 EFIAPI
  51 AmlCreateObjectNode (
  52   IN  CONST  AML_BYTE_ENCODING   * AmlByteEncoding,
  53   IN         UINT32                PkgLength,
  54   OUT        AML_OBJECT_NODE    ** NewObjectNodePtr
  55   );
  56
  57 /** Create an AML_DATA_NODE.
  58
  59   @param  [in]  DataType        DataType of the node.
  60   @param  [in]  Data            Pointer to the AML bytecode corresponding to
  61                                 this node. Data is copied from there.
  62   @param  [in]  DataSize        Number of bytes to consider at the address
  63                                 pointed by Data.
  64   @param  [out] NewDataNodePtr  If success, contains the created
  65                                 AML_DATA_NODE.
  66                                 Otherwise reset to NULL.
  67
  68   @retval EFI_SUCCESS             The function completed successfully.
  69   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  70   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory.
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 AmlCreateDataNode (
  75   IN        EAML_NODE_DATA_TYPE     DataType,
  76   IN  CONST UINT8                 * Data,
  77   IN        UINT32                  DataSize,
  78   OUT       AML_DATA_NODE        ** NewDataNodePtr
  79   );
  80
  81 /** Delete a Node.
  82
  83   @param  [in]  Node  Pointer to a Node.
  84
  85   @retval EFI_SUCCESS             The function completed successfully.
  86   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  87 **/
  88 EFI_STATUS
  89 EFIAPI
  90 AmlDeleteNode (
  91   IN  AML_NODE_HEADER   * Node
  92   );
  93
  94 /** Check whether ObjectNode has the input attribute.
  95     This function can be used to check ObjectNode is an object node
  96     at the same time.
  97
  98   @param  [in]  ObjectNode  Pointer to an object node.
  99   @param  [in]  Attribute   Attribute to check for.
 100
 101   @retval TRUE    The node is an AML object and the attribute is present.
 102   @retval FALSE   Otherwise.
 103 **/
 104 BOOLEAN
 105 EFIAPI
 106 AmlNodeHasAttribute (
 107   IN  CONST AML_OBJECT_NODE   * ObjectNode,
 108   IN        AML_OP_ATTRIBUTE    Attribute
 109   );
 110
 111 /** Check whether ObjectNode has the input OpCode/SubOpcode couple.
 112
 113   @param  [in]  ObjectNode  Pointer to an object node.
 114   @param  [in]  OpCode      OpCode to check
 115   @param  [in]  SubOpCode   SubOpCode to check
 116
 117   @retval TRUE    The node is an AML object and
 118                   the Opcode and the SubOpCode match.
 119   @retval FALSE   Otherwise.
 120 **/
 121 BOOLEAN
 122 EFIAPI
 123 AmlNodeCompareOpCode (
 124   IN  CONST  AML_OBJECT_NODE  * ObjectNode,
 125   IN         UINT8              OpCode,
 126   IN         UINT8              SubOpCode
 127   );
 128
 129 /** Check whether a Node is an integer node.
 130
 131   By integer node we mean an object node having one of the following opcode:
 132    - AML_BYTE_PREFIX;
 133    - AML_WORD_PREFIX;
 134    - AML_DWORD_PREFIX;
 135    - AML_QWORD_PREFIX.
 136
 137   @param  [in]  Node  The node to check.
 138
 139   @retval TRUE  The Node is an integer node.
 140   @retval FALSE Otherwise.
 141 */
 142 BOOLEAN
 143 EFIAPI
 144 IsIntegerNode (
 145   IN  AML_OBJECT_NODE   * Node
 146   );
 147
 148 /** Check whether a Node is a ZeroOp, a OneOp or a OnesOp.
 149
 150   These two objects don't have a data node holding
 151   a value. This require special handling.
 152
 153   @param  [in]  Node  The node to check.
 154
 155   @retval TRUE  The Node is a ZeroOp or OneOp.
 156   @retval FALSE Otherwise.
 157 */
 158 BOOLEAN
 159 EFIAPI
 160 IsSpecialIntegerNode (
 161   IN  AML_OBJECT_NODE   * Node
 162   );
 163
 164 /** Check whether Node corresponds to a method definition.
 165
 166   A method definition can be introduced:
 167    - By a method object, having an AML_METHOD_OP OpCode;
 168    - By an external definition of a method, having an AML_EXTERNAL_OP OpCode
 169      and an ObjectType byte set to the MethodObj.
 170
 171   Note:
 172   An alias node, having an AML_ALIAS_OP, can be resolved to a method
 173   definition. This function doesn't handle this case.
 174
 175   @param [in] Node    Node to check whether it is a method definition.
 176
 177   @retval TRUE  The Node is a method definition.
 178   @retval FALSE Otherwise.
 179 **/
 180 BOOLEAN
 181 EFIAPI
 182 AmlIsMethodDefinitionNode (
 183   IN  CONST AML_OBJECT_NODE   * Node
 184   );
 185
 186 /** Get the index at which the name of the node is stored.
 187
 188   @param  [in]  ObjectNode  Pointer to an object node.
 189                             Must have the AML_IN_NAMESPACE attribute.
 190   @param  [out] Index       Index of the name in the fixed list of arguments.
 191
 192   @retval EFI_SUCCESS             The function completed successfully.
 193   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 194 **/
 195 EFI_STATUS
 196 AmlNodeGetNameIndex (
 197   IN  CONST AML_OBJECT_NODE     * ObjectNode,
 198   OUT       EAML_PARSE_INDEX    * Index
 199   );
 200
 201 /** Get the name of the Node.
 202
 203   Node must be part of the namespace.
 204
 205   @param [in] ObjectNode    Pointer to an object node,
 206                             which is part of the namespace.
 207
 208   @return A pointer to the name.
 209           NULL otherwise.
 210           Return NULL for the root node.
 211 **/
 212 CHAR8 *
 213 EFIAPI
 214 AmlNodeGetName (
 215   IN  CONST AML_OBJECT_NODE   * ObjectNode
 216   );
 217
 218 #endif // AML_NODE_H_