DynamicTablesPkg/Readme.md

   1 Dynamic Tables Framework
   2 ------------------------
   3
   4 Dynamic Tables Framework provides mechanisms to reduce the amount
   5 of effort required in porting firmware to new platforms. The aim is
   6 to provide an implementation capable of generating the firmware
   7 tables from an external source.  This is potentially a management
   8 node, either local or remote, or, where suitable, a file that might
   9 be generated from the system construction.  This initial release
  10 does not fully implement that - the configuration is held in local
  11 UEFI modules.
  12
  13 Feature Summary
  14 ---------------
  15 The dynamic tables framework is designed to generate standardised
  16 firmware tables that describe the hardware information at
  17 run-time. A goal of standardised firmware is to have a common
  18 firmware for a platform capable of booting both Windows and Linux
  19 operating systems.
  20
  21 Traditionally the firmware tables are handcrafted using ACPI
  22 Source Language (ASL), Table Definition Language (TDL) and
  23 C-code. This approach can be error prone and involves time
  24 consuming debugging. In addition, it may be desirable to configure
  25 platform hardware at runtime such as: configuring the number of
  26 cores available for use by the OS, or turning SoC features ON or
  27 OFF.
  28
  29 The dynamic tables framework simplifies this by providing a set
  30 of standard table generators, that are implemented as libraries.
  31 These generators query a platform specific component, the
  32 'Configuration Manager', to collate the information required
  33 for generating the tables at run-time.
  34
  35 The framework also provides the ability to implement custom/OEM
  36 generators; thereby facilitating support for custom tables. The
  37 custom generators can also utilize the existing standard generators
  38 and override any functionality if needed.
  39
  40 The framework currently implements a set of standard ACPI table
  41 generators for ARM architecture, that can generate Server Base Boot
  42 Requirement (SBBR) compliant tables. Although, the set of standard
  43 generators implement the functionality required for ARM architecture;
  44 the framework is extensible, and support for other architectures can
  45 be added easily.
  46
  47 The framework currently supports the following table generators for ARM:
  48 * DBG2 - Debug Port Table 2
  49 * DSDT - Differentiated system description table. This is essentially
  50          a RAW table generator.
  51 * FADT - Fixed ACPI Description Table
  52 * GTDT - Generic Timer Description Table
  53 * IORT - IO Remapping Table
  54 * MADT - Multiple APIC Description Table
  55 * MCFG - PCI Express memory mapped configuration space base address
  56          Description Table
  57 * SPCR - Serial Port Console Redirection Table
  58 * SSDT - Secondary System Description Table. This is essentially
  59          a RAW table generator.
  60
  61 Roadmap
  62 -------
  63 The current implementation of the Configuration Manager populates the
  64 platform information statically as a C structure. Further enhancements
  65 to introduce runtime loading of platform information from a platform
  66 information file is planned.
  67
  68 Also support for generating SMBIOS tables is planned and will be added
  69 subsequently.
  70
  71 Related Modules
  72 ---------------
  73
  74 ### ACPICA iASL compiler
  75 The RAW table generator, used to process the DSDT/SSDT files depends on
  76 the iASL compiler to convert the DSDT/SSDT ASL files to a C array containing
  77 the hex AML code. The "-tc" option of the iASL compiler has been enhanced to
  78 support generation of an AML hex file (C header) with a unique symbol name
  79 so that it is suitable for inclusion from a C source file.
  80
  81 Related Links
  82 --------------
  83
  84 <https://github.com/acpica/acpica.git>
  85
  86
  87 Supported Platforms
  88 -------------------
  89 1. Juno
  90 2. FVP Models
  91
  92 Build Instructions
  93 ------------------
  94 1. Set path for the iASL compiler with support for generating a C header
  95    file as output.
  96
  97 2. Set PACKAGES_PATH to point to the locations of the following repositories:
  98
  99 Example:
 100
 101 > set PACKAGES_PATH=%CD%\edk2;%CD%\edk2-platforms;
 102
 103   or
 104
 105 > export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms
 106
 107 3. To enable Dynamic tables framework the *'DYNAMIC_TABLES_FRAMEWORK'*
 108 option must be defined. This can be passed as a command line
 109 parameter to the edk2 build system.
 110
 111 Example:
 112
 113 >build -a AARCH64 -p Platform\ARM\JunoPkg\ArmJuno.dsc
 114    -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
 115
 116 or
 117
 118 >build -a AARCH64 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc
 119    -t GCC5 **-D DYNAMIC_TABLES_FRAMEWORK**
 120
 121 Prerequisites
 122 -------------
 123 ACPICA iASL compiler with the enhanced "-tc" option to support generation of
 124 AML hex (C header) files with unique symbol names.
 125
 126 A patch *'[iASL: Enhance the -tc option (create AML hex file in C)](https://github.com/acpica/acpica/commit/f9a88a4c1cd020b6a5475d63b29626852a0b5f37)'*, dated 16 March 2018 (2018-03-16),
 127 to enable this support has been integrated to the ACPICA source repository.
 128
 129 Ensure that the iASL compiler used for building *Dynamic Tables Framework* has this feature enabled.
 130
 131 This feature was made available in the *ACPICA Compiler update
 132 [Version 20180508](https://www.acpica.org/node/156)*, dated 8 May 2018 (2018-05-08).
 133
 134
 135 Running CI builds locally
 136 -------------------------
 137
 138 The TianoCore EDKII project has introduced Core CI infrastructure using TianoCore EDKII Tools PIP modules:
 139
 140    -  *[edk2-pytool-library](https://pypi.org/project/edk2-pytool-library)*
 141
 142    - *[edk2-pytool-extensions](https://pypi.org/project/edk2-pytool-extensions)*
 143
 144
 145 The instructions to setup the CI environment are in *'edk2\\.pytool\\Readme.md'*
 146
 147 ## Building DynamicTablesPkg with Pytools
 148
 149 1. [Optional] Create a Python Virtual Environment - generally once per workspace
 150
 151     ```
 152         python -m venv <name of virtual environment>
 153
 154         e.g. python -m venv edk2-ci
 155     ```
 156
 157 2. [Optional] Activate Virtual Environment - each time new shell/command window is opened
 158
 159     ```
 160         <name of virtual environment>/Scripts/activate
 161
 162         e.g. On a windows host PC run:
 163              edk2-ci\Scripts\activate.bat
 164     ```
 165 3. Install Pytools - generally once per virtual env or whenever pip-requirements.txt changes
 166
 167     ```
 168         pip install --upgrade -r pip-requirements.txt
 169     ```
 170
 171 4. Initialize & Update Submodules - only when submodules updated
 172
 173     ```
 174         stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
 175
 176         e.g. stuart_setup -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
 177     ```
 178
 179 5. Initialize & Update Dependencies - only as needed when ext_deps change
 180
 181     ```
 182         stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
 183
 184         e.g. stuart_update -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5
 185     ```
 186
 187 6. Compile the basetools if necessary - only when basetools C source files change
 188
 189     ```
 190         python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag>
 191     ```
 192
 193 7. Compile DynamicTablesPkg
 194
 195     ```
 196         stuart_build-c .pytool/CISettings.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH>
 197
 198         e.g. stuart_ci_build -c .pytool/CISettings.py TOOL_CHAIN_TAG=GCC5 -p DynamicTablesPkg -a AARCH64 --verbose
 199     ```
 200
 201     - use `stuart_build -c .pytool/CISettings.py -h` option to see help on additional options.
 202
 203
 204 Documentation
 205 -------------
 206
 207 Refer to the following presentation from *UEFI Plugfest Seattle 2018*:
 208
 209 [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)
 210