1# Dynamic Tables Framework
2
3Dynamic Tables Framework provides mechanisms to reduce the amount
4of effort required in porting firmware to new platforms. The aim is
5to provide an implementation capable of generating the firmware
6tables from an external source.  This is potentially a management
7node, either local or remote, or, where suitable, a file that might
8be generated from the system construction.  This initial release
9does not fully implement that - the configuration is held in local
10UEFI modules.
11
12# Feature Summary
13
14The dynamic tables framework is designed to generate standardised
15firmware tables that describe the hardware information at
16run-time. A goal of standardised firmware is to have a common
17firmware for a platform capable of booting both Windows and Linux
18operating systems.
19
20Traditionally the firmware tables are handcrafted using ACPI
21Source Language (ASL), Table Definition Language (TDL) and
22C-code. This approach can be error prone and involves time
23consuming debugging. In addition, it may be desirable to configure
24platform hardware at runtime such as: configuring the number of
25cores available for use by the OS, or turning SoC features ON or
26OFF.
27
28The dynamic tables framework simplifies this by providing a set
29of standard table generators, that are implemented as libraries.
30These generators query a platform specific component, the
31'Configuration Manager', to collate the information required
32for generating the tables at run-time.
33
34The framework also provides the ability to implement custom/OEM
35generators; thereby facilitating support for custom tables. The
36custom generators can also utilize the existing standard generators
37and override any functionality if needed.
38
39The framework currently implements a set of standard ACPI table
40generators for ARM architecture, that can generate Server Base Boot
41Requirement (SBBR) compliant tables. Although, the set of standard
42generators implement the functionality required for ARM architecture;
43the framework is extensible, and support for other architectures can
44be added easily.
45
46The 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
55         Description Table
56* SPCR - Serial Port Console Redirection Table
57* SSDT - Secondary System Description Table. This is essentially
58         a RAW table generator.
59
60## Dynamic AML
61
62ACPI Definition block (e.g. DSDT or SSDT) tables are used to describe system
63devices along with other control and power management information. These tables
64are written using ACPI Source Language (ASL). The ASL code is compiled using an
65ASL compiler (e.g. Intel iASL compiler) to generate ACPI Machine Language (AML)
66bytecode.
67
68Since, definition blocks are represented using AML grammar, run-time generation
69of definition blocks is complex. Dynamic AML is a feature of Dynamic Tables
70framework that provides a solution for dynamic generation of ACPI Definition
71block tables.
72
73Dynamic AML introduces the following techniques:
74* AML Fixup
75* AML Codegen
76* AML Fixup + Codegen
77
78### AML Fixup
79AML fixup is a technique that involves compiling an ASL template file to
80generate AML bytecode. This template AML bytecode can be parsed at run-time
81and a fixup code can update the required fields in the AML template.
82
83To simplify AML Fixup, the Dynamic Tables Framework provides an *AmlLib*
84library with a rich set of APIs that can be used to fixup the AML code.
85
86### AML Codegen
87AML Codegen employs generating small segments of AML code. The *AmlLib*
88library provides AML Codegen APIs that generate the AML code segments.
89
90    Example: The following table depicts the AML Codegen APIs and the
91             corresponding ASL code that would be generated.
92
93    | AML Codegen API                | ASL Code                       |
94    |--------------------------------|--------------------------------|
95    |  AmlCodeGenDefinitionBlock (   |  DefinitionBlock (             |
96    |    ..,                         |    ...                         |
97    |    &RootNode);                 |  ) {                           |
98    |  AmlCodeGenScope (             |    Scope (_SB) {               |
99    |    "\_SB",                     |                                |
100    |    RootNode,                   |                                |
101    |    &ScopeNode);                |                                |
102    |  AmlCodeGenDevice (            |    Device (CPU0) {             |
103    |    "CPU0",                     |                                |
104    |    ScopeNode,                  |                                |
105    |    &CpuNode);                  |                                |
106    |  AmlCodeGenNameString (        |      Name (_HID, "ACPI0007")   |
107    |    "_HID",                     |                                |
108    |    "ACPI0007",                 |                                |
109    |    CpuNode,                    |                                |
110    |    &HidNode);                  |                                |
111    |  AmlCodeGenNameInteger (       |      Name (_UID, Zero)         |
112    |    "_UID",                     |                                |
113    |    0,                          |                                |
114    |    CpuNode,                    |                                |
115    |    &UidNode);                  |                                |
116    |                                |      } // Device               |
117    |                                |    } // Scope                  |
118    |                                |  } // DefinitionBlock          |
119
120### AML Fixup + Codegen
121A combination of AML Fixup and AML Codegen could be used for generating
122Definition Blocks. For example the AML Fixup could be used to fixup certain
123parts of the AML template while the AML Codegen APIs could be used to inserted
124small fragments of AML code in the AML template.
125
126### AmlLib Library
127Since, AML bytecode represents complex AML grammar, an **AmlLib** library is
128introduced to assist parsing and traversing of the AML bytecode at run-time.
129
130The AmlLib library parses a definition block and represents it as an AML
131tree. This tree representation is based on the AML grammar defined by the
132ACPI 6.3 specification, section - 20 'ACPI Machine Language (AML)
133Specification'.
134
135AML objects, methods and data are represented as tree nodes. Since the AML
136data is represented as tree nodes, it is possible to traverse the tree, locate
137a 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
139the fixed up AML code can then be installed as an ACPI table (DSDT/SSDT).
140
141AmlLib provides a rich API to operate on AML data. For example it provides
142APIs to update a device's name, the value of a "_UID" object, and the memory
143and interrupt number stored in a "_CRS" node.
144
145Although the AmlLib performs checks to a reasonable extent while modifying a
146definition block, these checks may not cover all aspects due to the complexity
147of the ASL/AML language. It is therefore recommended to review any operation
148performed, and validate the generated output.
149
150    Example: The serialized AML code could be validated by
151     - Saving the generated AML to a file and comparing with
152       a reference output.
153     or
154     - Disassemble the generated AML using the iASL compiler
155       and verifying the output.
156
157# Roadmap
158
159The current implementation of the Configuration Manager populates the
160platform information statically as a C structure. Further enhancements
161to introduce runtime loading of platform information from a platform
162information file is planned.
163
164Also support for generating SMBIOS tables is planned and will be added
165subsequently.
166
167# Supported Platforms
168
1691. Juno
1702. FVP Models
171
172# Build Instructions
173
1741. Set path for the iASL compiler with support for generating a C header
175   file as output.
176
1772. Set PACKAGES_PATH to point to the locations of the following repositories:
178
179Example:
180
181> set PACKAGES_PATH=%CD%\edk2;%CD%\edk2-platforms;
182
183  or
184
185> export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms
186
1873. To enable Dynamic tables framework the *'DYNAMIC_TABLES_FRAMEWORK'*
188option must be defined. This can be passed as a command line
189parameter to the edk2 build system.
190
191Example:
192
193>build -a AARCH64 -p Platform\ARM\JunoPkg\ArmJuno.dsc
194   -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
195
196or
197
198>build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc
199   -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
200
201# Prerequisites
202
203Ensure 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.
206
207
208#Running CI builds locally
209
210The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules:
211
212   -  *[edk2-pytool-library](https://pypi.org/project/edk2-pytool-library)*
213
214   - *[edk2-pytool-extensions](https://pypi.org/project/edk2-pytool-extensions)*
215
216
217The instructions to setup the CI environment are in *'edk2\\.pytool\\Readme.md'*
218
219## Building DynamicTablesPkg with Pytools
220
2211. [Optional] Create a Python Virtual Environment - generally once per workspace
222
223    ```
224        python -m venv <name of virtual environment>
225
226        e.g. python -m venv edk2-ci
227    ```
228
2292. [Optional] Activate Virtual Environment - each time new shell/command window is opened
230
231    ```
232        <name of virtual environment>/Scripts/activate
233
234        e.g. On a windows host PC run:
235             edk2-ci\Scripts\activate.bat
236    ```
2373. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
238
239    ```
240        pip install --upgrade -r pip-requirements.txt
241    ```
242
2434. Initialize & Update Submodules - only when submodules updated
244
245    ```
246        stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
247
248        e.g. stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
249    ```
250
2515. Initialize & Update Dependencies - only as needed when ext_deps change
252
253    ```
254        stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
255
256        e.g. stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
257    ```
258
2596. Compile the basetools if necessary - only when basetools C source files change
260
261    ```
262        python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
263    ```
264
2657. Compile DynamicTablesPkg
266
267    ```
268        stuart_build-c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
269
270        e.g. stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5 -p DynamicTablesPkg -a AARCH64 --verbose
271    ```
272
273    - use `stuart_build -c .pytool/CISettings.py -h` option to see help on additional options.
274
275
276# Documentation
277
278Refer to the following presentation from *UEFI Plugfest Seattle 2018*:
279
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)
281
282