1 # Dynamic Tables Framework
3 Dynamic Tables Framework provides mechanisms to reduce the amount
4 of effort required in porting firmware to new platforms. The aim is
5 to provide an implementation capable of generating the firmware
6 tables from an external source. This is potentially a management
7 node, either local or remote, or, where suitable, a file that might
8 be generated from the system construction. This initial release
9 does not fully implement that - the configuration is held in local
14 The dynamic tables framework is designed to generate standardised
15 firmware tables that describe the hardware information at
16 run-time. A goal of standardised firmware is to have a common
17 firmware for a platform capable of booting both Windows and Linux
20 Traditionally the firmware tables are handcrafted using ACPI
21 Source Language (ASL), Table Definition Language (TDL) and
22 C-code. This approach can be error prone and involves time
23 consuming debugging. In addition, it may be desirable to configure
24 platform hardware at runtime such as: configuring the number of
25 cores available for use by the OS, or turning SoC features ON or
28 The dynamic tables framework simplifies this by providing a set
29 of standard table generators, that are implemented as libraries.
30 These generators query a platform specific component, the
31 'Configuration Manager', to collate the information required
32 for generating the tables at run-time.
34 The framework also provides the ability to implement custom/OEM
35 generators; thereby facilitating support for custom tables. The
36 custom generators can also utilize the existing standard generators
37 and override any functionality if needed.
39 The framework currently implements a set of standard ACPI table
40 generators for ARM architecture, that can generate Server Base Boot
41 Requirement (SBBR) compliant tables. Although, the set of standard
42 generators implement the functionality required for ARM architecture;
43 the framework is extensible, and support for other architectures can
46 The framework currently supports the following table generators for ARM:
47 * DBG2 - Debug Port Table 2
48 * DSDT - Differentiated system description table. This is essentially
49 a RAW table generator.
50 * FADT - Fixed ACPI Description Table
51 * GTDT - Generic Timer Description Table
52 * IORT - IO Remapping Table
53 * MADT - Multiple APIC Description Table
54 * MCFG - PCI Express memory mapped configuration space base address
56 * SPCR - Serial Port Console Redirection Table
57 * SSDT - Secondary System Description Table. This is essentially
58 a RAW table generator.
62 ACPI Definition block (e.g. DSDT or SSDT) tables are used to describe system
63 devices along with other control and power management information. These tables
64 are written using ACPI Source Language (ASL). The ASL code is compiled using an
65 ASL compiler (e.g. Intel iASL compiler) to generate ACPI Machine Language (AML)
68 Since, definition blocks are represented using AML grammar, run-time generation
69 of definition blocks is complex. Dynamic AML is a feature of Dynamic Tables
70 framework that provides a solution for dynamic generation of ACPI Definition
73 Dynamic AML introduces the following techniques:
79 AML fixup is a technique that involves compiling an ASL template file to
80 generate AML bytecode. This template AML bytecode can be parsed at run-time
81 and a fixup code can update the required fields in the AML template.
83 To simplify AML Fixup, the Dynamic Tables Framework provides an *AmlLib*
84 library with a rich set of APIs that can be used to fixup the AML code.
87 AML Codegen employs generating small segments of AML code. The *AmlLib*
88 library provides AML Codegen APIs that generate the AML code segments.
90 Example: The following table depicts the AML Codegen APIs and the
91 corresponding ASL code that would be generated.
93 | AML Codegen API | ASL Code |
94 |--------------------------------|--------------------------------|
95 | AmlCodeGenDefinitionBlock ( | DefinitionBlock ( |
98 | AmlCodeGenScope ( | Scope (_SB) { |
102 | AmlCodeGenDevice ( | Device (CPU0) { |
106 | AmlCodeGenNameString ( | Name (_HID, "ACPI0007") |
111 | AmlCodeGenNameInteger ( | Name (_UID, Zero) |
118 | | } // DefinitionBlock |
120 ### AML Fixup + Codegen
121 A combination of AML Fixup and AML Codegen could be used for generating
122 Definition Blocks. For example the AML Fixup could be used to fixup certain
123 parts of the AML template while the AML Codegen APIs could be used to inserted
124 small fragments of AML code in the AML template.
127 Since, AML bytecode represents complex AML grammar, an **AmlLib** library is
128 introduced to assist parsing and traversing of the AML bytecode at run-time.
130 The AmlLib library parses a definition block and represents it as an AML
131 tree. This tree representation is based on the AML grammar defined by the
132 ACPI 6.3 specification, section - 20 'ACPI Machine Language (AML)
135 AML objects, methods and data are represented as tree nodes. Since the AML
136 data is represented as tree nodes, it is possible to traverse the tree, locate
137 a node and modify the node data. The tree can then be serialized to a buffer
138 (that represents the definition block). This definition block containing
139 the fixed up AML code can then be installed as an ACPI table (DSDT/SSDT).
141 AmlLib provides a rich API to operate on AML data. For example it provides
142 APIs to update a device's name, the value of a "_UID" object, and the memory
143 and interrupt number stored in a "_CRS" node.
145 Although the AmlLib performs checks to a reasonable extent while modifying a
146 definition block, these checks may not cover all aspects due to the complexity
147 of the ASL/AML language. It is therefore recommended to review any operation
148 performed, and validate the generated output.
150 Example: The serialized AML code could be validated by
151 - Saving the generated AML to a file and comparing with
154 - Disassemble the generated AML using the iASL compiler
155 and verifying the output.
159 The current implementation of the Configuration Manager populates the
160 platform information statically as a C structure. Further enhancements
161 to introduce runtime loading of platform information from a platform
162 information file is planned.
164 Also support for generating SMBIOS tables is planned and will be added
167 # Supported Platforms
174 1. Set path for the iASL compiler with support for generating a C header
177 2. Set PACKAGES_PATH to point to the locations of the following repositories:
181 > set PACKAGES_PATH=%CD%\edk2;%CD%\edk2-platforms;
185 > export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms
187 3. To enable Dynamic tables framework the *'DYNAMIC_TABLES_FRAMEWORK'*
188 option must be defined. This can be passed as a command line
189 parameter to the edk2 build system.
193 >build -a AARCH64 -p Platform\ARM\JunoPkg\ArmJuno.dsc
194 -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
198 >build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc
199 -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
203 Ensure that the latest ACPICA iASL compiler is used for building *Dynamic Tables Framework*.
204 *Dynamic Tables Framework* has been tested using the following iASL compiler version:
205 [Version 20200717](https://www.acpica.org/node/183), dated 17 July, 2020.
208 #Running CI builds locally
210 The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules:
212 - *[edk2-pytool-library](https://pypi.org/project/edk2-pytool-library)*
214 - *[edk2-pytool-extensions](https://pypi.org/project/edk2-pytool-extensions)*
217 The instructions to setup the CI environment are in *'edk2\\.pytool\\Readme.md'*
219 ## Building DynamicTablesPkg with Pytools
221 1. [Optional] Create a Python Virtual Environment - generally once per workspace
224 python -m venv <name of virtual environment>
226 e.g. python -m venv edk2-ci
229 2. [Optional] Activate Virtual Environment - each time new shell/command window is opened
232 <name of virtual environment>/Scripts/activate
234 e.g. On a windows host PC run:
235 edk2-ci\Scripts\activate.bat
237 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
240 pip install --upgrade -r pip-requirements.txt
243 4. Initialize & Update Submodules - only when submodules updated
246 stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
248 e.g. stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
251 5. Initialize & Update Dependencies - only as needed when ext_deps change
254 stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
256 e.g. stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
259 6. Compile the basetools if necessary - only when basetools C source files change
262 python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
265 7. Compile DynamicTablesPkg
268 stuart_build-c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
270 e.g. stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5 -p DynamicTablesPkg -a AARCH64 --verbose
273 - use `stuart_build -c .pytool/CISettings.py -h` option to see help on additional options.
278 Refer to the following presentation from *UEFI Plugfest Seattle 2018*:
280 [Dynamic Tables Framework: A Step Towards Automatic Generation of Advanced Configuration and Power Interface (ACPI) & System Management BIOS (SMBIOS) Tables](http://www.uefi.org/sites/default/files/resources/Arm_Dynamic%20Tables%20Framework%20A%20Step%20Towards%20Automatic%20Generation%20of%20Advanced%20Configuration%20and%20Power%20Interface%20%28ACPI%29%20%26%20System%20Management%20BIOS%20%28SMBIOS%29%20Tables%20_0.pdf)