Dynamic Tables Framework provides mechanisms to reduce the amount of effort required in porting firmware to new platforms. The aim is to provide an implementation capable of generating the firmware tables from an external source. This is potentially a management node, either local or remote, or, where suitable, a file that might be generated from the system construction. This initial release does not fully implement that - the configuration is held in local UEFI modules.
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 firmware for a platform capable of booting both Windows and Linux operating systems.
Traditionally the firmware tables are handcrafted using ACPI Source Language (ASL), Table Definition Language (TDL) and C-code. This approach can be error prone and involves time consuming debugging. In addition, it may be desirable to configure platform hardware at runtime such as: configuring the number of cores available for use by the OS, or turning SoC features ON or OFF.
The dynamic tables framework simplifies this by providing a set of standard table generators, that are implemented as libraries. These generators query a platform specific component, the ‘Configuration Manager’, to collate the information required for generating the tables at run-time.
The framework also provides the ability to implement custom/OEM generators; thereby facilitating support for custom tables. The custom generators can also utilize the existing standard generators and override any functionality if needed.
The framework currently implements a set of standard ACPI table generators for ARM architecture, that can generate Server Base Boot Requirement (SBBR) compliant tables. Although, the set of standard generators implement the functionality required for ARM architecture; the framework is extensible, and support for other architectures can be added easily.
The framework currently supports the following table generators for ARM:
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 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 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 |
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.
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.
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 information file is planned.
Also support for generating SMBIOS tables is planned and will be added subsequently.
Set path for the iASL compiler with support for generating a C header file as output.
Set PACKAGES_PATH to point to the locations of the following repositories:
Example:
set PACKAGES_PATH=%CD%\edk2;%CD%\edk2-platforms;
or
export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms
Example:
build -a AARCH64 -p Platform\ARM\JunoPkg\ArmJuno.dsc -t GCC5 -D DYNAMIC_TABLES_FRAMEWORK
or
build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc -t GCC5 -D DYNAMIC_TABLES_FRAMEWORK
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, dated 17 July, 2020.
#Running CI builds locally
The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules:
The instructions to setup the CI environment are in ‘edk2\.pytool\Readme.md’
[Optional] Create a Python Virtual Environment - generally once per workspace
python -m venv <name of virtual environment>
e.g. python -m venv edk2-ci
[Optional] Activate Virtual Environment - each time new shell/command window is opened
<name of virtual environment>/Scripts/activate
e.g. On a windows host PC run:
edk2-ci\Scripts\activate.bat
Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
pip install --upgrade -r pip-requirements.txt
Initialize & Update Submodules - only when submodules updated
stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
e.g. stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
Initialize & Update Dependencies - only as needed when ext_deps change
stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
e.g. stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
Compile the basetools if necessary - only when basetools C source files change
python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
Compile DynamicTablesPkg
stuart_build-c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
e.g. stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5 -p DynamicTablesPkg -a AARCH64 --verbose
stuart_build -c .pytool/CISettings.py -h option to see help on additional options.Refer to the following presentation from UEFI Plugfest Seattle 2018: