--- /dev/null
+/** @file\r
+ AML Core Interface.\r
+\r
+ Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>\r
+\r
+ SPDX-License-Identifier: BSD-2-Clause-Patent\r
+**/\r
+\r
+#ifndef AML_CORE_INTERFACE_H_\r
+#define AML_CORE_INTERFACE_H_\r
+\r
+/* This header file does not include internal Node definition,\r
+ i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. The node definitions\r
+ must be included by the caller file. The function prototypes must\r
+ only expose AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE, etc. node\r
+ definitions.\r
+ This allows to keep the functions defined here both internal and\r
+ potentially external. If necessary, any function of this file can\r
+ be exposed externally.\r
+ The Api folder is internal to the AmlLib, but should only use these\r
+ functions. They provide a "safe" way to interact with the AmlLib.\r
+*/\r
+\r
+#include <AmlDefines.h>\r
+#include <Include/Library/AmlLib/AmlLib.h>\r
+#include <ResourceData/AmlResourceData.h>\r
+\r
+/**\r
+ @defgroup CoreApis Core APIs\r
+ @ingroup AMLLib\r
+ @{\r
+ Core APIs are the main APIs of the library. They allow to:\r
+ - Create an AML tree;\r
+ - Delete an AML tree;\r
+ - Clone an AML tree/node;\r
+ - Serialize an AML tree (convert the tree to a DSDT/SSDT table).\r
+ @}\r
+*/\r
+\r
+/** Serialize a tree to create a DSDT/SSDT table.\r
+\r
+ If:\r
+ - the content of BufferSize is >= to the size needed to serialize the\r
+ definition block;\r
+ - Buffer is not NULL;\r
+ first serialize the ACPI DSDT/SSDT header from the root node,\r
+ then serialize the AML blob from the rest of the tree.\r
+\r
+ The content of BufferSize is always updated to the size needed to\r
+ serialize the definition block.\r
+\r
+ @ingroup CoreApis\r
+\r
+ @param [in] RootNode Pointer to a root node.\r
+ @param [in] Buffer Buffer to write the DSDT/SSDT table to.\r
+ If Buffer is NULL, the size needed to\r
+ serialize the DSDT/SSDT table is returned\r
+ in BufferSize.\r
+ @param [in, out] BufferSize Pointer holding the size of the Buffer.\r
+ Its content is always updated to the size\r
+ needed to serialize the DSDT/SSDT table.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlSerializeTree (\r
+ IN AML_ROOT_NODE_HANDLE RootNode,\r
+ IN UINT8 * Buffer, OPTIONAL\r
+ IN OUT UINT32 * BufferSize\r
+ );\r
+\r
+/** Clone a node.\r
+\r
+ This function does not clone the children nodes.\r
+ The cloned node returned is not attached to any tree.\r
+\r
+ @ingroup CoreApis\r
+\r
+ @param [in] Node Pointer to a node.\r
+ @param [out] ClonedNode Pointer holding the cloned node.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+ @retval EFI_OUT_OF_RESOURCES Could not allocate memory.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlCloneNode (\r
+ IN AML_NODE_HANDLE Node,\r
+ OUT AML_NODE_HANDLE * ClonedNode\r
+ );\r
+\r
+/**\r
+ @defgroup TreeModificationApis Tree modification APIs\r
+ @ingroup AMLLib\r
+ @{\r
+ Tree modification APIs allow to add/remove/replace nodes that are in a\r
+ variable list of arguments.\r
+\r
+ No interface is provided to add/remove/replace nodes that are in a fixed\r
+ list of arguments. Indeed, these nodes are the spine of the tree and a\r
+ mismanipulation would make the tree inconsistent.\r
+\r
+ It is however possible to modify the content of fixed argument nodes via\r
+ @ref NodeInterfaceApis APIs.\r
+ @}\r
+*/\r
+\r
+/** Remove the Node from its parent's variable list of arguments.\r
+\r
+ The function will fail if the Node is in its parent's fixed\r
+ argument list.\r
+ The Node is not deleted. The deletion is done separately\r
+ from the removal.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] Node Pointer to a Node.\r
+ Must be a data node or an object node.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlRemoveNodeFromVarArgList (\r
+ IN AML_NODE_HANDLE Node\r
+ );\r
+\r
+/** Add the NewNode to the head of the variable list of arguments\r
+ of the ParentNode.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] ParentNode Pointer to the parent node.\r
+ Must be a root or an object node.\r
+ @param [in] NewNode Pointer to the node to add.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlVarListAddHead (\r
+ IN AML_NODE_HANDLE ParentNode,\r
+ IN AML_NODE_HANDLE NewNode\r
+ );\r
+\r
+/** Add the NewNode to the tail of the variable list of arguments\r
+ of the ParentNode.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] ParentNode Pointer to the parent node.\r
+ Must be a root or an object node.\r
+ @param [in] NewNode Pointer to the node to add.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlVarListAddTail (\r
+ IN AML_NODE_HANDLE ParentNode,\r
+ IN AML_NODE_HANDLE NewNode\r
+ );\r
+\r
+/** Add the NewNode before the Node in the list of variable\r
+ arguments of the Node's parent.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] Node Pointer to a node.\r
+ Must be a root or an object node.\r
+ @param [in] NewNode Pointer to the node to add.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlVarListAddBefore (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN AML_NODE_HANDLE NewNode\r
+ );\r
+\r
+/** Add the NewNode after the Node in the variable list of arguments\r
+ of the Node's parent.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] Node Pointer to a node.\r
+ Must be a root or an object node.\r
+ @param [in] NewNode Pointer to the node to add.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlVarListAddAfter (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN AML_NODE_HANDLE NewNode\r
+ );\r
+\r
+/** Append a Resource Data node to the BufferOpNode.\r
+\r
+ The Resource Data node is added at the end of the variable\r
+ list of arguments of the BufferOpNode, but before the End Tag.\r
+ If no End Tag is found, the function returns an error.\r
+\r
+ @param [in] BufferOpNode Buffer node containing resource data elements.\r
+ @param [in] NewRdNode The new Resource Data node to add.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlAppendRdNode (\r
+ IN AML_OBJECT_NODE_HANDLE BufferOpNode,\r
+ IN AML_DATA_NODE_HANDLE NewRdNode\r
+ );\r
+\r
+/** Replace the OldNode, which is in a variable list of arguments,\r
+ with the NewNode.\r
+\r
+ Note: This function unlinks the OldNode from the tree. It is the callers\r
+ responsibility to delete the OldNode if needed.\r
+\r
+ @ingroup TreeModificationApis\r
+\r
+ @param [in] OldNode Pointer to the node to replace.\r
+ Must be a data node or an object node.\r
+ @param [in] NewNode The new node to insert.\r
+ Must be a data node or an object node.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlReplaceVariableArgument (\r
+ IN AML_NODE_HANDLE OldNode,\r
+ IN AML_NODE_HANDLE NewNode\r
+ );\r
+\r
+/**\r
+ @defgroup NodeInterfaceApis Node Interface APIs\r
+ @ingroup AMLLib\r
+ @{\r
+ Node Interface APIs allow to query information from a node. Some functions\r
+ expect a specific node type among the root/object/data node types.\r
+\r
+ For instance, AmlGetRootNodeInfo expects to receive a root node.\r
+\r
+ E.g.: Query the node type, the ACPI header stored in the root node,\r
+ the OpCode/SubOpCode/PkgLen of an object node, the type of data\r
+ stored in a data node, etc.\r
+\r
+ These APIs also allow to update some information.\r
+\r
+ E.g.: The ACPI header stored in the root node, the buffer of a data node.\r
+\r
+ The information of object nodes and the data type of data nodes cannot be\r
+ modified. This prevents the creation of an inconsistent tree.\r
+\r
+ It is however possible to remove a node from a variable list of arguments\r
+ and replace it. Use the @ref TreeModificationApis APIs for this.\r
+ @}\r
+*/\r
+\r
+/** Returns the tree node type (Root/Object/Data).\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] Node Pointer to a Node.\r
+\r
+ @return The node type.\r
+ EAmlNodeUnknown if invalid parameter.\r
+**/\r
+EAML_NODE_TYPE\r
+EFIAPI\r
+AmlGetNodeType (\r
+ IN AML_NODE_HANDLE Node\r
+ );\r
+\r
+/** Get the RootNode information.\r
+ The Node must be a root node.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] RootNode Pointer to a root node.\r
+ @param [out] SdtHeaderBuffer Buffer to copy the ACPI DSDT/SSDT header to.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetRootNodeInfo (\r
+ IN AML_ROOT_NODE_HANDLE RootNode,\r
+ OUT EFI_ACPI_DESCRIPTION_HEADER * SdtHeaderBuffer\r
+ );\r
+\r
+/** Get the ObjectNode information.\r
+ The Node must be an object node.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] ObjectNode Pointer to an object node.\r
+ @param [out] OpCode Pointer holding the OpCode.\r
+ Optional, can be NULL.\r
+ @param [out] SubOpCode Pointer holding the SubOpCode.\r
+ Optional, can be NULL.\r
+ @param [out] PkgLen Pointer holding the PkgLen.\r
+ The PkgLen is 0 for nodes\r
+ not having the Pkglen attribute.\r
+ Optional, can be NULL.\r
+ @param [out] IsNameSpaceNode Pointer holding TRUE if the node is defining\r
+ or changing the NameSpace scope.\r
+ E.g.: The "Name ()" and "Scope ()" ASL\r
+ statements add/modify the NameSpace scope.\r
+ Their corresponding node are NameSpace nodes.\r
+ Optional, can be NULL.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetObjectNodeInfo (\r
+ IN AML_OBJECT_NODE_HANDLE ObjectNode,\r
+ OUT UINT8 * OpCode, OPTIONAL\r
+ OUT UINT8 * SubOpCode, OPTIONAL\r
+ OUT UINT32 * PkgLen, OPTIONAL\r
+ OUT BOOLEAN * IsNameSpaceNode OPTIONAL\r
+ );\r
+\r
+/** Returns the count of the fixed arguments for the input Node.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] Node Pointer to an object node.\r
+\r
+ @return Number of fixed arguments of the object node.\r
+ Return 0 if the node is not an object node.\r
+**/\r
+UINT8\r
+AmlGetFixedArgumentCount (\r
+ IN AML_OBJECT_NODE_HANDLE Node\r
+ );\r
+\r
+/** Get the data type of the DataNode.\r
+ The Node must be a data node.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] DataNode Pointer to a data node.\r
+ @param [out] DataType Pointer holding the data type of the data buffer.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetNodeDataType (\r
+ IN AML_DATA_NODE_HANDLE DataNode,\r
+ OUT EAML_NODE_DATA_TYPE * DataType\r
+ );\r
+\r
+/** Get the descriptor Id of the resource data element\r
+ contained in the DataNode.\r
+\r
+ The Node must be a data node.\r
+ The Node must have the resource data type, i.e. have the\r
+ EAmlNodeDataTypeResourceData data type.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] DataNode Pointer to a data node containing a\r
+ resource data element.\r
+ @param [out] ResourceDataType Pointer holding the descriptor Id of\r
+ the resource data.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetResourceDataType (\r
+ IN AML_DATA_NODE_HANDLE DataNode,\r
+ OUT AML_RD_HEADER * ResourceDataType\r
+ );\r
+\r
+/** Get the data buffer and size of the DataNode.\r
+ The Node must be a data node.\r
+\r
+ BufferSize is always updated to the size of buffer of the DataNode.\r
+\r
+ If:\r
+ - the content of BufferSize is >= to the DataNode's buffer size;\r
+ - Buffer is not NULL;\r
+ then copy the content of the DataNode's buffer in Buffer.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] DataNode Pointer to a data node.\r
+ @param [out] Buffer Buffer to write the data to.\r
+ Optional, if NULL, only update BufferSize.\r
+ @param [in, out] BufferSize Pointer holding:\r
+ - At entry, the size of the Buffer;\r
+ - At exit, the size of the DataNode's\r
+ buffer size.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetDataNodeBuffer (\r
+ IN AML_DATA_NODE_HANDLE DataNode,\r
+ OUT UINT8 * Buffer, OPTIONAL\r
+ IN OUT UINT32 * BufferSize\r
+ );\r
+\r
+/** Update the ACPI DSDT/SSDT table header.\r
+\r
+ The input SdtHeader information is copied to the tree RootNode.\r
+ The table Length field is automatically updated.\r
+ The checksum field is only updated when serializing the tree.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] RootNode Pointer to a root node.\r
+ @param [in] SdtHeader Pointer to an ACPI DSDT/SSDT table header.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlUpdateRootNode (\r
+ IN AML_ROOT_NODE_HANDLE RootNode,\r
+ IN CONST EFI_ACPI_DESCRIPTION_HEADER * SdtHeader\r
+ );\r
+\r
+/** Update an object node representing an integer with a new value.\r
+\r
+ The object node must have one of the following OpCodes:\r
+ - AML_BYTE_PREFIX\r
+ - AML_WORD_PREFIX\r
+ - AML_DWORD_PREFIX\r
+ - AML_QWORD_PREFIX\r
+ - AML_ZERO_OP\r
+ - AML_ONE_OP\r
+\r
+ The following OpCode is not supported:\r
+ - AML_ONES_OP\r
+\r
+ @param [in] IntegerOpNode Pointer an object node containing an integer.\r
+ Must not be an object node with an AML_ONES_OP\r
+ OpCode.\r
+ @param [in] NewInteger New integer value to set.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlUpdateInteger (\r
+ IN AML_OBJECT_NODE_HANDLE IntegerOpNode,\r
+ IN UINT64 NewInteger\r
+ );\r
+\r
+/** Update the buffer of a data node.\r
+\r
+ Note: The data type of the buffer's content must match the data type of the\r
+ DataNode. This is a hard restriction to prevent undesired behaviour.\r
+\r
+ @ingroup NodeInterfaceApis\r
+\r
+ @param [in] DataNode Pointer to a data node.\r
+ @param [in] DataType Data type of the Buffer's content.\r
+ @param [in] Buffer Buffer containing the new data. The content of\r
+ the Buffer is copied.\r
+ @param [in] Size Size of the Buffer.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+ @retval EFI_UNSUPPORTED Operation not supporter.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlUpdateDataNode (\r
+ IN AML_DATA_NODE_HANDLE DataNode,\r
+ IN EAML_NODE_DATA_TYPE DataType,\r
+ IN UINT8 * Buffer,\r
+ IN UINT32 Size\r
+ );\r
+\r
+/**\r
+ @defgroup NavigationApis Navigation APIs\r
+ @ingroup AMLLib\r
+ @{\r
+ Navigation APIs allow to navigate in the AML tree. There are different\r
+ ways to navigate in the tree by:\r
+ - Direct relation (@ref CoreNavigationApis);\r
+ - Enumeration: enumerate all the nodes and call a callback function\r
+ (@ref EnumerationApis);\r
+ - Iteration: instantiate an iterator and use it to navigate\r
+ (@ref IteratorApis);\r
+ - NameSpace path: use the AML namespace to navigate the tree\r
+ (@ref NameSpaceApis).\r
+ @}\r
+*/\r
+\r
+/**\r
+ @defgroup CoreNavigationApis Core Navigation APIs\r
+ @ingroup NavigationApis\r
+ @{\r
+ Core Navigation APIs allow to get a node by specifying a relation.\r
+\r
+ E.g.: Get the parent, the n-th fixed argument, the next variable\r
+ argument, etc.\r
+ @}\r
+*/\r
+\r
+/** Get the parent node of the input Node.\r
+\r
+ @ingroup CoreNavigationApis\r
+\r
+ @param [in] Node Pointer to a node.\r
+\r
+ @return The parent node of the input Node.\r
+ NULL otherwise.\r
+**/\r
+AML_NODE_HANDLE\r
+EFIAPI\r
+AmlGetParent (\r
+ IN AML_NODE_HANDLE Node\r
+ );\r
+\r
+/** Get the node at the input Index in the fixed argument list of the input\r
+ ObjectNode.\r
+\r
+ @ingroup CoreNavigationApis\r
+\r
+ @param [in] ObjectNode Pointer to an object node.\r
+ @param [in] Index The Index of the fixed argument to get.\r
+\r
+ @return The node at the input Index in the fixed argument list\r
+ of the input ObjectNode.\r
+ NULL otherwise, e.g. if the node is not an object node, or no\r
+ node is available at this Index.\r
+**/\r
+AML_NODE_HANDLE\r
+EFIAPI\r
+AmlGetFixedArgument (\r
+ IN AML_OBJECT_NODE_HANDLE ObjectNode,\r
+ IN EAML_PARSE_INDEX Index\r
+ );\r
+\r
+/** Get the sibling node among the nodes being in\r
+ the same variable argument list.\r
+\r
+ (ParentNode) /-i # Child of fixed argument b\r
+ \ /\r
+ |- [a][b][c][d] # Fixed Arguments\r
+ |- {(VarArgNode)->(f)->(g)} # Variable Arguments\r
+ \\r
+ \-h # Child of variable argument e\r
+\r
+ Node must be in a variable list of arguments.\r
+ Traversal Order: VarArgNode, f, g, NULL\r
+\r
+ @ingroup CoreNavigationApis\r
+\r
+ @param [in] VarArgNode Pointer to a node.\r
+ Must be in a variable list of arguments.\r
+\r
+ @return The next node after VarArgNode in the variable list of arguments.\r
+ Return NULL if\r
+ - VarArgNode is the last node of the list, or\r
+ - VarArgNode is not part of a variable list of arguments.\r
+**/\r
+AML_NODE_HANDLE\r
+EFIAPI\r
+AmlGetSiblingVariableArgument (\r
+ IN AML_NODE_HANDLE VarArgNode\r
+ );\r
+\r
+/** Get the next variable argument.\r
+\r
+ (Node) /-i # Child of fixed argument b\r
+ \ /\r
+ |- [a][b][c][d] # Fixed Arguments\r
+ |- {(e)->(f)->(g)} # Variable Arguments\r
+ \\r
+ \-h # Child of variable argument e\r
+\r
+ Traversal Order: e, f, g, NULL\r
+\r
+ @ingroup CoreNavigationApis\r
+\r
+ @param [in] Node Pointer to a Root node or Object Node.\r
+ @param [in] CurrVarArg Pointer to the Current Variable Argument.\r
+\r
+ @return The node after the CurrVarArg in the variable list of arguments.\r
+ If CurrVarArg is NULL, return the first node of the\r
+ variable argument list.\r
+ Return NULL if\r
+ - CurrVarArg is the last node of the list, or\r
+ - Node does not have a variable list of arguments.\r
+**/\r
+AML_NODE_HANDLE\r
+EFIAPI\r
+AmlGetNextVariableArgument (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN AML_NODE_HANDLE CurrVarArg\r
+ );\r
+\r
+/** Get the previous variable argument.\r
+\r
+ (Node) /-i # Child of fixed argument b\r
+ \ /\r
+ |- [a][b][c][d] # Fixed Arguments\r
+ |- {(e)->(f)->(g)} # Variable Arguments\r
+ \\r
+ \-h # Child of variable argument e\r
+\r
+ Traversal Order: g, f, e, NULL\r
+\r
+ @ingroup CoreNavigationApis\r
+\r
+ @param [in] Node Pointer to a root node or an object node.\r
+ @param [in] CurrVarArg Pointer to the Current Variable Argument.\r
+\r
+ @return The node before the CurrVarArg in the variable list of\r
+ arguments.\r
+ If CurrVarArg is NULL, return the last node of the\r
+ variable list of arguments.\r
+ Return NULL if:\r
+ - CurrVarArg is the first node of the list, or\r
+ - Node doesn't have a variable list of arguments.\r
+**/\r
+AML_NODE_HANDLE\r
+EFIAPI\r
+AmlGetPreviousVariableArgument (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN AML_NODE_HANDLE CurrVarArg\r
+ );\r
+\r
+/**\r
+ @defgroup EnumerationApis Enumeration APIs\r
+ @ingroup NavigationApis\r
+ @{\r
+ Enumeration APIs are navigation APIs, allowing to call a callback function\r
+ on each node enumerated. Nodes are enumerated in the AML bytestream order,\r
+ i.e. in a depth first order.\r
+ @}\r
+*/\r
+\r
+/**\r
+ Callback function prototype used when iterating through the tree.\r
+\r
+ @ingroup EnumerationApis\r
+\r
+ @param [in] Node The Node currently being processed.\r
+ @param [in, out] Context A context for the callback function.\r
+ Can be optional.\r
+ @param [in, out] Status End the enumeration if pointing to a value\r
+ evaluated to TRUE.\r
+ Can be optional.\r
+\r
+ @retval TRUE if the enumeration can continue or has finished without\r
+ interruption.\r
+ @retval FALSE if the enumeration needs to stopped or has stopped.\r
+**/\r
+typedef\r
+BOOLEAN\r
+(EFIAPI * EDKII_AML_TREE_ENUM_CALLBACK) (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN OUT VOID * Context, OPTIONAL\r
+ IN OUT EFI_STATUS * Status OPTIONAL\r
+ );\r
+\r
+/** Enumerate all nodes of the subtree under the input Node in the AML\r
+ bytestream order (i.e. in a depth first order), and call the CallBack\r
+ function with the input Context.\r
+ The prototype of the Callback function is EDKII_AML_TREE_ENUM_CALLBACK.\r
+\r
+ @ingroup EnumerationApis\r
+\r
+ @param [in] Node Enumerate nodes of the subtree under this Node.\r
+ Must be a valid node.\r
+ @param [in] CallBack Callback function to call on each node.\r
+ @param [in, out] Context Void pointer used to pass some information\r
+ to the Callback function.\r
+ Optional, can be NULL.\r
+ @param [out] Status Optional parameter that can be used to get\r
+ the status of the Callback function.\r
+ If used, need to be init to EFI_SUCCESS.\r
+\r
+ @retval TRUE if the enumeration can continue or has finished without\r
+ interruption.\r
+ @retval FALSE if the enumeration needs to stopped or has stopped.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+AmlEnumTree (\r
+ IN AML_NODE_HANDLE Node,\r
+ IN EDKII_AML_TREE_ENUM_CALLBACK CallBack,\r
+ IN OUT VOID * Context, OPTIONAL\r
+ OUT EFI_STATUS * Status OPTIONAL\r
+ );\r
+\r
+/**\r
+ @defgroup NameSpaceApis NameSpace APIs\r
+ @ingroup NavigationApis\r
+ @{\r
+ NameSpace APIs allow to find a node from an AML path, and reciprocally\r
+ get the AML path of a node.\r
+\r
+ These APIs only operate on "NameSpace nodes", i.e. nodes that are\r
+ part of the AML namespace. These are the root node and object nodes\r
+ acknowledged by AmlGetObjectNodeInfo in @ref NodeInterfaceApis.\r
+ @}\r
+*/\r
+\r
+/** Build the absolute ASL pathname to Node.\r
+\r
+ BufferSize is always updated to the size of the pathname.\r
+\r
+ If:\r
+ - the content of BufferSize is >= to the size of the pathname AND;\r
+ - Buffer is not NULL;\r
+ then copy the pathname in the Buffer. A buffer of the size\r
+ MAX_ASL_NAMESTRING_SIZE is big enough to receive any ASL pathname.\r
+\r
+ @ingroup NameSpaceApis\r
+\r
+ @param [in] Node Node to build the absolute path to.\r
+ Must be a root node, or a namespace node.\r
+ @param [out] Buffer Buffer to write the path to.\r
+ If NULL, only update *BufferSize.\r
+ @param [in, out] BufferSize Pointer holding:\r
+ - At entry, the size of the Buffer;\r
+ - At exit, the size of the pathname.\r
+\r
+ @retval EFI_SUCCESS The function completed successfully.\r
+ @retval EFI_BUFFER_TOO_SMALL No space left in the buffer.\r
+ @retval EFI_INVALID_PARAMETER Invalid parameter.\r
+ @retval EFI_OUT_OF_RESOURCES Out of memory.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+AmlGetAslPathName (\r
+ IN AML_NODE_HANDLE Node,\r
+ OUT CHAR8 * Buffer,\r
+ IN OUT UINT32 * BufferSize\r
+ );\r
+\r
+#endif // AML_CORE_INTERFACE_H_\r
projects / mirror_edk2.git / commitdiff