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.49]) by mx.groups.io with SMTP id smtpd.web12.16973.1597245813069188506 for ; Wed, 12 Aug 2020 08:23:33 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=jORwrdvU; spf=pass (domain: arm.com, ip: 40.107.21.49, 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=4DMIZmYcUdd++dhTIL7D+8tHfIQFSNsMUCjQZJQSOWY=; b=jORwrdvU7LRPrbc19dMCGu/NG45T962TfZJx4bnAMTmfrsGoR4HNLTeaXkeOt5TYXi8BICptDgM+XKwZ8NG0iybxrf25463PI5ikaWGBxX1UCtYiO9eKHtERatFZKsNyryjcRjK0pWQKsX9tsH26TGDKTzApLkKhplI4THZs9aM= Received: from AM6PR10CA0096.EURPRD10.PROD.OUTLOOK.COM (2603:10a6:209:8c::37) by DB8PR08MB5052.eurprd08.prod.outlook.com (2603:10a6:10:e8::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3261.16; Wed, 12 Aug 2020 15:23:29 +0000 Received: from AM5EUR03FT049.eop-EUR03.prod.protection.outlook.com (2603:10a6:209:8c:cafe::31) by AM6PR10CA0096.outlook.office365.com (2603:10a6:209:8c::37) 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:29 +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 AM5EUR03FT049.mail.protection.outlook.com (10.152.17.130) 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:29 +0000 Received: ("Tessian outbound a0bffebca527:v64"); Wed, 12 Aug 2020 15:23:29 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: b82a804e057189ba X-CR-MTA-TID: 64aa7808 Received: from 5ee88d692784.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 269F87EB-DF38-4B3B-8A59-6A8E603FCA82.1; Wed, 12 Aug 2020 15:23:20 +0000 Received: from EUR02-AM5-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 5ee88d692784.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Wed, 12 Aug 2020 15:23:20 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=lH5Axk7ZHJYn/jMiL5xFw/vvKZcyNdAmxN9Dyen/9zJlXJkYLprCPc30pVO675RjPoaZo98j/G2Q/eLh7kMVCzZA7ldK7TQHjgduEEcdITKTsIC3+EO5A+W4u/mrmuU9sYbizeKZsMhhiHq5AC54E6lbFSlVgRg6mO2kG78dnduBpms+k5kXfFK81cw281m0TPF6EH0Ya4m6QM4nSv+Sr/3N3nA6TkXepcS7y6BZxP1RNpMnObq/43cJBFWzs8PuAOPzu77c6HqJU0E660KtbB6ToinxiPTVPXBdiPx1qi4AhYPC8Ll7zOcnFsu555kxfyHPI0DsYCpPYaTR+qu4Cg== 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=4DMIZmYcUdd++dhTIL7D+8tHfIQFSNsMUCjQZJQSOWY=; b=IK8vhlUU2+t0pK/93d6wFEdLpQPTrRvCD913TVdClQu2d6hzyXw3TVdaFqLz0p6d4e29DAppBN2qNlbrQaMqrcarNFinwuqIPlFKXuhOW/cNijX8YO8g1PKbNdaS6ehy9wEhELoSYAgpFzpQ+cMMgTEyYWiYbvx+fJxI8KUBijjdZhhjX9SDL2lS/0B6GqPVWjRJzSu3KIwLfYhsmQSXr0fvhzbNIOZWfkdNUK0FDICWldyY7Yb9gLGsSvAov02qOvlmIQzn8FZFb8m7NuY7kcZvf8RLyVr+p1YiqliN305VYTFDGrsWvJxSoz1WjzViwEWJNW8WGozHFhxZVp3SvA== 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=4DMIZmYcUdd++dhTIL7D+8tHfIQFSNsMUCjQZJQSOWY=; b=jORwrdvU7LRPrbc19dMCGu/NG45T962TfZJx4bnAMTmfrsGoR4HNLTeaXkeOt5TYXi8BICptDgM+XKwZ8NG0iybxrf25463PI5ikaWGBxX1UCtYiO9eKHtERatFZKsNyryjcRjK0pWQKsX9tsH26TGDKTzApLkKhplI4THZs9aM= Received: from DB6P193CA0014.EURP193.PROD.OUTLOOK.COM (2603:10a6:6:29::24) by AM8PR08MB5682.eurprd08.prod.outlook.com (2603:10a6:20b:1c5::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.15; Wed, 12 Aug 2020 15:23:19 +0000 Received: from DB5EUR03FT018.eop-EUR03.prod.protection.outlook.com (2603:10a6:6:29:cafe::e4) by DB6P193CA0014.outlook.office365.com (2603:10a6:6:29::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3283.15 via Frontend Transport; Wed, 12 Aug 2020 15:23:19 +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 DB5EUR03FT018.mail.protection.outlook.com (10.152.20.69) 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:17 +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:11 +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:10 +0000 From: "Sami Mujawar" To: CC: Sami Mujawar , , , , , , Subject: [PATCH v1 08/30] DynamicTablesPkg: AML tree iterator Date: Wed, 12 Aug 2020 16:22:14 +0100 Message-ID: <20200812152236.31164-9-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: bff83bee-5dbb-4873-f763-08d83ed3aa8b X-MS-TrafficTypeDiagnostic: AM8PR08MB5682:|DB8PR08MB5052: X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true NoDisclaimer: true X-MS-Oob-TLC-OOBClassifiers: OLM:5516;OLM:5516; X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: Rc8czPMOfmEiGfdE5x2CRNrHjKgA9SZFwAayruh5fmDHTsa/qxawyDA41jbeu1wZbCFHRiqNjrcZH61YpeyCzg3Ki2NkaIBraONuyGSVYDJ6E0xUOwCCL/Q2qN/jv7I+++emwvr0H/QJ5Zz4El3Mlr4jAE/578KBh4Og5s+dQMf3nZPUYy6/+J3BwQsStH7v8K4+aenD/z8oHmZ5WV3M26AVYPcP0Cr+LAfu7+282aAokm6G6+4scsAuDWrrMJ5CvcKqSyGqL7PvdzS7NOcpBh4/KbZZ2I/RSCv7ktVaXNgJKj5VgEHQLiT9z2tfcjCS1jyeBtwF87JBSzREceml2Ff5Gc77LUZ1Ubs8tH3nqYw/9iplBtVBqt0iJx0H7tMcaPmnlogBo7OtMi3S90vB9A== 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)(376002)(346002)(39860400002)(396003)(136003)(46966005)(36756003)(8676002)(478600001)(86362001)(2906002)(2616005)(426003)(44832011)(6916009)(83380400001)(47076004)(316002)(356005)(4326008)(26005)(54906003)(7696005)(8936002)(1076003)(186003)(5660300002)(70206006)(82310400002)(30864003)(81166007)(70586007)(336012)(82740400003);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM8PR08MB5682 Return-Path: Sami.Mujawar@arm.com X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM5EUR03FT049.eop-EUR03.prod.protection.outlook.com X-MS-Office365-Filtering-Correlation-Id-Prvs: 5a2b4105-4149-4337-c4df-08d83ed3a39e X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: FzKoHmasEIu/hU/WLZa8bBTppmgySFTUzVVZIQTQN61/TzVnsOfPTRDooFOwU1iDzJ2fm+AHqCD+esLZwpjDQAO5eM3J1tbdsPs7PPwfKs0qu1sPDgMEuZABbZEDNnfPUtupk60PlhIb6x2+daOw9PomXEdjr9qKZt3KQAO3dJ1452LQkvy1eKEmGAg3zYnGwMSivrFH08TNfDzUdu1i5DRPNhXaxgyA+9QaDpw0CfYSrbzbl7NRoLVF0N3HtRntY9rf0lHLghyrkhbJ2dIUm/Jy6lcd97gUBV5U6HyXsvJAOsHCZrCkbsc5TCyC73grdGwiZ2266qLv1fAr9pBMb1NCB08EafaE3U35XhY1LD2cllG4E30idj2GmMKg+BTOCmeeWIx+U7JW9wMKAtprSg== 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)(39860400002)(376002)(396003)(136003)(46966005)(82740400003)(6916009)(44832011)(426003)(316002)(36756003)(2616005)(7696005)(336012)(26005)(54906003)(4326008)(478600001)(2906002)(82310400002)(8936002)(86362001)(47076004)(83380400001)(81166007)(5660300002)(1076003)(30864003)(70586007)(70206006)(186003)(8676002)(36906005);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Aug 2020 15:23:29.2476 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: bff83bee-5dbb-4873-f763-08d83ed3aa8b 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: AM5EUR03FT049.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB8PR08MB5052 Content-Type: text/plain From: Pierre Gondois The AML tree iterator provides interfaces to traverse the nodes in the AML tree. The iterator can traverse the AML tree nodes in the following order: - Linear progression: Iterate following the AML byte stream order (depth first). - Branch progression: Iterate following the AML byte stream order (depth first), but stop iterating at the end of the branch. Signed-off-by: Pierre Gondois Signed-off-by: Sami Mujawar --- DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.c | 353 ++++++++++++++++++++ DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.h | 220 ++++++++++++ 2 files changed, 573 insertions(+) diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.c b/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.c new file mode 100644 index 0000000000000000000000000000000000000000..e99c234990c669c89767d922aad75627adb2c350 --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.c @@ -0,0 +1,353 @@ +/** @file + AML Tree Iterator. + + Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#include +#include + +#include +#include + +/** Iterator to traverse the tree. + + This is an internal structure. +*/ +typedef struct AmlTreeInternalIterator { + /// External iterator structure, containing the external APIs. + /// Must be the first field. + AML_TREE_ITERATOR Iterator; + + // Note: The following members of this structure are opaque to the users + // of the Tree iterator APIs. + + /// Pointer to the node on which the iterator has been initialized. + CONST AML_NODE_HEADER * InitialNode; + + /// Pointer to the current node. + CONST AML_NODE_HEADER * CurrentNode; + + /// Iteration mode. + /// Allow to choose how to traverse the tree/choose which node is next. + EAML_ITERATOR_MODE Mode; +} AML_TREE_ITERATOR_INTERNAL; + +/** Get the current node of an iterator. + + @param [in] Iterator Pointer to an iterator. + @param [out] OutNode Pointer holding the current node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +STATIC +EFI_STATUS +EFIAPI +AmlIteratorGetNode ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HEADER ** OutNode + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)Iterator; + + // CurrentNode can be NULL, but InitialNode cannot. + if ((OutNode == NULL) || + (InternalIterator == NULL) || + (InternalIterator->Mode <= EAmlIteratorUnknown) || + (InternalIterator->Mode >= EAmlIteratorModeMax) || + !IS_AML_NODE_VALID (InternalIterator->InitialNode) || + ((InternalIterator->CurrentNode != NULL) && + !IS_AML_NODE_VALID (InternalIterator->CurrentNode))) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + *OutNode = (AML_NODE_HEADER*)InternalIterator->CurrentNode; + + return EFI_SUCCESS; +} + +/** Move the current node of the iterator to the next node, + according to the iteration mode selected. + + If NextNode is not NULL, return the next node. + + @param [in] Iterator Pointer to an iterator. + @param [out] NextNode If not NULL, updated to the next node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +STATIC +EFI_STATUS +EFIAPI +AmlIteratorGetNextLinear ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HEADER ** NextNode + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)Iterator; + + // CurrentNode can be NULL, but InitialNode cannot. + if ((InternalIterator == NULL) || + (InternalIterator->Mode != EAmlIteratorLinear) || + !IS_AML_NODE_VALID (InternalIterator->InitialNode) || + !IS_AML_NODE_VALID (InternalIterator->CurrentNode)) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + // Get the next node according to the iteration mode. + InternalIterator->CurrentNode = AmlGetNextNode ( + InternalIterator->CurrentNode + ); + + if (NextNode != NULL) { + *NextNode = (AML_NODE_HEADER*)InternalIterator->CurrentNode; + } + return EFI_SUCCESS; +} + +/** Move the current node of the iterator to the previous node, + according to the iteration mode selected. + + If PrevNode is not NULL, return the previous node. + + @param [in] Iterator Pointer to an iterator. + @param [out] PrevNode If not NULL, updated to the previous node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +STATIC +EFI_STATUS +EFIAPI +AmlIteratorGetPreviousLinear ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HEADER ** PrevNode + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)Iterator; + + // CurrentNode can be NULL, but InitialNode cannot. + if ((InternalIterator == NULL) || + (InternalIterator->Mode != EAmlIteratorLinear) || + !IS_AML_NODE_VALID (InternalIterator->InitialNode) || + !IS_AML_NODE_VALID (InternalIterator->CurrentNode)) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + // Get the previous node according to the iteration mode. + InternalIterator->CurrentNode = AmlGetPreviousNode ( + InternalIterator->CurrentNode + ); + if (PrevNode != NULL) { + *PrevNode = (AML_NODE_HEADER*)InternalIterator->CurrentNode; + } + return EFI_SUCCESS; +} + +/** Move the current node of the iterator to the next node, + according to the iteration mode selected. + + If NextNode is not NULL, return the next node. + + @param [in] Iterator Pointer to an iterator. + @param [out] NextNode If not NULL, updated to the next node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +STATIC +EFI_STATUS +EFIAPI +AmlIteratorGetNextBranch ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HEADER ** NextNode + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + AML_NODE_HEADER * Node; + + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)Iterator; + + // CurrentNode can be NULL, but InitialNode cannot. + if ((InternalIterator == NULL) || + (InternalIterator->Mode != EAmlIteratorBranch) || + !IS_AML_NODE_VALID (InternalIterator->InitialNode) || + !IS_AML_NODE_VALID (InternalIterator->CurrentNode)) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + Node = AmlGetNextNode (InternalIterator->CurrentNode); + // Check whether NextNode is a sibling of InitialNode. + if (AmlGetParent (Node) == + AmlGetParent ((AML_NODE_HEADER*)InternalIterator->InitialNode)) { + Node = NULL; + } + + InternalIterator->CurrentNode = Node; + + if (NextNode != NULL) { + *NextNode = Node; + } + return EFI_SUCCESS; +} + +/** Move the current node of the iterator to the previous node, + according to the iteration mode selected. + + If PrevNode is not NULL, return the previous node. + + @param [in] Iterator Pointer to an iterator. + @param [out] PrevNode If not NULL, updated to the previous node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +STATIC +EFI_STATUS +EFIAPI +AmlIteratorGetPreviousBranch ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HEADER ** PrevNode + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + AML_NODE_HEADER * Node; + + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)Iterator; + + // CurrentNode can be NULL, but InitialNode cannot. + if ((InternalIterator == NULL) || + (InternalIterator->Mode != EAmlIteratorBranch) || + !IS_AML_NODE_VALID (InternalIterator->InitialNode) || + !IS_AML_NODE_VALID (InternalIterator->CurrentNode)) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + Node = AmlGetPreviousNode (InternalIterator->CurrentNode); + // Check whether PreviousNode is a sibling of InitialNode. + if (AmlGetParent (Node) == + AmlGetParent ((AML_NODE_HEADER*)InternalIterator->InitialNode)) { + Node = NULL; + } + + InternalIterator->CurrentNode = Node; + + if (PrevNode != NULL) { + *PrevNode = Node; + } + return EFI_SUCCESS; +} + +/** Initialize an iterator. + + Note: The caller must call AmlDeleteIterator () to free the memory + allocated for the iterator. + + @param [in] Node Pointer to the node. + @param [in] IteratorMode Selected mode to traverse the tree. + @param [out] IteratorPtr Pointer holding the created iterator. + + @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 +AmlInitializeIterator ( + IN AML_NODE_HEADER * Node, + IN EAML_ITERATOR_MODE IteratorMode, + OUT AML_TREE_ITERATOR ** IteratorPtr + ) +{ + AML_TREE_ITERATOR_INTERNAL * InternalIterator; + + if (!IS_AML_NODE_VALID (Node) || + (IteratorMode <= EAmlIteratorUnknown) || + (IteratorMode >= EAmlIteratorModeMax) || + (IteratorPtr == NULL)) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + *IteratorPtr = NULL; + InternalIterator = (AML_TREE_ITERATOR_INTERNAL*)AllocateZeroPool ( + sizeof ( + AML_TREE_ITERATOR_INTERNAL + ) + ); + if (InternalIterator == NULL) { + ASSERT (0); + return EFI_OUT_OF_RESOURCES; + } + + InternalIterator->InitialNode = Node; + InternalIterator->CurrentNode = Node; + InternalIterator->Mode = IteratorMode; + InternalIterator->Iterator.GetNode = AmlIteratorGetNode; + + switch (InternalIterator->Mode) { + case EAmlIteratorLinear: + { + InternalIterator->Iterator.GetNext = AmlIteratorGetNextLinear; + InternalIterator->Iterator.GetPrevious = AmlIteratorGetPreviousLinear; + break; + } + case EAmlIteratorBranch: + { + InternalIterator->Iterator.GetNext = AmlIteratorGetNextBranch; + InternalIterator->Iterator.GetPrevious = AmlIteratorGetPreviousBranch; + break; + } + default: + { + ASSERT (0); + FreePool (InternalIterator); + return EFI_INVALID_PARAMETER; + } + } // switch + + *IteratorPtr = &InternalIterator->Iterator; + + return EFI_SUCCESS; +} + +/** Delete an iterator. + + Note: The caller must have first initialized the iterator with the + AmlInitializeIterator () function. + + @param [in] Iterator Pointer to an iterator. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlDeleteIterator ( + IN AML_TREE_ITERATOR * Iterator + ) +{ + if (Iterator == NULL) { + ASSERT (0); + return EFI_INVALID_PARAMETER; + } + + FreePool (Iterator); + + return EFI_SUCCESS; +} diff --git a/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.h b/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.h new file mode 100644 index 0000000000000000000000000000000000000000..d96eecab916818ceb0ab46a25e5151916cd4451d --- /dev/null +++ b/DynamicTablesPkg/Library/Common/AmlLib/Tree/AmlTreeIterator.h @@ -0,0 +1,220 @@ +/** @file + AML Iterator. + + Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.
+ + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#ifndef AML_ITERATOR_H_ +#define AML_ITERATOR_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. +*/ + +/** + @defgroup IteratorLibrary Iterator library + @ingroup NavigationApis + @{ + The iterator library allow to navigate in the AML tree using an iterator. + It is possible to initialize/delete an iterator. + + This iterator can progress in the tree by different orders: + - Linear progression: Iterate following the AML bytestream order + (depth first). + - Branch progression: Iterate following the AML bytestream order + (depth first), but stop iterating at the + end of the branch. + + An iterator has the following features: + - GetNode: Get the current node pointed by the iterator. + - GetNext: Move the current node of the iterator to the next + node, according to the iteration mode selected. + - GetPrevious: Move the current node of the iterator to the previous + node, according to the iteration mode selected. + @} +*/ + +/** + @defgroup IteratorApis Iterator APIs + @ingroup IteratorLibrary + @{ + Iterator APIs defines the action that can be done on an iterator: + - Initialization; + - Deletion; + - Getting the node currently pointed by the iterator; + - Moving to the next node; + - Moving to the previous node. + @} +*/ + +/** + @defgroup IteratorStructures Iterator structures + @ingroup IteratorLibrary + @{ + Iterator structures define the enum/define values and structures related + to iterators. + @} +*/ + +/** Iterator mode. + + Modes to choose how the iterator is progressing in the tree. + A + \-B <- Iterator initialized with this node. + | \-C + | | \-D + | \-E + | \-F + | \-G + \-H + \-I + + @ingroup IteratorStructures +*/ +typedef enum EAmlIteratorMode { + EAmlIteratorUnknown, ///< Unknown/Invalid AML IteratorMode + EAmlIteratorLinear, ///< Iterate following the AML bytestream order + /// (depth first). + /// The order followed by the iterator would be: + /// B, C, D, E, F, G, H, I, NULL. + EAmlIteratorBranch, ///< Iterate through the node of a branch. + /// The iteration follows the AML bytestream + /// order but within the branch B. + /// The order followed by the iterator would be: + /// B, C, D, E, F, G, NULL. + EAmlIteratorModeMax ///< Max enum. +} EAML_ITERATOR_MODE; + +/** Iterator. + + Allows to traverse the tree in different orders. + + @ingroup IteratorStructures +*/ +typedef struct AmlTreeIterator AML_TREE_ITERATOR; + +/** Function pointer to a get the current node of the iterator. + + @ingroup IteratorApis + + @param [in] Iterator Pointer to an iterator. + @param [out] OutNode Pointer holding the current node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +*/ +typedef +EFI_STATUS +(EFIAPI * EDKII_AML_TREE_ITERATOR_GET_NODE) ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HANDLE * OutNode + ); + +/** Function pointer to move the current node of the iterator to the + next node, according to the iteration mode selected. + + If NextNode is not NULL, return the next node. + + @ingroup IteratorApis + + @param [in] Iterator Pointer to an iterator. + @param [out] NextNode If not NULL, updated to the next node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +*/ +typedef +EFI_STATUS +(EFIAPI * EDKII_AML_TREE_ITERATOR_GET_NEXT) ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HANDLE * NextNode + ); + +/** Function pointer to move the current node of the iterator to the + previous node, according to the iteration mode selected. + + If PrevNode is not NULL, return the previous node. + + @ingroup IteratorApis + + @param [in] Iterator Pointer to an iterator. + @param [out] PrevNode If not NULL, updated to the previous node. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +*/ +typedef +EFI_STATUS +(EFIAPI * EDKII_AML_TREE_ITERATOR_GET_PREVIOUS) ( + IN AML_TREE_ITERATOR * Iterator, + OUT AML_NODE_HANDLE * PrevNode + ); + +/** Iterator structure to traverse the tree. + + @ingroup IteratorStructures +*/ +typedef struct AmlTreeIterator { + /// Get the current node of the iterator. + EDKII_AML_TREE_ITERATOR_GET_NODE GetNode; + + /// Update the current node of the iterator with the next node. + EDKII_AML_TREE_ITERATOR_GET_NEXT GetNext; + + /// Update the current node of the iterator with the previous node. + EDKII_AML_TREE_ITERATOR_GET_PREVIOUS GetPrevious; +} AML_TREE_ITERATOR; + + +/** Initialize an iterator. + + Note: The caller must call AmlDeleteIterator () to free the memory + allocated for the iterator. + + @ingroup IteratorApis + + @param [in] Node Pointer to the node. + @param [in] IteratorMode Selected mode to traverse the tree. + @param [out] IteratorPtr Pointer holding the created iterator. + + @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 +AmlInitializeIterator ( + IN AML_NODE_HANDLE Node, + IN EAML_ITERATOR_MODE IteratorMode, + OUT AML_TREE_ITERATOR ** IteratorPtr + ); + +/** Delete an iterator. + + Note: The caller must have first initialized the iterator with the + AmlInitializeIterator () function. + + @ingroup IteratorApis + + @param [in] Iterator Pointer to an iterator. + + @retval EFI_SUCCESS The function completed successfully. + @retval EFI_INVALID_PARAMETER Invalid parameter. +**/ +EFI_STATUS +EFIAPI +AmlDeleteIterator ( + IN AML_TREE_ITERATOR * Iterator + ); + +#endif // AML_ITERATOR_H_ -- 'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'