-Dynamic Tables Framework\r
-------------------------\r
+# Dynamic Tables Framework\r
\r
Dynamic Tables Framework provides mechanisms to reduce the amount\r
of effort required in porting firmware to new platforms. The aim is\r
does not fully implement that - the configuration is held in local\r
UEFI modules.\r
\r
-Feature Summary\r
----------------\r
+# Feature Summary\r
+\r
The dynamic tables framework is designed to generate standardised\r
firmware tables that describe the hardware information at\r
run-time. A goal of standardised firmware is to have a common\r
* MADT - Multiple APIC Description Table\r
* MCFG - PCI Express memory mapped configuration space base address\r
Description Table\r
+* PCCT - Platform Communications Channel Table\r
+* PPTT - Processor Properties Topology Table\r
* SPCR - Serial Port Console Redirection Table\r
+* SRAT - System Resource Affinity Table\r
* SSDT - Secondary System Description Table. This is essentially\r
a RAW table generator.\r
\r
-Roadmap\r
--------\r
+## Dynamic AML\r
+\r
+ACPI Definition block (e.g. DSDT or SSDT) tables are used to describe system\r
+devices along with other control and power management information. These tables\r
+are written using ACPI Source Language (ASL). The ASL code is compiled using an\r
+ASL compiler (e.g. Intel iASL compiler) to generate ACPI Machine Language (AML)\r
+bytecode.\r
+\r
+Since, definition blocks are represented using AML grammar, run-time generation\r
+of definition blocks is complex. Dynamic AML is a feature of Dynamic Tables\r
+framework that provides a solution for dynamic generation of ACPI Definition\r
+block tables.\r
+\r
+Dynamic AML introduces the following techniques:\r
+* AML Fixup\r
+* AML Codegen\r
+* AML Fixup + Codegen\r
+\r
+### AML Fixup\r
+AML fixup is a technique that involves compiling an ASL template file to\r
+generate AML bytecode. This template AML bytecode can be parsed at run-time\r
+and a fixup code can update the required fields in the AML template.\r
+\r
+To simplify AML Fixup, the Dynamic Tables Framework provides an *AmlLib*\r
+library with a rich set of APIs that can be used to fixup the AML code.\r
+\r
+### AML Codegen\r
+AML Codegen employs generating small segments of AML code. The *AmlLib*\r
+library provides AML Codegen APIs that generate the AML code segments.\r
+\r
+ Example: The following table depicts the AML Codegen APIs and the\r
+ corresponding ASL code that would be generated.\r
+\r
+ | AML Codegen API | ASL Code |\r
+ |--------------------------------|--------------------------------|\r
+ | AmlCodeGenDefinitionBlock ( | DefinitionBlock ( |\r
+ | .., | ... |\r
+ | &RootNode); | ) { |\r
+ | AmlCodeGenScope ( | Scope (_SB) { |\r
+ | "\_SB", | |\r
+ | RootNode, | |\r
+ | &ScopeNode); | |\r
+ | AmlCodeGenDevice ( | Device (CPU0) { |\r
+ | "CPU0", | |\r
+ | ScopeNode, | |\r
+ | &CpuNode); | |\r
+ | AmlCodeGenNameString ( | Name (_HID, "ACPI0007") |\r
+ | "_HID", | |\r
+ | "ACPI0007", | |\r
+ | CpuNode, | |\r
+ | &HidNode); | |\r
+ | AmlCodeGenNameInteger ( | Name (_UID, Zero) |\r
+ | "_UID", | |\r
+ | 0, | |\r
+ | CpuNode, | |\r
+ | &UidNode); | |\r
+ | | } // Device |\r
+ | | } // Scope |\r
+ | | } // DefinitionBlock |\r
+\r
+### AML Fixup + Codegen\r
+A combination of AML Fixup and AML Codegen could be used for generating\r
+Definition Blocks. For example the AML Fixup could be used to fixup certain\r
+parts of the AML template while the AML Codegen APIs could be used to inserted\r
+small fragments of AML code in the AML template.\r
+\r
+### AmlLib Library\r
+Since, AML bytecode represents complex AML grammar, an **AmlLib** library is\r
+introduced to assist parsing and traversing of the AML bytecode at run-time.\r
+\r
+The AmlLib library parses a definition block and represents it as an AML\r
+tree. This tree representation is based on the AML grammar defined by the\r
+ACPI 6.3 specification, section - 20 'ACPI Machine Language (AML)\r
+Specification'.\r
+\r
+AML objects, methods and data are represented as tree nodes. Since the AML\r
+data is represented as tree nodes, it is possible to traverse the tree, locate\r
+a node and modify the node data. The tree can then be serialized to a buffer\r
+(that represents the definition block). This definition block containing\r
+the fixed up AML code can then be installed as an ACPI table (DSDT/SSDT).\r
+\r
+AmlLib provides a rich API to operate on AML data. For example it provides\r
+APIs to update a device's name, the value of a "_UID" object, and the memory\r
+and interrupt number stored in a "_CRS" node.\r
+\r
+Although the AmlLib performs checks to a reasonable extent while modifying a\r
+definition block, these checks may not cover all aspects due to the complexity\r
+of the ASL/AML language. It is therefore recommended to review any operation\r
+performed, and validate the generated output.\r
+\r
+ Example: The serialized AML code could be validated by\r
+ - Saving the generated AML to a file and comparing with\r
+ a reference output.\r
+ or\r
+ - Disassemble the generated AML using the iASL compiler\r
+ and verifying the output.\r
+\r
+# Roadmap\r
+\r
The current implementation of the Configuration Manager populates the\r
platform information statically as a C structure. Further enhancements\r
to introduce runtime loading of platform information from a platform\r
Also support for generating SMBIOS tables is planned and will be added\r
subsequently.\r
\r
-Supported Platforms\r
--------------------\r
+# Supported Platforms\r
+\r
1. Juno\r
2. FVP Models\r
\r
-Build Instructions\r
-------------------\r
+# Build Instructions\r
+\r
1. Set path for the iASL compiler with support for generating a C header\r
file as output.\r
\r
>build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc\r
-t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**\r
\r
-Prerequisites\r
--------------\r
+# Prerequisites\r
+\r
Ensure that the latest ACPICA iASL compiler is used for building *Dynamic Tables Framework*.\r
*Dynamic Tables Framework* has been tested using the following iASL compiler version:\r
-[Version 20200717](https://www.acpica.org/node/183)*, dated 17 July, 2020.\r
+[Version 20200717](https://www.acpica.org/node/183), dated 17 July, 2020.\r
\r
\r
-Running CI builds locally\r
--------------------------\r
+#Running CI builds locally\r
\r
The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules:\r
\r
- use `stuart_build -c .pytool/CISettings.py -h` option to see help on additional options.\r
\r
\r
-Documentation\r
--------------\r
+# Documentation\r
\r
Refer to the following presentation from *UEFI Plugfest Seattle 2018*:\r
\r
projects / mirror_edk2.git / blobdiff