From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from EUR05-VI1-obe.outbound.protection.outlook.com (EUR05-VI1-obe.outbound.protection.outlook.com [40.107.21.52]) by mx.groups.io with SMTP id smtpd.web10.17205.1597245832052600315 for ; Wed, 12 Aug 2020 08:23:52 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=FdoTgtxk; spf=pass (domain: arm.com, ip: 40.107.21.52, mailfrom: sami.mujawar@arm.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=29pV7thJbUxPoAkG3V6m9MdVDuYUQn2zs8Mv/5DoBCE=; b=FdoTgtxksP8GYjtiaOgcw4ksJopQ1enqaqQ6dJDQ9Bap+CMIBIUfvchAac14y+uDYJtIEQoJmXn5zqmhr7J5tntkqQaueWkNyAV4HtOS3LysRAHf9K3rf7zvu8jGm1vSEotR1+hIPyHMpchJE9B2CXCdd6BZk1VP0R9zidfNJvY= Received: from AM0PR06CA0088.eurprd06.prod.outlook.com (2603:10a6:208:fa::29) by DB6PR0801MB1686.eurprd08.prod.outlook.com (2603:10a6:4:3b::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3261.19; Wed, 12 Aug 2020 15:23:48 +0000 Received: from AM5EUR03FT007.eop-EUR03.prod.protection.outlook.com (2603:10a6:208:fa:cafe::5b) by AM0PR06CA0088.outlook.office365.com (2603:10a6:208:fa::29) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.16 via Frontend Transport; Wed, 12 Aug 2020 15:23:48 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; edk2.groups.io; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;edk2.groups.io; dmarc=bestguesspass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by AM5EUR03FT007.mail.protection.outlook.com (10.152.16.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.16 via Frontend Transport; Wed, 12 Aug 2020 15:23:48 +0000 Received: ("Tessian outbound bac899b43a54:v64"); Wed, 12 Aug 2020 15:23:48 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: 7c723d2e6ba050ef X-CR-MTA-TID: 64aa7808 Received: from 170ed717c660.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 54C7F309-C496-4021-9E5A-D74C4EF34D28.1; Wed, 12 Aug 2020 15:23:42 +0000 Received: from EUR05-AM6-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 170ed717c660.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Wed, 12 Aug 2020 15:23:42 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=c6uY0rldUibZRT+Q/SS3ykxCMSFDofpLOpzjatIFy7AHjUhdvvnn79Jc6LwTbNgdXoKrpkS1lLusQECmrHOtaCHmlDf6MrxJ8wZ+L8hVsFxTtB76c4VBrCbchazpwPxC5MNe4qUyfp+z5GrL0DonIO9PCo/bKKiqiIH4VNgV6PrTcBoYK/LoOybJRQbHFkiIlyPIkKkDl/QOFwazgh6s9u+5RpahXK/QBtQ2v5JRG4OilOkVXrlWjR4qXH1/LZr1l0p7qMpWEN1SW/sHFVIk5vEGhUg9cGhjYqjCA3lQCzWuzBvHOAN1FfNO2zGKdQaarTpOInkDH8F4oNCekdVgjA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=29pV7thJbUxPoAkG3V6m9MdVDuYUQn2zs8Mv/5DoBCE=; b=KgXQsGsEx8GlQqyt0i80yx2uEDIM5rHlBgFEyOm8SwWMXewUN6c2pXhpUqqKWit5ulo9f2DJgHXWsN78XxB7GESZd3qb7wG0CoBTe8XobRc7xzAWZsdzutsT5T7ZEAJxrV0WyYcWu6LVT8lM6ygD+QrpYAWkGIvCXazq3Lyi3sJF/lFVMTuUwqEr6cZC1nVWVUr/pW311rWML+PZKBMTXDrgHaPbpf7kJ9oqfYpMjQ6W5Y7ZvH27Y1fKkTo9EDecRI0JoAWItWQcI0Oi7acfI0B/Y+HsfthayKiVVwuW+JpGFTgnCHw2gQ/oNUJtIykI3SkhqYIPhYl8lthxDHk2Vw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 40.67.248.234) smtp.rcpttodomain=edk2.groups.io smtp.mailfrom=arm.com; dmarc=bestguesspass action=none header.from=arm.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=29pV7thJbUxPoAkG3V6m9MdVDuYUQn2zs8Mv/5DoBCE=; b=FdoTgtxksP8GYjtiaOgcw4ksJopQ1enqaqQ6dJDQ9Bap+CMIBIUfvchAac14y+uDYJtIEQoJmXn5zqmhr7J5tntkqQaueWkNyAV4HtOS3LysRAHf9K3rf7zvu8jGm1vSEotR1+hIPyHMpchJE9B2CXCdd6BZk1VP0R9zidfNJvY= Received: from DB6PR07CA0062.eurprd07.prod.outlook.com (2603:10a6:6:2a::24) by DB7PR08MB3226.eurprd08.prod.outlook.com (2603:10a6:5:22::26) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.16; Wed, 12 Aug 2020 15:23:41 +0000 Received: from DB5EUR03FT059.eop-EUR03.prod.protection.outlook.com (2603:10a6:6:2a:cafe::12) by DB6PR07CA0062.outlook.office365.com (2603:10a6:6:2a::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.7 via Frontend Transport; Wed, 12 Aug 2020 15:23:40 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 40.67.248.234) smtp.mailfrom=arm.com; edk2.groups.io; dkim=none (message not signed) header.d=none;edk2.groups.io; dmarc=bestguesspass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 40.67.248.234 as permitted sender) receiver=protection.outlook.com; client-ip=40.67.248.234; helo=nebula.arm.com; Received: from nebula.arm.com (40.67.248.234) by DB5EUR03FT059.mail.protection.outlook.com (10.152.21.175) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.3283.16 via Frontend Transport; Wed, 12 Aug 2020 15:23:40 +0000 Received: from AZ-NEU-EX04.Arm.com (10.251.24.32) by AZ-NEU-EX04.Arm.com (10.251.24.32) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2044.4; Wed, 12 Aug 2020 15:23:37 +0000 Received: from E107187.Arm.com (10.57.41.222) by mail.arm.com (10.251.24.32) with Microsoft SMTP Server id 15.1.2044.4 via Frontend Transport; Wed, 12 Aug 2020 15:23:37 +0000 From: "Sami Mujawar" To: CC: Sami Mujawar , , , , , , Subject: [PATCH v1 23/30] DynamicTablesPkg: AML Core interface Date: Wed, 12 Aug 2020 16:22:29 +0100 Message-ID: <20200812152236.31164-24-sami.mujawar@arm.com> X-Mailer: git-send-email 2.11.0.windows.3 In-Reply-To: <20200812152236.31164-1-sami.mujawar@arm.com> References: <20200812152236.31164-1-sami.mujawar@arm.com> MIME-Version: 1.0 X-EOPAttributedMessage: 1 X-MS-Office365-Filtering-HT: Tenant X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: bdac413e-529a-486d-39d3-08d83ed3b5d3 X-MS-TrafficTypeDiagnostic: DB7PR08MB3226:|DB6PR0801MB1686: X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true NoDisclaimer: true X-MS-Oob-TLC-OOBClassifiers: OLM:2399;OLM:2399; X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Forefront-Antispam-Report-Untrusted: CIP:40.67.248.234;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:nebula.arm.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(4636009)(136003)(39860400002)(396003)(346002)(376002)(46966005)(356005)(82310400002)(30864003)(82740400003)(81166007)(7696005)(2906002)(70586007)(8676002)(336012)(70206006)(44832011)(6666004)(47076004)(316002)(54906003)(6916009)(1076003)(8936002)(186003)(426003)(478600001)(83380400001)(2616005)(26005)(5660300002)(4326008)(86362001)(36756003);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB7PR08MB3226 Return-Path: Sami.Mujawar@arm.com X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM5EUR03FT007.eop-EUR03.prod.protection.outlook.com X-MS-Office365-Filtering-Correlation-Id-Prvs: 770fd2e6-ce4c-4bd6-d58f-08d83ed3b17c X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: /ZUBiLnA58ySt3/+09p52ghEZls534LVGpcaF8yNYA+I54yQNOyd+nT9aSKKnHokRvZPKzKUMAofnHh8DPR1r+7GSHG97HK04SLrZWFMfZW315G8Mq/lxvCVCeKFKwy0xfay3c8muXscLsiRsPynNlXh1zJO8CvoxddNB9ZWPoxEx/yvmK6LYJVavy4XDN2MQbby7mlunGNe9Ksem1lnSLAa0fJoFkuTNY89iFaLwXelTcS5+3Cd3DrjF00igFErUfFmvZ5GWsGUuCWQGuX4p3MUSxHEaFdaiGSYK8FPu9fP7oQ+BwibOpHtrvdlBzQiEPDjdFsUb7j47PjtWF1gNPkC5CsrvYZl26msWHQac4L2taI6Y0sHXXvGlEt+9gNMkVYhojyt4JKZRMBskGn7Fw== X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFTY:;SFS:(4636009)(346002)(376002)(136003)(39860400002)(396003)(46966005)(81166007)(316002)(2616005)(6666004)(5660300002)(36906005)(478600001)(8676002)(6916009)(26005)(54906003)(4326008)(82740400003)(47076004)(1076003)(86362001)(186003)(7696005)(426003)(336012)(36756003)(70206006)(70586007)(8936002)(2906002)(30864003)(44832011)(83380400001)(82310400002);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Aug 2020 15:23:48.1656 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: bdac413e-529a-486d-39d3-08d83ed3b5d3 X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-AuthSource: AM5EUR03FT007.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB6PR0801MB1686 Content-Type: text/plain From: Pierre Gondois AML Core interface APIs are internal APIs of the AmlLib library. These APIs can be used to: - Create/Delete/Clone an AML tree/node - Get/update Fixed and Variable arguments - Serialize an AML tree. Signed-off-by: Pierre Gondois Signed-off-by: Sami Mujawar --- DynamicTablesPkg/Library/Common/AmlLib/AmlCoreInterface.h | 767 ++++++++++++++++++++ 1 file changed, 767 insertions(+) diff --git a/DynamicTablesPkg/Library/Common/AmlLib/AmlCoreInterface.h b/DynamicTablesPkg/Library/Common/AmlLib/AmlCoreInterface.h new file mode 100644 index 0000000000000000000000000000000000000000..9905cfe551b50eccb3576ff9bdb6a1b582199601 --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/AmlCoreInterface.h @@ -0,0 +1,767 @@ +/** @file + AML Core Interface. + + Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#ifndef AML_CORE_INTERFACE_H_ +#define AML_CORE_INTERFACE_H_ + +/* This header file does not include internal Node definition, + i.e. AML_ROOT_NODE, AML_OBJECT_NODE, etc. The node definitions + must be included by the caller file. The function prototypes must + only expose AML_NODE_HANDLE, AML_ROOT_NODE_HANDLE, etc. node + definitions. + This allows to keep the functions defined here both internal and + potentially external. If necessary, any function of this file can + be exposed externally. + The Api folder is internal to the AmlLib, but should only use these + functions. They provide a "safe" way to interact with the AmlLib. +*/ + +#include +#include +#include + +/** + @defgroup CoreApis Core APIs + @ingroup AMLLib + @{ + Core APIs are the main APIs of the library. They allow to: + - Create an AML tree; + - Delete an AML tree; + - Clone an AML tree/node; + - Serialize an AML tree (convert the tree to a DSDT/SSDT table). + @} +*/ + +/** Serialize a tree to create a DSDT/SSDT table. + + If: + - the content of BufferSize is >= to the size needed to serialize the + definition block; + - Buffer is not NULL; + first serialize the ACPI DSDT/SSDT header from the root node, + then serialize the AML blob from the rest of the tree. + + The content of BufferSize is always updated to the size needed to + serialize the definition block. + + @ingroup CoreApis + + @param [in] RootNode Pointer to a root node. + @param [in] Buffer Buffer to write the DSDT/SSDT table to. + If Buffer is NULL, the size needed to + serialize the DSDT/SSDT table is returned + in BufferSize. + @param [in, out] BufferSize Pointer holding the size of the Buffer. + Its content is always updated to the size + needed to serialize the DSDT/SSDT table. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. + @retval EFI_BUFFER_TOO_SMALL No space left in the buffer. +**/ +EFI_STATUS +EFIAPI +AmlSerializeTree ( + IN AML_ROOT_NODE_HANDLE RootNode, + IN UINT8 * Buffer, OPTIONAL + IN OUT UINT32 * BufferSize + ); + +/** Clone a node. + + This function does not clone the children nodes. + The cloned node returned is not attached to any tree. + + @ingroup CoreApis + + @param [in] Node Pointer to a node. + @param [out] ClonedNode Pointer holding the cloned 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 +AmlCloneNode ( + IN AML_NODE_HANDLE Node, + OUT AML_NODE_HANDLE * ClonedNode + ); + +/** + @defgroup TreeModificationApis Tree modification APIs + @ingroup AMLLib + @{ + Tree modification APIs allow to add/remove/replace nodes that are in a + variable list of arguments. + + No interface is provided to add/remove/replace nodes that are in a fixed + list of arguments. Indeed, these nodes are the spine of the tree and a + mismanipulation would make the tree inconsistent. + + It is however possible to modify the content of fixed argument nodes via + @ref NodeInterfaceApis APIs. + @} +*/ + +/** Remove the Node from its parent's variable list of arguments. + + The function will fail if the Node is in its parent's fixed + argument list. + The Node is not deleted. The deletion is done separately + from the removal. + + @ingroup TreeModificationApis + + @param [in] Node Pointer to a Node. + Must be a data node or an object node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlRemoveNodeFromVarArgList ( + IN AML_NODE_HANDLE Node + ); + +/** Add the NewNode to the head of the variable list of arguments + of the ParentNode. + + @ingroup TreeModificationApis + + @param [in] ParentNode Pointer to the parent node. + Must be a root or an object node. + @param [in] NewNode Pointer to the node to add. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlVarListAddHead ( + IN AML_NODE_HANDLE ParentNode, + IN AML_NODE_HANDLE NewNode + ); + +/** Add the NewNode to the tail of the variable list of arguments + of the ParentNode. + + @ingroup TreeModificationApis + + @param [in] ParentNode Pointer to the parent node. + Must be a root or an object node. + @param [in] NewNode Pointer to the node to add. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlVarListAddTail ( + IN AML_NODE_HANDLE ParentNode, + IN AML_NODE_HANDLE NewNode + ); + +/** Add the NewNode before the Node in the list of variable + arguments of the Node's parent. + + @ingroup TreeModificationApis + + @param [in] Node Pointer to a node. + Must be a root or an object node. + @param [in] NewNode Pointer to the node to add. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlVarListAddBefore ( + IN AML_NODE_HANDLE Node, + IN AML_NODE_HANDLE NewNode + ); + +/** Add the NewNode after the Node in the variable list of arguments + of the Node's parent. + + @ingroup TreeModificationApis + + @param [in] Node Pointer to a node. + Must be a root or an object node. + @param [in] NewNode Pointer to the node to add. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlVarListAddAfter ( + IN AML_NODE_HANDLE Node, + IN AML_NODE_HANDLE NewNode + ); + +/** Append a Resource Data node to the BufferOpNode. + + The Resource Data node is added at the end of the variable + list of arguments of the BufferOpNode, but before the End Tag. + If no End Tag is found, the function returns an error. + + @param [in] BufferOpNode Buffer node containing resource data elements. + @param [in] NewRdNode The new Resource Data node to add. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlAppendRdNode ( + IN AML_OBJECT_NODE_HANDLE BufferOpNode, + IN AML_DATA_NODE_HANDLE NewRdNode + ); + +/** Replace the OldNode, which is in a variable list of arguments, + with the NewNode. + + Note: This function unlinks the OldNode from the tree. It is the callers + responsibility to delete the OldNode if needed. + + @ingroup TreeModificationApis + + @param [in] OldNode Pointer to the node to replace. + Must be a data node or an object node. + @param [in] NewNode The new node to insert. + Must be a data node or an object node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlReplaceVariableArgument ( + IN AML_NODE_HANDLE OldNode, + IN AML_NODE_HANDLE NewNode + ); + +/** + @defgroup NodeInterfaceApis Node Interface APIs + @ingroup AMLLib + @{ + Node Interface APIs allow to query information from a node. Some functions + expect a specific node type among the root/object/data node types. + + For instance, AmlGetRootNodeInfo expects to receive a root node. + + E.g.: Query the node type, the ACPI header stored in the root node, + the OpCode/SubOpCode/PkgLen of an object node, the type of data + stored in a data node, etc. + + These APIs also allow to update some information. + + E.g.: The ACPI header stored in the root node, the buffer of a data node. + + The information of object nodes and the data type of data nodes cannot be + modified. This prevents the creation of an inconsistent tree. + + It is however possible to remove a node from a variable list of arguments + and replace it. Use the @ref TreeModificationApis APIs for this. + @} +*/ + +/** Returns the tree node type (Root/Object/Data). + + @ingroup NodeInterfaceApis + + @param [in] Node Pointer to a Node. + + @return The node type. + EAmlNodeUnknown if invalid parameter. +**/ +EAML_NODE_TYPE +EFIAPI +AmlGetNodeType ( + IN AML_NODE_HANDLE Node + ); + +/** Get the RootNode information. + The Node must be a root node. + + @ingroup NodeInterfaceApis + + @param [in] RootNode Pointer to a root node. + @param [out] SdtHeaderBuffer Buffer to copy the ACPI DSDT/SSDT header to. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlGetRootNodeInfo ( + IN AML_ROOT_NODE_HANDLE RootNode, + OUT EFI_ACPI_DESCRIPTION_HEADER * SdtHeaderBuffer + ); + +/** Get the ObjectNode information. + The Node must be an object node. + + @ingroup NodeInterfaceApis + + @param [in] ObjectNode Pointer to an object node. + @param [out] OpCode Pointer holding the OpCode. + Optional, can be NULL. + @param [out] SubOpCode Pointer holding the SubOpCode. + Optional, can be NULL. + @param [out] PkgLen Pointer holding the PkgLen. + The PkgLen is 0 for nodes + not having the Pkglen attribute. + Optional, can be NULL. + @param [out] IsNameSpaceNode Pointer holding TRUE if the node is defining + or changing the NameSpace scope. + E.g.: The "Name ()" and "Scope ()" ASL + statements add/modify the NameSpace scope. + Their corresponding node are NameSpace nodes. + Optional, can be NULL. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlGetObjectNodeInfo ( + IN AML_OBJECT_NODE_HANDLE ObjectNode, + OUT UINT8 * OpCode, OPTIONAL + OUT UINT8 * SubOpCode, OPTIONAL + OUT UINT32 * PkgLen, OPTIONAL + OUT BOOLEAN * IsNameSpaceNode OPTIONAL + ); + +/** Returns the count of the fixed arguments for the input Node. + + @ingroup NodeInterfaceApis + + @param [in] Node Pointer to an object node. + + @return Number of fixed arguments of the object node. + Return 0 if the node is not an object node. +**/ +UINT8 +AmlGetFixedArgumentCount ( + IN AML_OBJECT_NODE_HANDLE Node + ); + +/** Get the data type of the DataNode. + The Node must be a data node. + + @ingroup NodeInterfaceApis + + @param [in] DataNode Pointer to a data node. + @param [out] DataType Pointer holding the data type of the data buffer. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlGetNodeDataType ( + IN AML_DATA_NODE_HANDLE DataNode, + OUT EAML_NODE_DATA_TYPE * DataType + ); + +/** Get the descriptor Id of the resource data element + contained in the DataNode. + + The Node must be a data node. + The Node must have the resource data type, i.e. have the + EAmlNodeDataTypeResourceData data type. + + @ingroup NodeInterfaceApis + + @param [in] DataNode Pointer to a data node containing a + resource data element. + @param [out] ResourceDataType Pointer holding the descriptor Id of + the resource data. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlGetResourceDataType ( + IN AML_DATA_NODE_HANDLE DataNode, + OUT AML_RD_HEADER * ResourceDataType + ); + +/** Get the data buffer and size of the DataNode. + The Node must be a data node. + + BufferSize is always updated to the size of buffer of the DataNode. + + If: + - the content of BufferSize is >= to the DataNode's buffer size; + - Buffer is not NULL; + then copy the content of the DataNode's buffer in Buffer. + + @ingroup NodeInterfaceApis + + @param [in] DataNode Pointer to a data node. + @param [out] Buffer Buffer to write the data to. + Optional, if NULL, only update BufferSize. + @param [in, out] BufferSize Pointer holding: + - At entry, the size of the Buffer; + - At exit, the size of the DataNode's + buffer size. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlGetDataNodeBuffer ( + IN AML_DATA_NODE_HANDLE DataNode, + OUT UINT8 * Buffer, OPTIONAL + IN OUT UINT32 * BufferSize + ); + +/** Update the ACPI DSDT/SSDT table header. + + The input SdtHeader information is copied to the tree RootNode. + The table Length field is automatically updated. + The checksum field is only updated when serializing the tree. + + @ingroup NodeInterfaceApis + + @param [in] RootNode Pointer to a root node. + @param [in] SdtHeader Pointer to an ACPI DSDT/SSDT table header. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlUpdateRootNode ( + IN AML_ROOT_NODE_HANDLE RootNode, + IN CONST EFI_ACPI_DESCRIPTION_HEADER * SdtHeader + ); + +/** Update an object node representing an integer with a new value. + + The object node must have one of the following OpCodes: + - AML_BYTE_PREFIX + - AML_WORD_PREFIX + - AML_DWORD_PREFIX + - AML_QWORD_PREFIX + - AML_ZERO_OP + - AML_ONE_OP + + The following OpCode is not supported: + - AML_ONES_OP + + @param [in] IntegerOpNode Pointer an object node containing an integer. + Must not be an object node with an AML_ONES_OP + OpCode. + @param [in] NewInteger New integer value to set. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlUpdateInteger ( + IN AML_OBJECT_NODE_HANDLE IntegerOpNode, + IN UINT64 NewInteger + ); + +/** Update the buffer of a data node. + + Note: The data type of the buffer's content must match the data type of the + DataNode. This is a hard restriction to prevent undesired behaviour. + + @ingroup NodeInterfaceApis + + @param [in] DataNode Pointer to a data node. + @param [in] DataType Data type of the Buffer's content. + @param [in] Buffer Buffer containing the new data. The content of + the Buffer is copied. + @param [in] Size Size of the Buffer. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. + @retval EFI_UNSUPPORTED Operation not supporter. +**/ +EFI_STATUS +EFIAPI +AmlUpdateDataNode ( + IN AML_DATA_NODE_HANDLE DataNode, + IN EAML_NODE_DATA_TYPE DataType, + IN UINT8 * Buffer, + IN UINT32 Size + ); + +/** + @defgroup NavigationApis Navigation APIs + @ingroup AMLLib + @{ + Navigation APIs allow to navigate in the AML tree. There are different + ways to navigate in the tree by: + - Direct relation (@ref CoreNavigationApis); + - Enumeration: enumerate all the nodes and call a callback function + (@ref EnumerationApis); + - Iteration: instantiate an iterator and use it to navigate + (@ref IteratorApis); + - NameSpace path: use the AML namespace to navigate the tree + (@ref NameSpaceApis). + @} +*/ + +/** + @defgroup CoreNavigationApis Core Navigation APIs + @ingroup NavigationApis + @{ + Core Navigation APIs allow to get a node by specifying a relation. + + E.g.: Get the parent, the n-th fixed argument, the next variable + argument, etc. + @} +*/ + +/** Get the parent node of the input Node. + + @ingroup CoreNavigationApis + + @param [in] Node Pointer to a node. + + @return The parent node of the input Node. + NULL otherwise. +**/ +AML_NODE_HANDLE +EFIAPI +AmlGetParent ( + IN AML_NODE_HANDLE Node + ); + +/** Get the node at the input Index in the fixed argument list of the input + ObjectNode. + + @ingroup CoreNavigationApis + + @param [in] ObjectNode Pointer to an object node. + @param [in] Index The Index of the fixed argument to get. + + @return The node at the input Index in the fixed argument list + of the input ObjectNode. + NULL otherwise, e.g. if the node is not an object node, or no + node is available at this Index. +**/ +AML_NODE_HANDLE +EFIAPI +AmlGetFixedArgument ( + IN AML_OBJECT_NODE_HANDLE ObjectNode, + IN EAML_PARSE_INDEX Index + ); + +/** Get the sibling node among the nodes being in + the same variable argument list. + + (ParentNode) /-i # Child of fixed argument b + \ / + |- [a][b][c][d] # Fixed Arguments + |- {(VarArgNode)->(f)->(g)} # Variable Arguments + \ + \-h # Child of variable argument e + + Node must be in a variable list of arguments. + Traversal Order: VarArgNode, f, g, NULL + + @ingroup CoreNavigationApis + + @param [in] VarArgNode Pointer to a node. + Must be in a variable list of arguments. + + @return The next node after VarArgNode in the variable list of arguments. + Return NULL if + - VarArgNode is the last node of the list, or + - VarArgNode is not part of a variable list of arguments. +**/ +AML_NODE_HANDLE +EFIAPI +AmlGetSiblingVariableArgument ( + IN AML_NODE_HANDLE VarArgNode + ); + +/** Get the next variable argument. + + (Node) /-i # Child of fixed argument b + \ / + |- [a][b][c][d] # Fixed Arguments + |- {(e)->(f)->(g)} # Variable Arguments + \ + \-h # Child of variable argument e + + Traversal Order: e, f, g, NULL + + @ingroup CoreNavigationApis + + @param [in] Node Pointer to a Root node or Object Node. + @param [in] CurrVarArg Pointer to the Current Variable Argument. + + @return The node after the CurrVarArg in the variable list of arguments. + If CurrVarArg is NULL, return the first node of the + variable argument list. + Return NULL if + - CurrVarArg is the last node of the list, or + - Node does not have a variable list of arguments. +**/ +AML_NODE_HANDLE +EFIAPI +AmlGetNextVariableArgument ( + IN AML_NODE_HANDLE Node, + IN AML_NODE_HANDLE CurrVarArg + ); + +/** Get the previous variable argument. + + (Node) /-i # Child of fixed argument b + \ / + |- [a][b][c][d] # Fixed Arguments + |- {(e)->(f)->(g)} # Variable Arguments + \ + \-h # Child of variable argument e + + Traversal Order: g, f, e, NULL + + @ingroup CoreNavigationApis + + @param [in] Node Pointer to a root node or an object node. + @param [in] CurrVarArg Pointer to the Current Variable Argument. + + @return The node before the CurrVarArg in the variable list of + arguments. + If CurrVarArg is NULL, return the last node of the + variable list of arguments. + Return NULL if: + - CurrVarArg is the first node of the list, or + - Node doesn't have a variable list of arguments. +**/ +AML_NODE_HANDLE +EFIAPI +AmlGetPreviousVariableArgument ( + IN AML_NODE_HANDLE Node, + IN AML_NODE_HANDLE CurrVarArg + ); + +/** + @defgroup EnumerationApis Enumeration APIs + @ingroup NavigationApis + @{ + Enumeration APIs are navigation APIs, allowing to call a callback function + on each node enumerated. Nodes are enumerated in the AML bytestream order, + i.e. in a depth first order. + @} +*/ + +/** + Callback function prototype used when iterating through the tree. + + @ingroup EnumerationApis + + @param [in] Node The Node currently being processed. + @param [in, out] Context A context for the callback function. + Can be optional. + @param [in, out] Status End the enumeration if pointing to a value + evaluated to TRUE. + Can be optional. + + @retval TRUE if the enumeration can continue or has finished without + interruption. + @retval FALSE if the enumeration needs to stopped or has stopped. +**/ +typedef +BOOLEAN +(EFIAPI * EDKII_AML_TREE_ENUM_CALLBACK) ( + IN AML_NODE_HANDLE Node, + IN OUT VOID * Context, OPTIONAL + IN OUT EFI_STATUS * Status OPTIONAL + ); + +/** Enumerate all nodes of the subtree under the input Node in the AML + bytestream order (i.e. in a depth first order), and call the CallBack + function with the input Context. + The prototype of the Callback function is EDKII_AML_TREE_ENUM_CALLBACK. + + @ingroup EnumerationApis + + @param [in] Node Enumerate nodes of the subtree under this Node. + Must be a valid node. + @param [in] CallBack Callback function to call on each node. + @param [in, out] Context Void pointer used to pass some information + to the Callback function. + Optional, can be NULL. + @param [out] Status Optional parameter that can be used to get + the status of the Callback function. + If used, need to be init to EFI_SUCCESS. + + @retval TRUE if the enumeration can continue or has finished without + interruption. + @retval FALSE if the enumeration needs to stopped or has stopped. +**/ +BOOLEAN +EFIAPI +AmlEnumTree ( + IN AML_NODE_HANDLE Node, + IN EDKII_AML_TREE_ENUM_CALLBACK CallBack, + IN OUT VOID * Context, OPTIONAL + OUT EFI_STATUS * Status OPTIONAL + ); + +/** + @defgroup NameSpaceApis NameSpace APIs + @ingroup NavigationApis + @{ + NameSpace APIs allow to find a node from an AML path, and reciprocally + get the AML path of a node. + + These APIs only operate on "NameSpace nodes", i.e. nodes that are + part of the AML namespace. These are the root node and object nodes + acknowledged by AmlGetObjectNodeInfo in @ref NodeInterfaceApis. + @} +*/ + +/** Build the absolute ASL pathname to Node. + + BufferSize is always updated to the size of the pathname. + + If: + - the content of BufferSize is >= to the size of the pathname AND; + - Buffer is not NULL; + then copy the pathname in the Buffer. A buffer of the size + MAX_ASL_NAMESTRING_SIZE is big enough to receive any ASL pathname. + + @ingroup NameSpaceApis + + @param [in] Node Node to build the absolute path to. + Must be a root node, or a namespace node. + @param [out] Buffer Buffer to write the path to. + If NULL, only update *BufferSize. + @param [in, out] BufferSize Pointer holding: + - At entry, the size of the Buffer; + - At exit, the size of the pathname. + + @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 Out of memory. +**/ +EFI_STATUS +EFIAPI +AmlGetAslPathName ( + IN AML_NODE_HANDLE Node, + OUT CHAR8 * Buffer, + IN OUT UINT32 * BufferSize + ); + +#endif // AML_CORE_INTERFACE_H_ -- 'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'