DynamicTablesPkg/Readme.md

   1 # Dynamic Tables Framework
   2
   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
  10 UEFI modules.
  11
  12 # Feature Summary
  13
  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
  18 operating systems.
  19
  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
  26 OFF.
  27
  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.
  33
  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.
  38
  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
  44 be added easily.
  45
  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
  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
  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)
  66 bytecode.
  67
  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
  71 block tables.
  72
  73 Dynamic AML introduces the following techniques:
  74 * AML Fixup
  75 * AML Codegen
  76 * AML Fixup + Codegen
  77
  78 ### AML Fixup
  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.
  82
  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.
  85
  86 ### AML Codegen
  87 AML Codegen employs generating small segments of AML code. The *AmlLib*
  88 library 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
 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.
 125
 126 ### AmlLib Library
 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.
 129
 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)
 133 Specification'.
 134
 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).
 140
 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.
 144
 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.
 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
 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.
 163
 164 Also support for generating SMBIOS tables is planned and will be added
 165 subsequently.
 166
 167 # Supported Platforms
 168
 169 1. Juno
 170 2. FVP Models
 171
 172 # Build Instructions
 173
 174 1. Set path for the iASL compiler with support for generating a C header
 175    file as output.
 176
 177 2. Set PACKAGES_PATH to point to the locations of the following repositories:
 178
 179 Example:
 180
 181 > set PACKAGES_PATH=%CD%\edk2;%CD%\edk2-platforms;
 182
 183   or
 184
 185 > export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms
 186
 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.
 190
 191 Example:
 192
 193 >build -a AARCH64 -p Platform\ARM\JunoPkg\ArmJuno.dsc
 194    -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
 195
 196 or
 197
 198 >build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc
 199    -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
 200
 201 # Prerequisites
 202
 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.
 206
 207
 208 #Running CI builds locally
 209
 210 The 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
 217 The instructions to setup the CI environment are in *'edk2\\.pytool\\Readme.md'*
 218
 219 ## Building DynamicTablesPkg with Pytools
 220
 221 1. [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
 229 2. [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     ```
 237 3. 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
 243 4. 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
 251 5. 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
 259 6. Compile the basetools if necessary - only when basetools C source files change
 260
 261     ```
 262         python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
 263     ```
 264
 265 7. 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
 278 Refer 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