From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from EUR04-VI1-obe.outbound.protection.outlook.com (EUR04-VI1-obe.outbound.protection.outlook.com [40.107.8.74]) by mx.groups.io with SMTP id smtpd.web12.16958.1597245773370046603 for ; Wed, 12 Aug 2020 08:22:54 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@armh.onmicrosoft.com header.s=selector2-armh-onmicrosoft-com header.b=lF6ps2HP; spf=pass (domain: arm.com, ip: 40.107.8.74, 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=rFjnrro4uiX/r/U1ubUCMYMVMSX86+uuT/P87nQvUIY=; b=lF6ps2HP3+oyz3WAB5hGV8TdIFo+rY07FK0OF5Li3UGb/1AAQvHuoQZe5X88HGOU8pUTpyrqxlqnBeiELN0wsUX8ZomR1jJoNfzzjb1v/cW1HibA/mOOf6Y3cPv+rS0pLhX+RXo99ErxCmQn/6Z7+52yBkCIIEUnEYL33XefYgY= Received: from AM5PR04CA0022.eurprd04.prod.outlook.com (2603:10a6:206:1::35) by AM4PR0802MB2291.eurprd08.prod.outlook.com (2603:10a6:200:5e::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3261.15; Wed, 12 Aug 2020 15:22:50 +0000 Received: from AM5EUR03FT022.eop-EUR03.prod.protection.outlook.com (2603:10a6:206:1:cafe::e0) by AM5PR04CA0022.outlook.office365.com (2603:10a6:206:1::35) 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:22:50 +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 AM5EUR03FT022.mail.protection.outlook.com (10.152.16.79) 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:22:50 +0000 Received: ("Tessian outbound 7161e0c2a082:v64"); Wed, 12 Aug 2020 15:22:50 +0000 X-CheckRecipientChecked: true X-CR-MTA-CID: 010c66c1c1d07c52 X-CR-MTA-TID: 64aa7808 Received: from 48a1904769b1.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id 37231928-3F89-4D80-82F5-81E55BBC51F4.1; Wed, 12 Aug 2020 15:22:44 +0000 Received: from EUR04-HE1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 48a1904769b1.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Wed, 12 Aug 2020 15:22:44 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=hSjPyEQeQE4n68Ie/w2FXTQ+S9P1L0ZGMeJbZxInhORmo1GJVMmXpYrrw7FV//EC+hs0HkZzBHq6N5NgUb7GS8imtVMWoAfcvmJcUpOKTeFrNgb3pTIyiNG7xn+I6fbn6qokRETQ46XPjr/gXczpA2k4OvSpWWlrYzTZKHwq3N6XfnbtKbTuPVEpm0yiAgv2MWWRp22/TGPXBvUSu9F6Y3jFHh5Onu9ju7a3nA7rQyN8nYOQrU5JA9yjAIMy2poYab7jRMeekLHx7f9qYIvCcuxXT7sJki/N0p0/tUloRsIeR8TuVjC6jEonzLVgnZnizVLZHDV3IulhLfNN4hwVHg== 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=rFjnrro4uiX/r/U1ubUCMYMVMSX86+uuT/P87nQvUIY=; b=VcvrG8rFLk0xSZyu2bxIVhI8qDNXZz1XkgQvA3AXoMNKQh1EOZOFUhwLeLaiXs6LiVJw2N51wMs958PfGuTOb5ngPi8vEf1aqrDJVpHwjVjIbvQ5ZdEBmuiec2Iizz4CvIlCr6Qzea6aJSPXI40pSzJQBPEHhl+6TUsGCpcUN1f0dXCCJl8CbknJNy5OZO5W9vf25t5muMc/KZbxVLqyJeD6dpDBNlg1VmOdv5ButmIb2Keqt13aLDdz5XGPDX1Ot3UEu0+CViQioKNySpU7DXEU4iBdIAI/d9KNeX91DFRY1CoU89246/dWlFCfrxB/7taEY5soepbU7pLDdOrbMg== 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=rFjnrro4uiX/r/U1ubUCMYMVMSX86+uuT/P87nQvUIY=; b=lF6ps2HP3+oyz3WAB5hGV8TdIFo+rY07FK0OF5Li3UGb/1AAQvHuoQZe5X88HGOU8pUTpyrqxlqnBeiELN0wsUX8ZomR1jJoNfzzjb1v/cW1HibA/mOOf6Y3cPv+rS0pLhX+RXo99ErxCmQn/6Z7+52yBkCIIEUnEYL33XefYgY= Received: from DB8PR06CA0012.eurprd06.prod.outlook.com (2603:10a6:10:100::25) by VI1PR0802MB2222.eurprd08.prod.outlook.com (2603:10a6:800:9b::19) 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:22:42 +0000 Received: from DB5EUR03FT005.eop-EUR03.prod.protection.outlook.com (2603:10a6:10:100:cafe::7b) by DB8PR06CA0012.outlook.office365.com (2603:10a6:10:100::25) 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:22:42 +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 DB5EUR03FT005.mail.protection.outlook.com (10.152.20.122) 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:22:42 +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:22:41 +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:22:37 +0000 From: "Sami Mujawar" To: CC: Sami Mujawar , , , , , , Subject: [PATCH v1 01/30] DynamicTablesPkg: Introduction to Dynamic AML Date: Wed, 12 Aug 2020 16:22:07 +0100 Message-ID: <20200812152236.31164-2-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: f77cff8f-72c8-4925-a811-08d83ed39356 X-MS-TrafficTypeDiagnostic: VI1PR0802MB2222:|AM4PR0802MB2291: X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true NoDisclaimer: true X-MS-Oob-TLC-OOBClassifiers: OLM:9508;OLM:9508; X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: innqBEzAfRc12gRlqMScGwQfZok+hHYQ+KPBLvHNfc2g3m9Osx+0eXGt1L00WEcuU/j5M+k5pDZMxNsBPoaSKonqFukRNnKxRFA3MbLIZe+FbIX9wx2eMeTXDZMuCafYH9CWiskx4rssEJCfIB86OxZdN77n4fBj9ylI7WdEYGSEby4nMDWMQGRIH7fRBKLGEh6Eicl2VRb8mTUfnnT64Nzp5iWfsmNmI+v3x7/LahuS9Na7u1Cku3T0jZ8XkV4J9a8V+2faFHypSRvMkzkaB72XS5UU0gawxi/rVABvqP8kGvSRuJZ5FqFlzaauVabGOM9DHoRYad0gg8aj6O4XsguGifXsFbR36lmQOhPcaaS3HkUEPSSTMiBV7tHD5o9dO+sWagQ7pLDXVYDgIG8S2zba7FJq3mCObRx55cbl+dBcQrlWgGSSKeP1jzeY4HAc4wpzy8Z/Mzo8/dkBOEQeNqiSxj5J1HSJc1FWaf9YTZc= 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;SFTY:;SFS:(4636009)(346002)(376002)(396003)(136003)(39860400002)(46966005)(5660300002)(478600001)(8936002)(86362001)(7696005)(26005)(8676002)(186003)(2906002)(336012)(83380400001)(81166007)(356005)(2616005)(44832011)(82310400002)(47076004)(1076003)(6666004)(70586007)(6916009)(36756003)(4326008)(82740400003)(426003)(316002)(70206006)(54906003);DIR:OUT;SFP:1101; X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0802MB2222 Return-Path: Sami.Mujawar@arm.com X-MS-Exchange-Transport-CrossTenantHeadersStripped: AM5EUR03FT022.eop-EUR03.prod.protection.outlook.com X-MS-Office365-Filtering-Correlation-Id-Prvs: cd0d8960-6416-4dec-9852-08d83ed38e91 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: /I1mDL7bdPHLHuLehKMD0SOxNr3QUwI5AQmTSxiCExU5S9NLd0k6TSL7fuBD7WCkCPANkeB3jLqHRWuDn48ufmvmBbZaJbw/Y0MVgsYEs9jjuAe3HSDd23Q6bkTD99btWyHsbLD1M8jGsehg28LouuL8RtM20nR2Qcd+VNMcdIfi3OVPna2iGvdu7Bi7IQdJnRBpIZvO6rFIBe6NQkKDwtdcVTQq7YXYptOxZO4f7v87FpXujN6lGvLvTp/pClTfY+A6MjHgkH8f7ac02ZLvKrDmiXpCmBSoyZDsoQCm/l0Uo78/VBxk0ylzeU44WYncxcR2r0OlcreRnVoR6t6gwSmxtUSE17VzATSmGAWcuStnbE4sREyDTrKW3HS+yLgLXFiBlUmMO0P46ycDThYdMmAOoIfvtUMvWjn/Xx4/WBJDQ2t7OxSQDHMr/vYcJzSg/3bs9hDUfNqB6AStkrj0M+ruS9IWLKznwxs1bChMp+o= 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)(136003)(376002)(39860400002)(396003)(346002)(46966005)(83380400001)(478600001)(4326008)(82740400003)(82310400002)(70586007)(81166007)(47076004)(8936002)(6916009)(7696005)(70206006)(8676002)(1076003)(5660300002)(86362001)(36756003)(36906005)(186003)(426003)(2906002)(316002)(44832011)(6666004)(336012)(54906003)(2616005)(26005);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Aug 2020 15:22:50.3096 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: f77cff8f-72c8-4925-a811-08d83ed39356 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: AM5EUR03FT022.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: AM4PR0802MB2291 Content-Type: text/plain ACPI Definition block (e.g. DSDT or SSDT) tables are implemented using ACPI source language (ASL) and compiled to ACPI Machine language (AML). The AML bytecode runs in the OS ACPI Interpreter. AML has a complex grammar which makes generation of ACPI Definition block tables difficult. Dynamic Tables Framework introduces a new feature 'Dynamic AML' that aims at simplifying the generation of ACPI Definition block tables. Dynamic AML provides the following techniques for generating ACPI Definition blocks. - AML Fixup - AML Codegen - AML Fixup + Codegen AML Fixup involves patching an AML template code at runtime and then installing the fixed-up AML code as an ACPI table. AML Codegen provides APIs to generate small segments of AML code that can be serialised for installation as an ACPI table. AML Fixup + Codegen is an approach where parts of an AML template are fixed-up at runtime as well as the AML Codegen APIs are used to insert small segments of AML code in the AML template. This AML code is then serialised for installation as an ACPI table. To assist Dynamic AML generation an AmlLib library is introduced that provides a rich set of APIs that can be used to parse, traverse, fixup, codegen and serialise AML definition blocks. Signed-off-by: Pierre Gondois Signed-off-by: Sami Mujawar --- DynamicTablesPkg/Readme.md | 128 +++++++++++++++++--- 1 file changed, 111 insertions(+), 17 deletions(-) diff --git a/DynamicTablesPkg/Readme.md b/DynamicTablesPkg/Readme.md index 34000cf73bc7da5fce2e520d41318af908353969..5f92d4c6cb2efd77bbc3306f827088216b7a32e0 100644 --- a/DynamicTablesPkg/Readme.md +++ b/DynamicTablesPkg/Readme.md @@ -1,5 +1,4 @@ -Dynamic Tables Framework ------------------------- +# Dynamic Tables Framework Dynamic Tables Framework provides mechanisms to reduce the amount of effort required in porting firmware to new platforms. The aim is @@ -10,8 +9,8 @@ be generated from the system construction. This initial release does not fully implement that - the configuration is held in local UEFI modules. -Feature Summary ---------------- +# Feature Summary + The dynamic tables framework is designed to generate standardised firmware tables that describe the hardware information at run-time. A goal of standardised firmware is to have a common @@ -58,8 +57,105 @@ The framework currently supports the following table generators for ARM: * SSDT - Secondary System Description Table. This is essentially a RAW table generator. -Roadmap -------- +## Dynamic AML + +ACPI Definition block (e.g. DSDT or SSDT) tables are used to describe system +devices along with other control and power management information. These tables +are written using ACPI Source Language (ASL). The ASL code is compiled using an +ASL compiler (e.g. Intel iASL compiler) to generate ACPI Machine Language (AML) +bytecode. + +Since, definition blocks are represented using AML grammar, run-time generation +of definition blocks is complex. Dynamic AML is a feature of Dynamic Tables +framework that provides a solution for dynamic generation of ACPI Definition +block tables. + +Dynamic AML introduces the following techniques: +* AML Fixup +* AML Codegen +* AML Fixup + Codegen + +### AML Fixup +AML fixup is a technique that involves compiling an ASL template file to +generate AML bytecode. This template AML bytecode can be parsed at run-time +and a fixup code can update the required fields in the AML template. + +To simplify AML Fixup, the Dynamic Tables Framework provides an *AmlLib* +library with a rich set of APIs that can be used to fixup the AML code. + +### AML Codegen +AML Codegen employs generating small segments of AML code. The *AmlLib* +library provides AML Codegen APIs that generate the AML code segments. + + Example: The following table depicts the AML Codegen APIs and the + corresponding ASL code that would be generated. + + | AML Codegen API | ASL Code | + |--------------------------------|--------------------------------| + | AmlCodeGenDefinitionBlock ( | DefinitionBlock ( | + | .., | ... | + | &RootNode); | ) { | + | AmlCodeGenScope ( | Scope (_SB) { | + | "\_SB", | | + | RootNode, | | + | &ScopeNode); | | + | AmlCodeGenDevice ( | Device (CPU0) { | + | "CPU0", | | + | ScopeNode, | | + | &CpuNode); | | + | AmlCodeGenNameString ( | Name (_HID, "ACPI0007") | + | "_HID", | | + | "ACPI0007", | | + | CpuNode, | | + | &HidNode); | | + | AmlCodeGenNameInteger ( | Name (_UID, Zero) | + | "_UID", | | + | 0, | | + | CpuNode, | | + | &UidNode); | | + | | } // Device | + | | } // Scope | + | | } // DefinitionBlock | + +### AML Fixup + Codegen +A combination of AML Fixup and AML Codegen could be used for generating +Definition Blocks. For example the AML Fixup could be used to fixup certain +parts of the AML template while the AML Codegen APIs could be used to inserted +small fragments of AML code in the AML template. + +### AmlLib Library +Since, AML bytecode represents complex AML grammar, an **AmlLib** library is +introduced to assist parsing and traversing of the AML bytecode at run-time. + +The AmlLib library parses a definition block and represents it as an AML +tree. This tree representation is based on the AML grammar defined by the +ACPI 6.3 specification, section - 20 'ACPI Machine Language (AML) +Specification'. + +AML objects, methods and data are represented as tree nodes. Since the AML +data is represented as tree nodes, it is possible to traverse the tree, locate +a node and modify the node data. The tree can then be serialized to a buffer +(that represents the definition block). This definition block containing +the fixed up AML code can then be installed as an ACPI table (DSDT/SSDT). + +AmlLib provides a rich API to operate on AML data. For example it provides +APIs to update a device's name, the value of a "_UID" object, and the memory +and interrupt number stored in a "_CRS" node. + +Although the AmlLib performs checks to a reasonable extent while modifying a +definition block, these checks may not cover all aspects due to the complexity +of the ASL/AML language. It is therefore recommended to review any operation +performed, and validate the generated output. + + Example: The serialized AML code could be validated by + - Saving the generated AML to a file and comparing with + a reference output. + or + - Disassemble the generated AML using the iASL compiler + and verifying the output. + +# Roadmap + The current implementation of the Configuration Manager populates the platform information statically as a C structure. Further enhancements to introduce runtime loading of platform information from a platform @@ -68,13 +164,13 @@ information file is planned. Also support for generating SMBIOS tables is planned and will be added subsequently. -Supported Platforms -------------------- +# Supported Platforms + 1. Juno 2. FVP Models -Build Instructions ------------------- +# Build Instructions + 1. Set path for the iASL compiler with support for generating a C header file as output. @@ -102,15 +198,14 @@ or >build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK** -Prerequisites -------------- +# Prerequisites + Ensure that the latest ACPICA iASL compiler is used for building *Dynamic Tables Framework*. *Dynamic Tables Framework* has been tested using the following iASL compiler version: -[Version 20200717](https://www.acpica.org/node/183)*, dated 17 July, 2020. +[Version 20200717](https://www.acpica.org/node/183), dated 17 July, 2020. -Running CI builds locally -------------------------- +#Running CI builds locally The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules: @@ -178,8 +273,7 @@ The instructions to setup the CI environment are in *'edk2\\.pytool\\Readme.md'* - use `stuart_build -c .pytool/CISettings.py -h` option to see help on additional options. -Documentation -------------- +# Documentation Refer to the following presentation from *UEFI Plugfest Seattle 2018*: -- 'Guid(CE165669-3EF3-493F-B85D-6190EE5B9759)'