├── CNAME ├── .gitignore ├── source ├── images │ ├── design.png │ ├── image2.jpg │ ├── image3.png │ ├── image4.PNG │ ├── image5.PNG │ ├── image6.PNG │ ├── image7.png │ ├── image8.png │ ├── image9.png │ ├── image1.jpeg │ ├── image10.png │ ├── image11.png │ ├── image12.png │ ├── image13.png │ ├── image14.png │ ├── image15.png │ ├── image16.jpg │ ├── image17.png │ ├── image18.png │ ├── image19.png │ ├── image20.png │ ├── image21.png │ └── POL_common_config_tool_diagram.png ├── substitutions.txt ├── 4_runtime.rst ├── index.rst ├── revision_history.rst ├── disclaimers.rst ├── 9_bootloader_payloads.rst ├── 6_debug.rst ├── _static │ └── custom.css ├── 8_scalable_fsp.rst ├── 1_terminology.rst ├── conf.py ├── 7_yaml_boot_configuration.rst ├── 5_security.rst └── 3_platform_orchestration_layer.rst ├── .travis.yml ├── Makefile ├── README.md └── make.bat /CNAME: -------------------------------------------------------------------------------- 1 | https://universalscalablefirmware.org/ -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build/ 2 | publish/ 3 | codeworkspace/ 4 | .vscode/ 5 | -------------------------------------------------------------------------------- /source/images/design.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/design.png -------------------------------------------------------------------------------- /source/images/image2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image2.jpg -------------------------------------------------------------------------------- /source/images/image3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image3.png -------------------------------------------------------------------------------- /source/images/image4.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image4.PNG -------------------------------------------------------------------------------- /source/images/image5.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image5.PNG -------------------------------------------------------------------------------- /source/images/image6.PNG: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image6.PNG -------------------------------------------------------------------------------- /source/images/image7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image7.png -------------------------------------------------------------------------------- /source/images/image8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image8.png -------------------------------------------------------------------------------- /source/images/image9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image9.png -------------------------------------------------------------------------------- /source/images/image1.jpeg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image1.jpeg -------------------------------------------------------------------------------- /source/images/image10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image10.png -------------------------------------------------------------------------------- /source/images/image11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image11.png -------------------------------------------------------------------------------- /source/images/image12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image12.png -------------------------------------------------------------------------------- /source/images/image13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image13.png -------------------------------------------------------------------------------- /source/images/image14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image14.png -------------------------------------------------------------------------------- /source/images/image15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image15.png -------------------------------------------------------------------------------- /source/images/image16.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image16.jpg -------------------------------------------------------------------------------- /source/images/image17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image17.png -------------------------------------------------------------------------------- /source/images/image18.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image18.png -------------------------------------------------------------------------------- /source/images/image19.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image19.png -------------------------------------------------------------------------------- /source/images/image20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image20.png -------------------------------------------------------------------------------- /source/images/image21.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/image21.png -------------------------------------------------------------------------------- /source/images/POL_common_config_tool_diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UniversalScalableFirmware/documentation/HEAD/source/images/POL_common_config_tool_diagram.png -------------------------------------------------------------------------------- /source/substitutions.txt: -------------------------------------------------------------------------------- 1 | .. |br| raw:: html .. force a line break in HTML output (blank lines needed here) 2 | 3 |
4 | .. |PN| replace:: Universal Payload 5 | 6 | 7 | -------------------------------------------------------------------------------- /source/4_runtime.rst: -------------------------------------------------------------------------------- 1 | .. _runtime: 2 | 3 | Runtime 4 | ======= 5 | 6 | .. _introduction-1: 7 | 8 | Introduction 9 | ------------ 10 | 11 | In addition to the boot-time POL, there are runtime variants. 12 | 13 | .. image:: images/image16.jpg 14 | :alt: POL and runtime 15 | :width: 6.5in 16 | :height: 3.65625in 17 | 18 | Figure 13: POL and runtime 19 | 20 | .. _acpi-1: 21 | 22 | ACPI 23 | ~~~~ 24 | 25 | PRM 26 | ^^^ 27 | 28 | UEFI Runtime 29 | ~~~~~~~~~~~~ 30 | 31 | SMM 32 | ~~~ 33 | 34 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | python: 3 | - "3.6" 4 | 5 | os: 6 | - linux 7 | dist: focal 8 | 9 | install: 10 | - pip install sphinx==1.8.1 docutils==0.14 sphinx-rtd-theme==0.4.2 sphinxcontrib-websupport==1.1.0 11 | 12 | before_install: 13 | - mkdir -p build 14 | - chmod 777 build 15 | - cd build 16 | - mkdir -p html 17 | - chmod 777 html 18 | - cd .. 19 | - touch ./build/html/.nojekyll 20 | 21 | script: 22 | - make html 23 | 24 | deploy: 25 | - provider: pages 26 | verbose: true 27 | skip_cleanup: true 28 | github_token: $GITHUB_TOKEN 29 | local_dir: ./build/html/ 30 | keep_history: true -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = source 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | .. Index file for the Universal Scalable Firmware Specification. This file must contain at least one "toctree" directive with links to the content files for this documentation, which should be in ReStructuredText format. The file names are to be listed without the file type extension. 2 | 3 | Universal Scalable Firmware Specification 4 | ========================================== 5 | 6 | .. toctree:: 7 | :name: frontmatter 8 | 9 | revision_history 10 | disclaimers 11 | 12 | .. toctree:: 13 | :name: content 14 | :maxdepth: 3 15 | :numbered: 16 | 17 | 1_terminology 18 | 2_universal_payload 19 | 3_platform_orchestration_layer 20 | 4_runtime 21 | 5_security 22 | 6_debug 23 | 7_yaml_boot_configuration 24 | 8_scalable_fsp 25 | 9_bootloader_payloads 26 | -------------------------------------------------------------------------------- /source/revision_history.rst: -------------------------------------------------------------------------------- 1 | .. _revision_history: 2 | 3 | Revision History 4 | ================== 5 | 6 | .. list-table:: 7 | :name: revision-history-table 8 | :widths: 15 65 20 9 | :header-rows: 1 10 | :class: longtable 11 | 12 | * 13 | - Revision 14 | - Description 15 | - Date 16 | * 17 | - 0.7 18 | - Initial draft 19 | - October 2021 20 | * 21 | - 0.9 22 | - | Update Security HOB for payload interface 23 | | Add details on post-quantum cryptography (PQC) and crypto agility 24 | | Reference Integrity Manifest (RIM) definition for universal payload 25 | | Update measurement information 26 | | Detail alternative input structure of CBOR 27 | | Add VaultBoot info 28 | | Clean-up of POL section 29 | - October 2022 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | This documentation is written in **RST (ReStructuredText)** format and can be built into web pages 2 | using Sphinx rendered with an HTML theme (sphinx-rtd-theme). The HTML pages are then hosted using 3 | GitHub Pages service. 4 | 5 | The pages are hosted @ https://universalscalablefirmware.github.io/documentation/ 6 | 7 | Getting Started 8 | 9 | In order to build the web site content from the source code, install **additional** python packages: 10 | 11 | **pip install sphinx docutils sphinx-rtd-theme sphinxcontrib-websupport** 12 | 13 | 14 | To make html: 15 | 16 | **make html** 17 | 18 | The generated HTML file is located in 'build'. 19 | 20 | 21 | Submit changes (for contributors) 22 | Follow the github workflow to submit your pull request. 23 | 24 | Travis-CI is used to build the html files and the html files are pushed into a 25 | gh-pages branch which is then rendered by GitHub Pages. 26 | 27 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=source 11 | set BUILDDIR=build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /source/disclaimers.rst: -------------------------------------------------------------------------------- 1 | .. _disclaimers: 2 | 3 | Notices and Disclaimers 4 | ========================= 5 | 6 | This version 0.7 specification is under development and is not final. 7 | 8 | The content of this Universal Scalable Firmware (USF) Specification is licensed under the Creative Commons Attribution 4.0 International License. Unless stated otherwise, the sample code examples in this document are released to you under the BSD license. 9 | 10 | USF is intended to be an open specification and we encourage you to help us make it better. Your feedback is optional, but to enable Intel to incorporate any feedback you may provide to this specification, please submit your feedback under the terms and conditions below. 11 | 12 | Any contribution of your feedback to the USF Specification does not prohibit you from also contributing your feedback directly to other standard bodies under their respective policies. By opening an issue, providing feedback, or otherwise contributing to the specification, you agree that Intel will be free to use, disclose, reproduce, modify, license, or otherwise distribute your feedback at its sole discretion without any obligations or restrictions of any kind, including without limitation, intellectual property rights or licensing obligations. 13 | 14 | This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice. 15 | 16 | Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries. 17 | 18 | \* Other names and brands may be claimed as the property of others. 19 | 20 | © Copyright 2021 Intel Corporation -------------------------------------------------------------------------------- /source/9_bootloader_payloads.rst: -------------------------------------------------------------------------------- 1 | .. _bootloader-payloads: 2 | 3 | Bootloader Payloads 4 | =================== 5 | 6 | There are a plurality of payload implementations. Below provides a 7 | summary. 8 | 9 | References 10 | ---------- 11 | 12 | .. _bootloader-payloads-1: 13 | 14 | Bootloader Payloads – 15 | ~~~~~~~~~~~~~~~~~~~~~ 16 | 17 | - Slimboot payload doc 18 | https://slimbootloader.github.io/developer-guides/payload.html 19 | 20 | - coreboot payloads https://www.coreboot.org/Payloads 21 | 22 | - UEFI payload 23 | https://github.com/tianocore/edk2/tree/master/UefiPayloadPkg 24 | 25 | - LinuxBoot https://www.linuxboot.org/ 26 | 27 | - PI 1.7 https://uefi.org/specifications 28 | 29 | - VaultBoot https://github.com/hardenedvault/vaultboot 30 | 31 | OS/Hv interfaces 32 | ~~~~~~~~~~~~~~~~ 33 | 34 | Kernel load protocol doc 35 | https://www.kernel.org/doc/Documentation/x86/boot.txt 36 | 37 | - UEFI 2.9 https://uefi.org/specifications 38 | 39 | - ACPI 6.3 https://uefi.org/specifications 40 | 41 | - PRM https://github.com/tianocore/edk2-staging/tree/PRMCaseStudy 42 | 43 | Platform implementations 44 | ~~~~~~~~~~~~~~~~~~~~~~~~ 45 | 46 | - EDKII `www.tianocore.org `__ (also 47 | possible payload) 48 | 49 | - EDKII min platform 50 | https://edk2-docs.gitbook.io/edk-ii-minimum-platform-specification/ 51 | 52 | - coreboot `https://www.coreboot.org `__ 53 | 54 | - slimboot https://slimbootloader.github.io/ 55 | 56 | - u-boot https://www.denx.de/wiki/U-Boot (also possible payload) 57 | 58 | - oreboot https://github.com/oreboot/oreboot 59 | 60 | .. _security-1: 61 | 62 | Security 63 | ~~~~~~~~ 64 | 65 | - SPDM 66 | https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_0.99a.pdf 67 | 68 | - Building Secure Firmware 69 | https://link.springer.com/book/10.1007/978-1-4842-6106-4 70 | 71 | .. |image1| image:: images/image11.png 72 | :width: 6.375in 73 | :height: 0.60612in 74 | .. |image14| image:: images/image14.png 75 | :width: 6.5in 76 | :height: 1.82431in 77 | -------------------------------------------------------------------------------- /source/6_debug.rst: -------------------------------------------------------------------------------- 1 | .. _debug-chapter: 2 | 3 | Debug 4 | ===== 5 | 6 | Debug Overview 7 | -------------- 8 | 9 | In this specification, the word ‘trace’ is used for any message that is 10 | generated by BIOS components for debug purposes. These typically include 11 | postcodes, status codes and string messages. 12 | 13 | The general philosophy is to provide a simple and ubiquitous solution 14 | that supports a range of debug solutions to help with BIOS debug and 15 | tracing needs. 16 | 17 | Requirements 18 | ~~~~~~~~~~~~ 19 | 20 | This section summarizes a set of requirements to ensure common debug and 21 | trace features are supported by all modules. 22 | 23 | Trace interfaces 24 | ^^^^^^^^^^^^^^^^ 25 | 26 | - BIOS shall support sending trace messages to all BIOS accessible HW 27 | interfaces on the platform. 28 | 29 | - BIOS shall support enabling and disabling the trace interfaces 30 | individually. 31 | 32 | - BIOS modules don’t control which trace output is used. 33 | 34 | - SAL layer shall implement a middleware trace class which routes 35 | the messages to enabled interfaces such as NPK or UART. Enabled 36 | trace interfaces may be selected at build time but run time 37 | selection is preferred. 38 | 39 | - Enabled trace interfaces shall be initialized once before the first 40 | trace message is sent. 41 | 42 | Trace data 43 | ^^^^^^^^^^ 44 | 45 | - BIOS trace to NPK shall follow MIPI Sys-T specification catalog 46 | format and BIOS error levels shall comply to Sys-T definition 47 | matching verbosity level definition at bit level. 48 | 49 | - BIOS build shall output a catalog dictionary file for decoding the 50 | trace. 51 | 52 | - Generating the dictionary file shall not exceed BIOS build time 53 | requirements. 54 | 55 | - BIOS module trace shall comply to Intel Trace Specification. 56 | <*provide link if available>* 57 | 58 | - BIOS shall support both build time and boot time trace verbosity 59 | filtering. 60 | 61 | - Enabling BIOS trace feature shall meet release build binary size and 62 | performance requirements. 63 | 64 | Design 65 | ~~~~~~ 66 | 67 | Source level debugging 68 | ~~~~~~~~~~~~~~~~~~~~~~ 69 | 70 | -------------------------------------------------------------------------------- /source/_static/custom.css: -------------------------------------------------------------------------------- 1 | /* -- Extra CSS styles for SOF content (RTD theme) ----------------------- */ 2 | 3 | /* make the page width fill the window */ 4 | .wy-nav-content { 5 | max-width: none; 6 | } 7 | 8 | /* (temporarily) add an under development tagline to the bread crumb 9 | .wy-breadcrumbs::after { 10 | content: " (Content under development)"; 11 | background-color: #FFFACD; 12 | color: red; 13 | font-weight: bold; 14 | } 15 | */ 16 | 17 | /* code block highlight color in rtd changed to lime green, no no no */ 18 | 19 | .rst-content tt.literal, .rst-content code.literal, .highlight { 20 | background: #f0f0f0; 21 | } 22 | .rst-content tt.literal, .rst-content code.literal { 23 | color: #000000; 24 | } 25 | 26 | /* Make the version number more visible */ 27 | .wy-side-nav-search>div.version { 28 | color: rgba(255,255,255,1); 29 | } 30 | 31 | /* squish the space between a paragraph before a list */ 32 | div > p + ul, div > p + ol { 33 | margin-top: -20px; 34 | } 35 | 36 | /* add some space before the figure caption */ 37 | p.caption { 38 | # border-top: 1px solid; 39 | margin-top: 1em; 40 | } 41 | 42 | /* add a colon after the figure/table number (before the caption) */ 43 | span.caption-number::after { 44 | content: ": "; 45 | } 46 | 47 | p.extrafooter { 48 | text-align: right; 49 | margin-top: -36px; 50 | } 51 | 52 | table.align-center { 53 | display: table !important; 54 | } 55 | 56 | 57 | .code-block-caption { 58 | color: #000; 59 | font: italic 85%/1 arial,sans-serif; 60 | padding: 1em 0; 61 | text-align: center; 62 | } 63 | 64 | /* make .. hlist:: tables fill the page */ 65 | table.hlist { 66 | width: 95% !important; 67 | } 68 | 69 | /* override rtd theme white-space no-wrap in table heading and content */ 70 | th,td { 71 | white-space: normal !important; 72 | } 73 | 74 | /* tweak for doxygen-generated API headings (for RTD theme) */ 75 | .rst-content dl.group>dt, .rst-content dl.group>dd>p { 76 | display:none !important; 77 | } 78 | .rst-content dl.group { 79 | margin: 0 0 12px 0px; 80 | } 81 | .rst-content dl.group>dd { 82 | margin-left: 0 !important; 83 | } 84 | .rst-content p.breathe-sectiondef-title { 85 | text-decoration: underline; /* for API sub-headings */ 86 | font-size: 1.25rem; 87 | font-weight: bold; 88 | margin-bottom: 12px; 89 | } 90 | .rst-content div.breathe-sectiondef { 91 | padding-left: 0 !important; 92 | } 93 | -------------------------------------------------------------------------------- /source/8_scalable_fsp.rst: -------------------------------------------------------------------------------- 1 | .. _scalable-fsp: 2 | 3 | Scalable FSP 4 | ============ 5 | 6 | The scalable FSP is an evolution of the Intel Firmware Support Package 7 | detailed at `www.intel.com/fsp `__. 8 | 9 | Interfaces 10 | ---------- 11 | 12 | | There are a plurality of interfaces to the FSP, including C and 13 | RUST-based. 14 | | These interfaces allow for the POL to have a generic means by which to 15 | interface with the scalable FSP. 16 | 17 | C API’s include 18 | 19 | For EDKII - 20 | 21 | https://github.com/tianocore/edk2/tree/master/IntelFsp2WrapperPkg/Include/Library 22 | 23 | `FspMeasurementLib.h `__ 24 | 25 | `FspWrapperApiLib.h `__ 26 | 27 | `FspWrapperApiTestLib.h `__ 28 | 29 | `FspWrapperHobProcessLib.h `__ 30 | 31 | `FspWrapperPlatformLib.h `__ 32 | 33 | Details of some of the interfaces can be found in 34 | https://www.intel.com/content/dam/develop/external/us/en/documents/a-tour-beyond-bios-using-the-intel-firmware-support-package-with-the-efi-developer-kit-ii-fsp2-0-820293.pdf. 35 | 36 | RUST variants include 37 | 38 | https://github.com/jyao1/rust-firmware/tree/master/rust-fsp-wrapper 39 | 40 | coreboot FSP 41 | 42 | https://github.com/coreboot/coreboot/tree/master/src/drivers/intel/fsp2_0 43 | 44 | `api.h `__ 45 | 46 | `debug.h `__ 47 | 48 | `graphics.h `__ 49 | 50 | `info_header.h `__ 51 | 52 | `soc_binding.h `__ 53 | 54 | `upd.h `__ 55 | 56 | `util.h `__ 57 | 58 | Additional details can be found in 59 | https://github.com/coreboot/coreboot/tree/master/Documentation/soc/intel/fsp 60 | and https://link.springer.com/chapter/10.1007/978-1-4842-0070-4_4 61 | 62 | sFSP interactions 63 | ----------------- 64 | 65 | The Intel Firmware Support Package has various evolutions for the Next 66 | Generation Firmware program. These are tentatively described by the 67 | specification evolution. 68 | 69 | Since the POL uses FSP as its SOC abstraction, the POL considerations 70 | for the various permutations of the FSP are described below. 71 | 72 | FSP 2.2 73 | ~~~~~~~ 74 | 75 | Multiple notifications, bootloader debug/status code + FSP 2.1 76 | 77 | FSP 2.3 78 | ~~~~~~~ 79 | 80 | FSP 2.2, large HOB support, versioning update 81 | 82 | FSP 2.next.next 83 | ~~~~~~~~~~~~~~~ 84 | 85 | FSP2.3, SOC ACPI Abstraction, FSP-V, 64-bit, SMM loading 86 | 87 | FSP 3.0 or FSP2.next.next 88 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 89 | 90 | FSP-at-Reset (“bootable FSP”), FSP-R (FSP-Runtime) 91 | 92 | -------------------------------------------------------------------------------- /source/1_terminology.rst: -------------------------------------------------------------------------------- 1 | .. image:: images/image1.jpeg 2 | :width: 6in 3 | :height: 3.5in 4 | 5 | ================================================= 6 | Universal Scalable Firmware (USF) Specification 7 | ================================================= 8 | 9 | **Version 0.7** 10 | 11 | **October 2021** 12 | 13 | © Copyright 2021 - Document content licensed under a Creative Commons Attribution 4.0 International license 14 | 15 | 16 | Terminology 17 | =========== 18 | 19 | Early personal computers used a "Basic Input/Output System" (BIOS) to boot the system and provide communication between hardware and the Operating System (OS). Hence the term BIOS has come to be used as a generic term for all computer firmware, but this is not technically correct. In the 1990s, Intel developed the "Extensible Firmware Interface" (EFI) to provide more features than legacy BIOS, and this eventually evolved into the `Unified Extensible Firmware Interface (UEFI) `_ maintained by the `Unified EFI Forum, Inc. `_ Most modern PCs ship with some variation of UEFI firmware, and UEFI is widely supported by both commercial and open source operating systems. Both TianoCore EDKII and Intel's Minimum Platform Architecture (MPA or "min platform") are implementations based on the UEFI standard for system firmware. 20 | 21 | This Specification uses "firmware" or "system firmware" interchangeably to indicate a computer's pre-boot environment. "BIOS" may also be used as a generic term, and should not be considered a reference to legacy firmware implementations. 22 | 23 | 24 | Motivation for Universal Scalable Firmware 25 | ============================================ 26 | 27 | Firmware implementations such as TianoCore EDKII have served the industry well for a couple of decades now. But issues such as the following are now driving the need for new system firmware standards: 28 | 29 | - Growing demands from customers requiring firmware flexibility to easily support various bootloaders. 30 | 31 | - Fragmented Tianocore/EDKII/min-platform/FSP solutions are leading to higher development and validation cost. 32 | 33 | - Closely coupled Platform/SOC/IP level firmware design & code are resulting in low reusability and long time to market (TTM). 34 | 35 | - High complexity with key modules like Memory Reference Code (MRC) and security result in quality, test, and debug challenges. 36 | 37 | - Limited modularity. 38 | 39 | - Lack of unified/common interfaces to support platform XPUs (CPU, dGPU, etc). 40 | 41 | The goal of developing the Universal Scalable Firmware standard is to evolve modularity to scale for an IP firmware development model, with an emphasis on simplicity, scalability, debuggability, readability and determinism. 42 | 43 | 44 | Simplicity, Determinisim and Debuggability 45 | ============================================ 46 | 47 | The three attributes of Simplicity, Determinism and Debuggability go together. Firmware plays a major role in debugging hardware, silicon features, and various technologies such as Security, Power Management, IO, Virtualization, RAS, etc. Hence firmware should lend itself to readability and determining the sequence of operations by reading the source code. Firmware is the abstraction layer and often has to deal with unstable hardware and silicon workarounds. A simple debug-friendly infrastructure (hardware debug, not just software) is called for. Today’s platform and SoC complexity calls for a model of replaceable IP Modules, with the associated firmware components traveling with that IP. 48 | 49 | USF Layers 50 | ============ 51 | 52 | The layers of Universal Scalable Firmware are described in the following diagram. 53 | 54 | .. image:: images/image2.jpg 55 | :alt: A picture containing graphical user interface 56 | :width: 6in 57 | :height: 6.25in 58 | 59 | **Figure 1: USF stack** 60 | 61 | 62 | Starting from the top of this stack, we have the following items. 63 | 64 | OS Interfaces 65 | ---------------- 66 | 67 | These are well-known interfaces such as ACPI, UEFI, Kexec, or Multi-boot, that provide a means to interact with pre-OS and runtimes. 68 | 69 | 70 | Universal Payload 71 | ------------------ 72 | 73 | A Universal Payload API for different OS payloads such as UEFI, LinuxBoot, VaultBoot and ACRN embedded hypervisor, plus support for various bootloaders such as tianocore/EDKII, coreboot, slim bootloader, and u-boot. 74 | 75 | 76 | Platform Orchestration Layer (POL) 77 | ------------------------------------ 78 | 79 | Simplified ACPI support, common libraries for various bootloaders & Rust language, standard binary configuration through YAML, support for FW attestation, authentication, measurement, and modern update. 80 | 81 | 82 | Scalable Firmware Support Package (sFSP) 83 | ------------------------------------------ 84 | 85 | Scalable Firmware Support Package (sFSP) support for 64-bit reset vector, SMM encapsulation, various domain modules, authentication, unified configuration, and SOC level validation. 86 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Universal Scalable Firmware documentation build configuration file, created by 4 | # sphinx-quickstart on Tue Aug 7 13:04:00 2020. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | 18 | # If extensions (or modules to document with autodoc) are in another directory, 19 | # add these directories to sys.path here. If the directory is relative to the 20 | # documentation root, use os.path.abspath to make it absolute, like shown here. 21 | #sys.path.insert(0, os.path.abspath('.')) 22 | 23 | # -- General configuration ------------------------------------------------ 24 | 25 | # If your documentation needs a minimal Sphinx version, state it here. 26 | #needs_sphinx = '1.0' 27 | 28 | # Add any Sphinx extension module names here, as strings. They can be 29 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 30 | # ones. 31 | extensions = [ 32 | 'sphinx.ext.ifconfig', 33 | 'sphinx.ext.graphviz', 34 | 'sphinx.ext.todo', 35 | ] 36 | 37 | # Add any paths that contain templates here, relative to this directory. 38 | templates_path = ['_templates'] 39 | 40 | # The suffix(es) of source filenames. 41 | # You can specify multiple suffix as a list of string: 42 | # source_suffix = ['.rst', '.md'] 43 | source_suffix = '.rst' 44 | 45 | # The encoding of source files. 46 | #source_encoding = 'utf-8-sig' 47 | 48 | # The master toctree document. 49 | master_doc = 'index' 50 | 51 | # General information about the project. 52 | project = u'Universal Scalable Firmware (USF)' 53 | copyright = u'Content on this site is licensed under a Creative Commons Attribution 4.0 International license' 54 | author = u'Universal Scalable Firmware Project Team' 55 | 56 | # The version info for the project you're documenting, acts as replacement for 57 | # |version| and |release|, also used in various other places throughout the 58 | # built documents. 59 | # 60 | # The short X.Y version. 61 | version = u'' 62 | # The full version, including alpha/beta/rc tags. 63 | release = u'' 64 | 65 | # The language for content autogenerated by Sphinx. Refer to documentation 66 | # for a list of supported languages. 67 | # 68 | # This is also used if you do content translation via gettext catalogs. 69 | # Usually you set "language" from the command line for these cases. 70 | language = 'en' 71 | 72 | # There are two options for replacing |today|: either, you set today to some 73 | # non-false value, then it is used: 74 | #today = '' 75 | # Else, today_fmt is used as the format for a strftime call. 76 | #today_fmt = '%B %d, %Y' 77 | 78 | # List of patterns, relative to source directory, that match files and 79 | # directories to ignore when looking for source files. 80 | exclude_patterns = ['internal'] 81 | if tags.has('internal'): 82 | exclude_patterns = [] 83 | 84 | # The reST default role (used for this markup: `text`) to use for all 85 | # documents. 86 | #default_role = None 87 | 88 | # If true, '()' will be appended to :func: etc. cross-reference text. 89 | #add_function_parentheses = True 90 | 91 | # If true, the current module name will be prepended to all description 92 | # unit titles (such as .. function::). 93 | #add_module_names = True 94 | 95 | # If true, sectionauthor and moduleauthor directives will be shown in the 96 | # output. They are ignored by default. 97 | #show_authors = False 98 | 99 | # The name of the Pygments (syntax highlighting) style to use. 100 | pygments_style = 'sphinx' 101 | 102 | # A list of ignored prefixes for module index sorting. 103 | #modindex_common_prefix = [] 104 | 105 | # If true, keep warnings as "system message" paragraphs in the built documents. 106 | #keep_warnings = False 107 | 108 | # If true, `todo` and `todoList` produce output, else they produce nothing. 109 | #todo_include_todos = True 110 | 111 | rst_epilog = """ 112 | .. include:: /substitutions.txt 113 | """ 114 | 115 | # -- Options for HTML output ---------------------------------------------- 116 | 117 | # The theme to use for HTML and HTML Help pages. See the documentation for 118 | # a list of builtin themes. 119 | html_theme = 'sphinx_rtd_theme' 120 | 121 | # Theme options are theme-specific and customize the look and feel of a theme 122 | # further. For a list of options available for each theme, see the 123 | # documentation. 124 | #html_theme_options = {} 125 | 126 | # Add any paths that contain custom themes here, relative to this directory. 127 | #html_theme_path = [] 128 | 129 | # The name for this set of Sphinx documents. If None, it defaults to 130 | # " v documentation". 131 | #html_title = None 132 | 133 | # A shorter title for the navigation bar. Default is the same as html_title. 134 | #html_short_title = None 135 | 136 | # The name of an image file (relative to this directory) to place at the top 137 | # of the sidebar. 138 | #html_logo = 'Payload.png' 139 | 140 | # The name of an image file (relative to this directory) to use as a favicon of 141 | # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 142 | # pixels large. 143 | #html_favicon = 'payload_32x32_icon.ico' 144 | 145 | # Add any paths that contain custom static files (such as style sheets) here, 146 | # relative to this directory. They are copied after the builtin static files, 147 | # so a file named "default.css" will overwrite the builtin "default.css". 148 | html_static_path = ['_static'] 149 | 150 | def setup(app): 151 | app.add_css_file("custom.css") 152 | 153 | # Add any extra paths that contain custom files (such as robots.txt or 154 | # .htaccess) here, relative to this directory. These files are copied 155 | # directly to the root of the documentation. 156 | #html_extra_path = [] 157 | 158 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 159 | # using the given strftime format. 160 | html_last_updated_fmt = '%b %d, %Y' 161 | 162 | # If true, SmartyPants will be used to convert quotes and dashes to 163 | # typographically correct entities. 164 | #html_use_smartypants = True 165 | 166 | # Custom sidebar templates, maps document names to template names. 167 | #html_sidebars = {} 168 | 169 | # Additional templates that should be rendered to pages, maps page names to 170 | # template names. 171 | #html_additional_pages = {} 172 | 173 | # If false, no module index is generated. 174 | #html_domain_indices = True 175 | 176 | # If false, no index is generated. 177 | #html_use_index = True 178 | 179 | # If true, the index is split into individual pages for each letter. 180 | #html_split_index = False 181 | 182 | # If true, links to the reST sources are added to the pages. 183 | html_show_sourcelink = False 184 | 185 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 186 | #html_show_sphinx = True 187 | 188 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 189 | #html_show_copyright = True 190 | 191 | # If true, an OpenSearch description file will be output, and all pages will 192 | # contain a tag referring to it. The value of this option must be the 193 | # base URL from which the finished HTML is served. 194 | #html_use_opensearch = '' 195 | 196 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 197 | #html_file_suffix = None 198 | 199 | # Language to be used for generating the HTML full-text search index. 200 | # Sphinx supports the following languages: 201 | # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' 202 | # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' 203 | #html_search_language = 'en' 204 | 205 | # A dictionary with options for the search language support, empty by default. 206 | # Now only 'ja' uses this config value 207 | #html_search_options = {'type': 'default'} 208 | 209 | # The name of a javascript file (relative to the configuration directory) that 210 | # implements a search results scorer. If empty, the default will be used. 211 | #html_search_scorer = 'scorer.js' 212 | 213 | # Output file base name for HTML help builder. 214 | htmlhelp_basename = 'UniversalScalableFirmwaredoc' 215 | 216 | # -- Options for LaTeX output --------------------------------------------- 217 | 218 | latex_elements = { 219 | # The paper size ('letterpaper' or 'a4paper'). 220 | #'papersize': 'letterpaper', 221 | 222 | # The font size ('10pt', '11pt' or '12pt'). 223 | #'pointsize': '10pt', 224 | 225 | # Additional stuff for the LaTeX preamble. 226 | #'preamble': '', 227 | 228 | # Latex figure (float) alignment 229 | #'figure_align': 'htbp', 230 | } 231 | 232 | # Grouping the document tree into LaTeX files. List of tuples 233 | # (source start file, target name, title, 234 | # author, documentclass [howto, manual, or own class]). 235 | latex_documents = [ 236 | (master_doc, 'UniversalScalableFirmware.tex', u'Universal Scalable Firmware Documentation', 237 | u'Universal Scalable Firmware Team', 'manual'), 238 | ] 239 | 240 | # The name of an image file (relative to this directory) to place at the top of 241 | # the title page. 242 | #latex_logo = None 243 | 244 | # For "manual" documents, if this is true, then toplevel headings are parts, 245 | # not chapters. 246 | #latex_use_parts = False 247 | 248 | # If true, show page references after internal links. 249 | #latex_show_pagerefs = False 250 | 251 | # If true, show URL addresses after external links. 252 | #latex_show_urls = False 253 | 254 | # Documents to append as an appendix to all manuals. 255 | #latex_appendices = [] 256 | 257 | # If false, no module index is generated. 258 | #latex_domain_indices = True 259 | 260 | 261 | # -- Options for manual page output --------------------------------------- 262 | 263 | # One entry per manual page. List of tuples 264 | # (source start file, name, description, authors, manual section). 265 | man_pages = [ 266 | (master_doc, 'UniversalScalableFirmware', u'Universal Scalable Firmware Documentation', 267 | [author], 1) 268 | ] 269 | 270 | # If true, show URL addresses after external links. 271 | #man_show_urls = False 272 | 273 | 274 | # -- Options for Texinfo output ------------------------------------------- 275 | 276 | # Grouping the document tree into Texinfo files. List of tuples 277 | # (source start file, target name, title, author, 278 | # dir menu entry, description, category) 279 | texinfo_documents = [ 280 | (master_doc, 'UniversalScalableFirmware', u'Universal Scalable Firmware Documentation', 281 | author, 'UniversalScalableFirmware', 'One line description of project.', 282 | 'Miscellaneous'), 283 | ] 284 | 285 | # Documents to append as an appendix to all manuals. 286 | #texinfo_appendices = [] 287 | 288 | # If false, no module index is generated. 289 | #texinfo_domain_indices = True 290 | 291 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 292 | #texinfo_show_urls = 'footnote' 293 | 294 | # If true, do not generate a @detailmenu in the "Top" node's menu. 295 | #texinfo_no_detailmenu = False 296 | -------------------------------------------------------------------------------- /source/7_yaml_boot_configuration.rst: -------------------------------------------------------------------------------- 1 | .. _yaml-format-boot-configuration: 2 | 3 | YAML Format Boot Configuration 4 | ================================== 5 | 6 | .. _introduction-2: 7 | 8 | Introduction 9 | ------------ 10 | 11 | This document describes the format of the YAML based boot setting file 12 | used to specify features, settings, and tool display information to the 13 | Intel Firmware Support Package (FSP) and tools like Config Editor. It 14 | further describes the structure and content of YAML format files, which 15 | can simplify the configuration of a static binary and during dynamic 16 | boot process. 17 | 18 | Target Audience 19 | --------------- 20 | 21 | This document is intended for person creating and using firmware images. 22 | It is most likely of interest if a developer needs to create customized 23 | feature and expose binary settings for delivery to customers, or that a 24 | new SOC device is being enabled. 25 | 26 | Configuration Description (YAML) Explained 27 | ------------------------------------------ 28 | 29 | The declarations required to build the configuration data blobs and the 30 | header files are provided in a configuration description file. This file 31 | uses the **YAML** syntax. 32 | 33 | **YAML** (`https://yaml.org/ `__) is a data 34 | serialization language designed to be human-friendly and work well with 35 | modern programming languages. A quick syntax reference can be found here 36 | - https://yaml.org/refcard.html 37 | 38 | Configuration **YAML** files will be processed by configuration tools 39 | like GenCfgData, CfgDataTool, CfgDataStitch in order to generate the 40 | configuration header files and binary blobs. 41 | 42 | The main platform configuration file is specified in CfgDataDef.yaml. 43 | Please note that you may find many YAML files. However, only 44 | CfgDataDef.yaml is the primary file used for the platform configuration, 45 | and other sub YAML files will be included by the primary YAML file to 46 | provide component specific configuration. 47 | 48 | An example configuration file in YAML syntax is provided in Figure 15 49 | below. 50 | 51 | .. image:: images/image17.png 52 | :width: 6.26042in 53 | :height: 4.6291in 54 | 55 | Figure 14 56 | 57 | File Layout 58 | ----------- 59 | 60 | The configuration YAML file has a basic organization as below 61 | 62 | - **Variable** declarations 63 | 64 | - **Template** declarations 65 | 66 | - **Configuration** declarations 67 | 68 | Meta-Data Markers 69 | ~~~~~~~~~~~~~~~~~ 70 | 71 | The configuration YAML files uses the $ sign as meta-data indicator. 72 | This is used by the SBL configuration parsing tools. 73 | 74 | The current specification version supports the following meta-data 75 | markers. 76 | 77 | $ACTION 78 | ^^^^^^^ 79 | 80 | **$ACTION** is a meta-data marker and is followed by a YAML mapping node 81 | that contains some meta-data. The following attributes are supported 82 | currently. 83 | 84 | PAGE 85 | ^^^^ 86 | 87 | PAGE is used to declare a list of pages used in the GUI. 88 | 89 | PAGE is also used to define the display scope for a configuration 90 | parameter and can be applied for individual configuration parameters. 91 | 92 | In this way multiple configuration parameters can be grouped to be 93 | visually displayed together in the same page in GUI. 94 | 95 | Since the page: value(s) is a meta-data used by the tool (not a 96 | configuration option itself), it has be preceded by the **$ACTION** 97 | node. 98 | 99 | **Format:** 100 | 101 | page: PageId1:ParentPageId1:PageTxetDescription1, PageId2: 102 | ParentPageId2:PageTxetDescription2 103 | 104 | If a root page needs to be defined, the ParentPageId could be empty as 105 | below: 106 | 107 | page: RootPageId::RootPageTxetDescription 108 | 109 | .. image:: images/image18.png 110 | :width: 6.6928in 111 | :height: 3.375in 112 | 113 | Figure 15 114 | 115 | $STRUCT 116 | ^^^^^^^ 117 | 118 | The STRUCT directive is used to indicate a nested structure within a 119 | configuration structure. 120 | 121 | For example, consider the nested structure below: 122 | 123 | typedef struct { 124 | 125 | UINT32 Acpi : 1; 126 | 127 | UINT32 MeasuredBoot : 1; 128 | 129 | UINT32 Vt : 1; 130 | 131 | UINT32 eMMCTuning : 1; 132 | 133 | UINT32 DciDebug : 1; 134 | 135 | UINT32 Rsvd1 : 27; 136 | 137 | } FEATURES_DATA; 138 | 139 | typedef struct { 140 | 141 | FEATURES_DATA Features; 142 | 143 | } FEATURES_CFG_DATA; 144 | 145 | The following example shows this declaration using a $STRUCT as shown 146 | below 147 | 148 | .. image:: images/image19.png 149 | :width: 6.21875in 150 | :height: 6.18154in 151 | 152 | Figure 16 153 | 154 | - $ACTION : 155 | 156 | page : FEATURES:PLT:"Features" 157 | 158 | - FEATURES_CFG_DATA : 159 | 160 | - !expand { CFGHDR_TMPL : [ FEATURES_CFG_DATA, 0x310, 0, 0 ] } 161 | 162 | - !expand { FEATURES_TMPL : [ 0x0000001F ] } 163 | 164 | YAML Tags 165 | ~~~~~~~~~ 166 | 167 | YAML represents type information of native data structures with a simple 168 | identifier, called a tag. Explicit typing is denoted with a tag using 169 | the exclamation point (“!”) symbol. The following application-specific 170 | local tags are used. 171 | 172 | !INCLUDE 173 | ^^^^^^^^ 174 | 175 | Configuration declarations may be logically organized in multiple files. 176 | Additional YAML files are included in the CfgDataDef.yaml using 177 | “!include” tag. 178 | 179 | *!include* statement may appear within any section. A relative file path 180 | is required to specific the file path to be included. This path should 181 | be relative to the current YAML file containing the *!include* 182 | statement. The file content to be included must match the content type 183 | of the current section definition, contain complete sections, or 184 | combination of both. 185 | 186 | Statements in *!include* files must not break the integrity of the Yaml 187 | file, the included file is read by parsing tools in the exact position 188 | of the file, and is functionally equivalent to copying contents of the 189 | included file and pasting them into Yaml. The indentation of the 190 | included file will be adjusted automatically so that the top-level 191 | indentation in the included file has the same level as the *!include* 192 | statement line. line. 193 | 194 | **Format:** 195 | 196 | - !include RelativeFilePath 197 | 198 | **Example:** 199 | 200 | - !include Platform/CommonBrdPkg/CfgData/CfgData.yaml 201 | 202 | - !include Platform/Rvp7Pkg/CfgData/CfgData_GPIO.yaml 203 | 204 | !EXPAND 205 | ^^^^^^^ 206 | 207 | “!expand” tag is used for declaring a configuration option defined by a 208 | template 209 | (`Template `__). 210 | *!expand* tag can only appear in *template* or *configs* section. 211 | 212 | **Format:** 213 | 214 | - !expand { CfgTmplName: [Param1, Param2, ….] } 215 | 216 | Using the CFGHDR_TMPL template example: 217 | 218 | CFGHDR_TMPL: > 219 | 220 | - CfgHeader : 221 | 222 | length : 0x04 223 | 224 | value : {0x01:2b, ((_LENGTH_$(1)_)/4):10b, $(3):4b, $(4):4b, $(2):12b} 225 | 226 | - CondValue : 227 | 228 | length : 0x04 229 | 230 | value : 0x00000000 231 | 232 | - !expand { CFGHDR_TMPL : [ PLATFORMID_CFG_DATA, 0x0F0, 0, 0 ] } 233 | 234 | Here, the template CFGHDR_TMPL will be expanded with its full template 235 | body. $(1), $(2), $(3) in template body will be replaced with the 236 | appropriate parameters where: 237 | 238 | - $(1) is replaced with PLATFORMID_CFG_DATA, 239 | 240 | - $(2) is replaced with 0x0F0, 241 | 242 | - $(3) is replaced with 0, 243 | 244 | - and $(4) is replaced with 0. 245 | 246 | Variable 247 | -------- 248 | 249 | Variables may be considered as something equivalent to a C language 250 | macro. Variables are primarily used as symbolic names given to Python 251 | expressions. Whenever the variable name is used, it is replaced by the 252 | contents of the macro. Variables should only be defined in *variable* 253 | section. 254 | 255 | Example: 256 | 257 | variable: 258 | 259 | COND_GPIO_SKIP : ($GPIO_CFG_DATA.$(1)_Half0.GpioSkip == 0) 260 | 261 | Template 262 | -------- 263 | 264 | Templates are used to declare the format of configuration options and 265 | are useful when many configuration options of the similar type are 266 | needed. GPIO configuration option is a good example where templates are 267 | useful. A platform may have a lot of GPIO pins and instead of declaring 268 | configuration options for GPIO_1, GPIO_2, GPIO_3, etc., a template for 269 | GPIO can be declared and each GPIO can reuse the same configuration 270 | template with different values as needed. 271 | 272 | Templates should be declared in *template* section only, and should 273 | always be represented as a mapping node using folded block style 274 | indicated by a right angle bracket (>). 275 | 276 | Templates support reference to parameters to customize the expansion. 277 | $(n) can be used to refer to the Nth parameter passed into this template 278 | macro by *!expland* tag. During expansion, $(n) will be substituted with 279 | the actual Nth parameter. 280 | 281 | For example, a template for PCIe root port configuration is shown below: 282 | 283 | PCIERP_TMPL: > 284 | 285 | - PcieRpFeatures$(1) : 286 | 287 | - $STRUCT : 288 | 289 | name : PCIE RP $(1) Config Data 290 | 291 | struct : PCIE_RP_FEAT[] 292 | 293 | length : 0x01 294 | 295 | value : $(2) 296 | 297 | - En : 298 | 299 | name : PCIE RP Enable 300 | 301 | type : Combo 302 | 303 | option : $EN_DIS 304 | 305 | help : > 306 | 307 | ENABLE- Enable this PCIE RP. DISABLE- Disable this PCIE RP 308 | 309 | order : 0000.0000 310 | 311 | length : 1bB 312 | 313 | - ClkReqSup : 314 | 315 | name : PCIE RP Clk Req Support 316 | 317 | type : Combo 318 | 319 | option : $EN_DIS 320 | 321 | help : > 322 | 323 | Enable/Disable CLKREQ# Support 324 | 325 | condition : $(COND_PCIE_RP_EN) 326 | 327 | length : 1bB 328 | 329 | - ClkReqNum : 330 | 331 | name : PCIE RP Clk Req Number 332 | 333 | type : EditNum, HEX, (0x00, 0xFF) 334 | 335 | help : > 336 | 337 | Configure Root Port CLKREQ Number if CLKREQ is supported 338 | 339 | condition : $(COND_PCIE_RP_CLK_REQ_SUP) 340 | 341 | length : 3bB 342 | 343 | - Aspm : 344 | 345 | name : PCIE RP Aspm 346 | 347 | type : EditNum, HEX, (0x00, 0xFF) 348 | 349 | help : > 350 | 351 | PCI Express Active State Power Management settings 352 | 353 | condition : $(COND_PCIE_RP_EN) 354 | 355 | length : 3bB 356 | 357 | Now, multiple PCIe root part configurations are declared using 358 | !expand 359 | (`!EXPAND `__) 360 | as below: 361 | 362 | - PCIE_RP_CFG_DATA : 363 | 364 | - !expand { CFGHDR_TMPL : [ PCIE_RP_CFG_DATA, 0x302, 0, 0 ] } 365 | 366 | - !expand { PCIERP_TMPL : [ 0 , 0x8B ] } 367 | 368 | - !expand { PCIERP_TMPL : [ 1 , 0x8F ] } 369 | 370 | - !expand { PCIERP_TMPL : [ 2 , 0x87 ] } 371 | 372 | - !expand { PCIERP_TMPL : [ 3 , 0x86 ] } 373 | 374 | - !expand { PCIERP_TMPL : [ 4 , 0x83 ] } 375 | 376 | - !expand { PCIERP_TMPL : [ 5 , 0x8E ] } 377 | 378 | Configs 379 | ------- 380 | 381 | This section contains the configuration option declarations. 382 | 383 | A YAML **node** represents a single native data structure. A **mapping 384 | node** is an unordered set of *key: value* node pairs. Mappings use a 385 | colon and space (“: “) to mark each key: value pair. 386 | 387 | A **block sequence** is simply a series of nodes, each denoted by a 388 | leading “-” indicator. The “-” indicator must be separated from the node 389 | by white space. YAML’s **block collections** use indentation for scope 390 | and begin each entry on its own line. 391 | 392 | SBL configuration options are a series of YAML block sequence and form a 393 | YAML block collection. 394 | 395 | Every ConfigDataDef.yaml configs section starts with the declaration for 396 | the **CDATA_BLOB_HEADER** as shown in `Config BLOB 397 | Header `__ 398 | followed by a series of configuration data identied by unique tags: 399 | 400 | configs: 401 | 402 | - $ACTION : 403 | 404 | page : PageId1::"Page Display Text", PageId2::"Page Display Text", 405 | PageId3::"Page Display Text", ... 406 | 407 | - Signature : 408 | 409 | length : 0x04 410 | 411 | value : {'CFGD'} 412 | 413 | - HeaderLength : 414 | 415 | length : 0x01 416 | 417 | value : 0x10 418 | 419 | - Reserved : 420 | 421 | length : 0x03 422 | 423 | value : {0,0,0} 424 | 425 | - UsedLength : 426 | 427 | length : 0x04 428 | 429 | value : \_LENGTH\_ 430 | 431 | - TotalLength : 432 | 433 | length : 0x04 434 | 435 | value : 0x2000 436 | 437 | As discussed in `SBL Configuration 438 | Tags `__, 439 | SBL configuration options are organized as groups. 440 | 441 | - Each group **is** represented **as** a **YAML** block sequence 442 | **and** starts **with** a leading "-" indicator followed by a white 443 | space. 444 | 445 | - Each group has a configuration header. The Configuration header 446 | **is** declared using "!expand" tag to expand a template declaration. 447 | The configuration header itself **is** a **YAML** block sequence 448 | 449 | - Each configuration option within the group **is** also a block 450 | sequence made of mapping nodes, each **with** key:value pair. 451 | 452 | The following example will illustrate how a MrcFastBoot config option is 453 | declared 454 | 455 | - MrcFastBoot : 456 | 457 | name : MrcFastBoot 458 | 459 | type : Combo 460 | 461 | option : $EN_DIS 462 | 463 | help : > 464 | 465 | Enable/Disable MRC fast boot support 466 | 467 | length : 0x01 468 | 469 | value : 0x1 470 | 471 | The below shows the MrcFastBoot config option being under 472 | MEMORY_CFG_DATA. 473 | 474 | - MEMORY_CFG_DATA : 475 | 476 | - !expand { CFGHDR_TMPL : [ MEMORY_CFG_DATA, 0x200, 0, 0 ] } 477 | 478 | - MrcFastBoot : 479 | 480 | name : MrcFastBoot 481 | 482 | type : Combo 483 | 484 | option : $EN_DIS 485 | 486 | help : > 487 | 488 | Enable/Disable MRC fast boot support 489 | 490 | length : 0x01 491 | 492 | value : 0x1 493 | 494 | Example showing the MrcFastBoot config option being under 495 | MEMORY_CFG_DATA which is displayed in a “MEM” page. 496 | 497 | - $ACTION : 498 | 499 | page : MEM 500 | 501 | - MEMORY_CFG_DATA : 502 | 503 | - !expand { CFGHDR_TMPL : [ MEMORY_CFG_DATA, 0x200, 0, 0 ] } 504 | 505 | - MrcFastBoot : 506 | 507 | name : MrcFastBoot 508 | 509 | type : Combo 510 | 511 | option : $EN_DIS 512 | 513 | help : > 514 | 515 | Enable/Disable MRC fast boot support 516 | 517 | length : 0x01 518 | 519 | value : 0x1 520 | 521 | Configuration Option Nodes 522 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 523 | 524 | The below sections explain each of the “keys” used in a configuration 525 | option. 526 | 527 | NAME 528 | ^^^^ 529 | 530 | NAME gives a plain-text label for a configuration parameter. This is the 531 | text label that is displayed in the Config Editor tool. 532 | 533 | Format: 534 | 535 | name: CfgItemName 536 | 537 | Example: 538 | 539 | name : MrcFastBoot 540 | 541 | TYPE 542 | ^^^^ 543 | 544 | TYPE defines the format of a configuration parameter that will be 545 | represented in the Config Editor tool. There are 5 different types 546 | available for configuration parameters: **EditNum**, **EditText**, 547 | **Combo**, **Table**, **Reserved** 548 | 549 | EditNum 550 | ''''''' 551 | 552 | EditNum is used when user needs to input any value within the range 553 | defined. If the configuration option is an array, the VALUE field is 554 | used to specify the number of elements in the array. 555 | 556 | Format: 557 | 558 | type : EditNum, NumType, (MinValue, MaxValue) 559 | 560 | NumType could be \**HEX*\* (Hexa-Decimal format) **or** \**DEC*\* 561 | (Decimal format) 562 | 563 | The MinValue **and** MaxValue **is** the minimum **and** maximum 564 | value allowed. 565 | 566 | EditText 567 | '''''''' 568 | 569 | EditText is used when user needs to input any text string. 570 | 571 | Format: 572 | 573 | type : EditText 574 | 575 | Combo 576 | ''''' 577 | 578 | Combo is used to select from a drop-down list along. This list will be 579 | provided by OPTION field. 580 | 581 | Format: 582 | 583 | type : Combo 584 | 585 | option : val1:text1, val2:text2, val3:text3, ... 586 | 587 | Example: 588 | 589 | type : Combo 590 | 591 | option : 0:9600, 1:19200, 2:38400, 3:57600, 4:115200 592 | 593 | Table 594 | ''''' 595 | 596 | Table is used to define a tabular format. It needs to be used along with 597 | OPTION field to provide additional information for the table including 598 | column header string, cell width and cell format. Further, the VALUE 599 | field specifies the total number of elements in the table. 600 | 601 | Format: 602 | 603 | type : Table 604 | 605 | option : ColumnHdr1:width:format, ColumnHdr2:width:format, 606 | ColumnHdr3:width:format, ... 607 | 608 | ColumnHdr’n’ sepcifier indicates the string to be displayed as the 609 | column header. width indicates the cell width in number of bytes format 610 | is the number format and should be HEX 611 | 612 | Example: 613 | 614 | type : Table 615 | 616 | option : > 617 | 618 | 0:1:HEX, 1:1:HEX, 2:1:HEX, 3:1:HEX, 4:1:HEX, 5:1:HEX, 6:1:HEX, 619 | 7:1:HEX, 8:1:HEX, 9:1:HEX, A:1:HEX, B:1:HEX, C:1:HEX, D:1:HEX, 620 | E:1:HEX, F:1:HEX 621 | 622 | Byte width in each cell of the table can be displayed as 1 byte, 2 bytes 623 | or 4 bytes. 624 | 625 | Reserved 626 | '''''''' 627 | 628 | Reserved type can be used to prevent configuration parameters from being 629 | displayed in the Config Editor. But the configuration parameters will 630 | still be generated in the auto-generated C header structure. 631 | 632 | Format: 633 | 634 | type : Reserved 635 | 636 | OPTION 637 | ^^^^^^ 638 | 639 | This allows to provide type-specific additional information. For type 640 | Combo, it defines the drop-down list. For type Table, it defines the 641 | column display information. 642 | 643 | Format: 644 | 645 | OPTION: > Value1:TextStr1, Value2:TextStr2, …. 646 | 647 | Note: Config tools allow the value/contents for OPTION to be split into 648 | multiple lines. The lines except for the very first line need to start 649 | with ‘\ **+’ (plus sign)** to tell the parsing tool to append this 650 | string to previous one. 651 | 652 | HELP 653 | ^^^^ 654 | 655 | This defines what will appear in the ‘help’ text when hovering over the 656 | field in the UI tool. 657 | 658 | Format: 659 | 660 | help: > Any detail about particular CfgItem 661 | 662 | Example: 663 | 664 | help: > Enable/disable LAN controller 665 | 666 | Note: Config tools allow the value/contents for HELP to be split into 667 | multiple lines. The lines except for the very first line need to start 668 | with ‘\ **+’ (plus sign)** to tell the parsing tool to append this 669 | string to previous one. 670 | 671 | CONDITION 672 | ^^^^^^^^^ 673 | 674 | CONDITION is used to associate conditional statement for a configuration 675 | parameter when required. It is useful to dynamically hide/display a 676 | configuration parameter that has a dependency on another configuration 677 | parameter value. When the condition is TRUE, the configuration parameter 678 | is visible. Otherwise, it is hidden. 679 | 680 | Format: 681 | 682 | condition: Expression 683 | 684 | Expression is an expression following Python\* syntax. It can have 685 | reference to another configuration parameter using $\ *CfgItemName* or 686 | *$CfgItemName.BitField* format. It can use variables as described in 3.3 687 | 688 | Example: 689 | 690 | condition : $GPIO_CFG_DATA.GpioPinConfig1_$(1).GPIOSkip_$(1) == 0 691 | 692 | condition : $SECURITY_CFG_DATA.EnableSgx != 0 and 693 | $SECURITY_CFG_DATA.EpochUpdate == 2 694 | 695 | ORDER 696 | ^^^^^ 697 | 698 | ORDER can be used to adjust the display order for the configuration 699 | parameters in a page. By default, if this command is not specified, the 700 | order value is assigned to be the CfgitemOffset as the logic described 701 | below. But if a different order is required, it can be overridden by 702 | declaring **ORDER** command explicitly using format: 703 | 704 | order : {HexMajor.HexMinor} 705 | 706 | The final order key is calculated as: 707 | 708 | Order = (HexMajor << 16) + (((HexMajor & 0xFF) << 8) + BitFieldOffset 709 | 710 | If ORDER {HexMajor.HexMinor} is not specified for an item, it is 711 | calculated as: Order = (CfgItemOffset << 16) 712 | 713 | The item order value is used as the *sort key* during YAML items 714 | display. 715 | 716 | Example: 717 | 718 | order :{0000.0000} 719 | 720 | order :{0x0040.01} 721 | 722 | LENGTH 723 | ^^^^^^ 724 | 725 | Length is used to specify the size of the configuration option in bytes. 726 | Length can also be specified in bits by appending ‘b’ at the end. 727 | 728 | Example: 729 | 730 | length : 1b 731 | 732 | length : 0x04 733 | 734 | VALUE 735 | ^^^^^ 736 | 737 | Value is used to specify the default value of the configuration option. 738 | It could be a number, string, or data array. 739 | 740 | - For number, it can be DEC or HEX. HEX needs to have prefix ‘0x’. 741 | 742 | - For array, **{** **}** braces are required around the element list. 743 | List elements should be numbers and are separated by comma. Each 744 | element should have the same unit size (1, 2, 4, 8 bytes). By 745 | default, it is BYTE for each element. The unit size can be changed 746 | through an extended dummy element at the beginning of the array, 747 | noted as “0:0[B|W|D|Q]”. 748 | 749 | - For string, single or double quotes are required. 750 | 751 | Example: 752 | 753 | value : 0xFF 754 | 755 | value : {0, 1, 3, 2, 4, 5, 6, 7} 756 | 757 | {0:0B, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08} 758 | 759 | {0:0W, 0x0201, 0x0403, 0x0605, 0x0807} 760 | 761 | {0:0D, 0x04030201, 0x08070605} 762 | 763 | {0:0Q, 0x0807060504030201} 764 | 765 | value : 'FwuImage.bin' 766 | 767 | Delta (DLT) File Explained 768 | -------------------------- 769 | 770 | Configuration Delta (DLT) file is an extension of the base configuration 771 | YAML file that contains configuration parameters that need to be 772 | overridden from base configuration. 773 | 774 | Each board flavor can have one DLT file specified. YAML and DLT files 775 | reside at the Platform folder in source. Delta files are **NOT** 776 | auto-generated files. 777 | 778 | In addition to board-specific delta files, a delta file that overrides 779 | configuration parameters for all boards (board ID 0) is also supported. 780 | Users can add/create new DLT file for each board flavor of the same SOC 781 | with the help of board-specific PlatformId (1 – 31) that should be 782 | specified in each file. Parsing tool will then calculate bit mask/value 783 | for each tag that is included in base configuration YAML against each 784 | board’s PlatformID specified in .DLT and populates relevant data based 785 | on PlatformID in the form of binaries (.bin) for each of the boards. 786 | 787 | If config parameters did not change for a tag, data is taken from base 788 | configuration itself. If it has changed for a particular tag mentioned 789 | in .DLT, new data from DLT will be overwritten and gets generated in the 790 | configuration binary for that specific board. 791 | 792 | DLT file rules 793 | -------------- 794 | 795 | - Users cannot add/create a new configuration parameter in DLT file, 796 | nor can they create a new tag. Users can only modify/overwrite the 797 | values for configuration parameters that are already existing in the 798 | base configuration YAML file. 799 | 800 | - Delta file can be used to generate both default and custom/standalone 801 | config data. Delta file is like changing configuration items using 802 | *ConfigEditor* (explained later). 803 | 804 | - Delta file cannot be opened in UI interface all by itself. But it’s 805 | possible to open in *ConfigEditor* by first loading the base 806 | configuration YAML, and then load DLT file on top of it. We can then 807 | see overrides in *ConfigEditor* that is mentioned in DLT. 808 | 809 | - Delta files should be included as part of the Board Configuration 810 | script, BoardConfig.py in order to take effect. 811 | 812 | Example: 813 | 814 | self._CFGDATA_INT_FILE = ['CfgData_Int_Brd0_Def.dlt'] 815 | 816 | self._CFGDATA_EXT_FILE = 817 | ['CfgData_Ext_Brd1_Rvp.dlt','CfgData_Ext_Brd2_Crb.dlt','CfgData_Ext_Brd3_Bmp.dlt'] 818 | 819 | - ‘_CFGDATA_INT_FILE’ is used for all the default board flavors. Delta 820 | files included here is generated as part of the default configuration 821 | data consumed within the source. 822 | 823 | - ‘_CFGDATA_EXT_FILE’ is used for external/customer boards. Delta files 824 | included here is generated as a standalone binary and stitched into 825 | the BIOS region of the SPI Flash. 826 | 827 | - Below are the current formats that can be used in DLT: 828 | 829 | - Hash “#” symbol indicates comments in the DLT file. 830 | 831 | - Users can overwrite the values of existing Tag items in DLT as 832 | follows 833 | 834 | Format: 835 | 836 | Tagname.itemname(s) \| 837 | 838 | Example: 839 | 840 | PLATFORMID_CFG_DATA.PlatformId \| 1 841 | 842 | Example: 843 | 844 | GPIO_CFG_DATA.GpioPinConfig1_GPP_A0.GPIOSkip_GPP_A0 \| 1 845 | 846 | - Granularity of the data is based upon the size of the configuration 847 | parameters specified in the base configuration YAML file. In the 848 | above example, PlatformID in base configuration YAML is defined as 2 849 | bytes. So, the value should be mentioned according to its size. 850 | Similarly, GPIOSkip field in base configuration YAML is defined as 1 851 | byte. So, the value to be mentioned in DLT can either be 0 or 1. If 852 | we want to overwrite the full DWORD instead of individual bits, for 853 | example, GPIO PIN Config DWord0 or DWord1, it can be specified as 854 | follows, example: GPIO_CFG_DATA.GpioPinConfig0_GPP_A0 \| 0x12345678 855 | 856 | Note: Customers who have access to source code can change DLT files 857 | without having to use *ConfigEditor* GUI interface and any other 858 | configuration tools if they are able to build and stitch the source. All 859 | the commands used to generate, merge, sign the binaries are all part of 860 | the *CfgDataTool*, which is already part of the build process. They will 861 | be auto generated, merged, and signed as we run the build/stitch 862 | commands with no manual steps needed to create the final Configuration 863 | binary blob. 864 | 865 | Configuration Process 866 | --------------------- 867 | 868 | Configuration data flow begins with the base configuration YAML file 869 | along with delta (DLT) files that contain the overrides of configuration 870 | settings that are different from base configuration data. *CfgDataTool* 871 | parses YAML and DLT file(s) and *GenCfgData* auto-generates each DLT’s 872 | binary file. 873 | 874 | The new board-specific config binary(ies) generated from the DLT files 875 | will then be ‘merged’ by *CfgDataTool* along with default config binary 876 | files (CfgDataInt.bin*) that were previously generated for each board 877 | flavor. 878 | 879 | Merged configuration binary will then be ‘signed’ by *CfgDataTool* with 880 | a Private Key. 881 | 882 | Signed configuration binary will be the ‘final’ custom/standalone 883 | configuration binary (Example: CFG_EXT_SIGNED.bin) that is placed in PDR 884 | or BIOS region and stitched into the final image that is to be flashed 885 | in SPI. 886 | 887 | -------------------------------------------------------------------------------- /source/5_security.rst: -------------------------------------------------------------------------------- 1 | .. _security: 2 | 3 | Security 4 | ======== 5 | 6 | Security Overview 7 | ----------------- 8 | 9 | There are various security considerations for the POL, sFSP, and the 10 | payloads. This section will describe the various overall concerns and 11 | technology specific aspects. 12 | 13 | Firmware Resiliency - Protection 14 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 15 | 16 | Critical Resource Lock (hardware) 17 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 18 | 19 | The platform shall always lock the important resource before it exits 20 | the platform manufacture phase. 21 | 22 | The important resource includes but is not limited to flash part, SMRAM, 23 | SMRR, silicon register such as lockable BAR register, 24 | 25 | Critical Service Close (software) 26 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 27 | 28 | The platform shall always close the service that may impact the system 29 | resource. 30 | 31 | The service includes but is not limited to SMM registration service, 32 | flash update service. 33 | 34 | Critical Resource Access 35 | ^^^^^^^^^^^^^^^^^^^^^^^^ 36 | 37 | The platform shall only allow the critical resource access in the 38 | trusted execution environment such as SMM. 39 | 40 | .. _update-1: 41 | 42 | Update 43 | ^^^^^^ 44 | 45 | The platform shall only allow firmware update only in the trusted 46 | execution environment such as SMM, or before existing the platform 47 | manufacture phase. 48 | 49 | The update must check the secure version number to prevent rollback. 50 | 51 | Firmware Resiliency - Detection 52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 | 54 | Secure Boot (verified boot) 55 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 56 | 57 | The platform shall enable secure boot. The early boot component shall 58 | verify the next component. 59 | 60 | Care must be taken for Time-of-check/Time-of-use (TOC/TOU) attack. 61 | 62 | The early component shall copy the next component to a trusted execution 63 | environment, verify and use. 64 | 65 | Please refer to `Understanding the UEFI Secure Boot Chain `_ 66 | 67 | Secure Configuration (data verification) 68 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 69 | 70 | If the configuration has security property, such as lock/unlock policy. 71 | It shall be protected and verified. 72 | 73 | The secure configuration may be treated as code and verified together 74 | with secure boot. 75 | 76 | Or the secure configuration may be protected by the variable 77 | enhancement, such as RPMB or RPMC. 78 | 79 | Firmware Resiliency - Recovery 80 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 81 | 82 | Recovery trigger 83 | ^^^^^^^^^^^^^^^^ 84 | 85 | A platform should have a watchdog to auto trigger recovery process 86 | automatically. Otherwise, it should notify the end user that a manual 87 | recovery is required. 88 | 89 | Known good image 90 | ^^^^^^^^^^^^^^^^ 91 | 92 | The recovery process may load a known good image. The known good image 93 | itself shall be protected and follow the detection flow. 94 | 95 | The known good image shall be up to date as well, to resist rollback 96 | attack – recovery to an old known bad image. 97 | 98 | Measurment and Attestation 99 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 100 | 101 | OEM Component Measurement 102 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 103 | 104 | The platform shall follow `TCG PC Client Platform Firmware Profile `_ 105 | if TPM-based measured boot is enabled. The early boot component shall 106 | measure the next component before transfer control to it, to create a 107 | trust chain. 108 | 109 | Please refer to `Understanding the Trusted Boot Chain Implementation `_ 110 | 111 | The platform shall follow TCG specification to measure all required 112 | component. For example, the platform shall measure every boot component. 113 | The platform shall measure any security-related boot configuration. 114 | 115 | FSP Measurement 116 | ^^^^^^^^^^^^^^^ 117 | 118 | The platform shall follow `FSP measurement and attestation `_ 119 | to record the measurement for FSP binary. 120 | 121 | Device Measurement 122 | ^^^^^^^^^^^^^^^^^^ 123 | 124 | The platform shall follow `DMTF Security Protocol and Data Model (SPDM) Specification `_ 125 | to record the measurement for the devices. 126 | 127 | Universal Payload Measurement 128 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 129 | 130 | The platform shall create a standalone event log for the universal payload. 131 | 132 | .. list-table:: 133 | :widths: auto 134 | :header-rows: 1 135 | 136 | * - Component 137 | - PCR 138 | - Event Type 139 | - Event Data 140 | - Event Log 141 | * - UniversalPayload binary 142 | - 0 (if it is part of OEM binary) or 2 (if it is treated as second phase loader) 143 | - EV_EFI_PLATFORM_FIRMWARE_BLOB2 144 | - UniversalPayload binary 145 | - EFI_PLATFORM_FIRMWARE_BLOB2 structure (descriptor: "UniversalPayload") 146 | 147 | DMA Protection 148 | ~~~~~~~~~~~~~~ 149 | 150 | The platform shall enable IOMMU based DMA protection. 151 | 152 | For example, `Using IOMMU for DMA Protection in UEFI Firmware `_. 153 | 154 | Cryptography Agility 155 | ~~~~~~~~~~~~~~~~~~~~ 156 | 157 | A firmware infrastructure shall allow the implementation to choose different cryptographic algorithms, to compliant with different standards. This is called Cryptography agility. 158 | TPM2.0 standard is a good example. A TPM2.0 device may support SHA256, SHA384, SM3_256, or future algorithms such as SHA3_256 or SHA3_384. 159 | 160 | Below table shows the supported crypto algorithms. 161 | 162 | .. list-table:: 163 | :widths: auto 164 | :header-rows: 1 165 | 166 | * - Standard 167 | - Supported Algorithm 168 | * - TCG - `EFI Protocol `_ 169 | - SHA1/SHA-{256,384,512}/SM3 170 | * - IETF - `TLS 1.3 `_ 171 | - TLS Cipher Suite – for negotiation 172 | * - DMTF - `SPDM 1.1 `_ 173 | - RSA{SSA,PSS}_{2048,3072,4096}/ECDSA_P{256,384,521}+{SHA,SHA3}_{256,384,512} 174 | * - PCI-SIG – `CMA (Component Measurement and Authentication) `_ 175 | - RSASSA_3072/ECDSA_P{256,384} + SHA{256,384} 176 | * - UEFI - `UEFI 2.9 `_ 177 | - RSA2048 (PKCS1_1.5) + SHA256 178 | 179 | Below table shows the minimal requirement. 180 | 181 | .. list-table:: 182 | :widths: auto 183 | :header-rows: 1 184 | 185 | * - Standard 186 | - Minimal Requirement 187 | * - `Commercial National Security Algorithm Suite (CNSA Suite Guide) `_ 188 | - SHA384, RSAPSS_3072/ECDSA_P384 189 | * - `PRC CESA Server BIOS Requirement `_ 190 | - SHA256/SM3, RSA_2048/SM2, ECDSA_256/SM2 191 | * - `ARM Trusted Board Boot Requirements Client (TBBR-CLIENT) for A profile `_ 192 | - AES_128, SHA256, ECDSA_256 (RSAPSS_2048) 193 | * - `ARM Platform Security Architecture (PSA) Trusted Base System Architecture (TBSA) for M profile `_ 194 | - AES_128, SHA256, ECDSA_256, RSA_3072 195 | * - `OCP Secure Boot `_ 196 | - SHA384, RSAPSS_3072/ECDSA_P384 197 | 198 | Below table shows the algorithm usage. 199 | 200 | .. list-table:: 201 | :widths: auto 202 | :header-rows: 1 203 | 204 | * - Feature 205 | - Algorithm 206 | * - `coreboot – Google Binary Blob (GBB) firmware keys `_ 207 | - RSA 8192 + SHA512 208 | * - `IBM Power Secure Boot `_ 209 | - ECDSA (512 bit) + SHA512 210 | * - `MSFT Secure Boot Key `_ 211 | - RSA 2048 + SHA256 212 | 213 | A firmware should start considering Post Quantum Cryptography Algorithm. 214 | In 2019, NIST Stateful Hash-Based Signatures (`HBS `_) projects published `NIST SP 800-208 `_ for the image signing in secure boot and secure update use case. 215 | In 2022, NIST Post Quantum Cryptography (`PQC `_) projects announced the `Selected Algorithms 2022 `_ for general purpose digital signature and Public-key Encryption / Key-establishment. 216 | In 2022, NSA released the `Commercial National Security Algorithm Suite 2.0 (CNSA 2.0) Cybersecurity Advisory (CSA) `_, which includes the quantum resistant algorithms. 217 | 218 | Below table shows the post quantum algorithms. 219 | 220 | .. list-table:: 221 | :widths: auto 222 | :header-rows: 1 223 | 224 | * - Usage 225 | - Algorithm 226 | - Specification 227 | - Approved by 228 | * - Image Signing (secure boot, secure update) 229 | - Leighton-Micali Signature (LMS) - `RFC8554 `_ 230 | - `NIST SP 800-208 `_ 231 | - NIST, NSA 232 | * - Image Signing (secure boot, secure update) 233 | - Xtended Merkle Signature Scheme (XMSS) - `RFC8391 `_ 234 | - `NIST SP 800-208 `_ 235 | - NIST, NSA 236 | * - Public-key Encryption and Key-establishment 237 | - `CRYSTALS-KYBER `_ 238 | - TBD 239 | - NIST, NSA 240 | * - General Purpose Digital Signature 241 | - `CRYSTALS-DILITHIUM `_ 242 | - TBD 243 | - NIST, NSA 244 | * - General Purpose Digital Signature 245 | - `FALCON `_ 246 | - TBD 247 | - NIST 248 | * - General Purpose Digital Signature 249 | - `SPHINCS+ `_ 250 | - TBD 251 | - NIST 252 | 253 | 254 | The firmware related timeline would be: 255 | 256 | 1. Software and Firmware Signing: prefer CNSA 2.0 by 2025, exclusively use by 2030. 257 | 2. Web browsers/servers and cloud services: prefer CNSA 2.0 by 2025, exclusively use by 2033. 258 | 259 | A firmware infrastructure shall consider crypto-agile support for two purposes: 260 | 261 | 1. To support more industry standard cryptographic algorithms, which may be used in some firmware implementation, such as SHA3, SM3, SM2, etc. 262 | 2. To support quantum safe cryptographic algorithm and hybrid mode, such as XMSS or LMS digital signature algorithm, etc. 263 | 264 | 265 | Vulnerability Mitigation Strategy 266 | --------------------------------- 267 | 268 | The platform should make the attacker difficult to find, exploit and leverage the vulnerabilities. 269 | 270 | .. list-table:: 271 | :widths: auto 272 | :header-rows: 1 273 | 274 | * - Tactics 275 | - Method 276 | - Example 277 | * - Eliminate Vulnerability 278 | - Reduce Attack Surface. Dont Use Weak Cryptography Algorithm. Use Type Safe Programming Language. 279 | - Remove Unnecessary Interface, such as SMI handler, UEFI variable. Adopt Firmware Security Best Practice. Consider Side Channel Attack. Cryptography Agility. Use Rust. 280 | * - Break Exploitation 281 | - Data Execution Prevention. Control Flow Guard. Address Space Layout Randomization. Secure Boot. 282 | - Non-executable Data Page. Read-only code page. Stack Cookie. Intel CET. ASLR in DXE/SMM. 283 | * - Contain Damage 284 | - Deprevilege 285 | - Ring-3 Option ROM. Ring-3 OEM SMM. 286 | * - Limit Attack Window 287 | - Firmware Resiliency. Measurement and Attestation. 288 | - Live Patching Runtime Component. Firmware Component Manifest. 289 | 290 | Eliminate Vulnerability 291 | ~~~~~~~~~~~~~~~~~~~~~~~ 292 | 293 | First, a platform should try to remove any attack surfaces and eliminate the potential vulnerablity. 294 | 295 | Minimize SMI handler 296 | ^^^^^^^^^^^^^^^^^^^^ 297 | 298 | In a system firmware, the SMI Handler is the most critical attack surface, because the SMM code has highest privilege. A platform should use `SMI Handler Profile `_ to evaluate if the exposed SMI handlers are necessary. 299 | 300 | Minimize UEFI variable 301 | ^^^^^^^^^^^^^^^^^^^^^^ 302 | 303 | Every UEFI variable is an attack surface, because the attacker can use UEFI API to modify it. A platform should review all UEFI variable and evaluate if it is really needed. 304 | 305 | 306 | Adopt Firmware Security Best Practice 307 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 308 | 309 | The platform should follow the existing firmware security best practice, such as `EDKII Secure Design Guide `_, `EDKII Secure Coding Guide `_, `EDKII Secure Code Review Guide `_. 310 | 311 | Other EDKII security related document can be found at `EDKII Security White Papers `_. 312 | 313 | Consider Side Channel Mitigation 314 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 315 | 316 | A platform shall follow `Host Firmware Speculative Execution Side Channel Mitigation `_. 317 | 318 | 1. LFENCE after validation of untrusted data but before use 319 | 2. RSB stuffing before RSM 320 | 321 | Type Safe Programming Language 322 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 323 | 324 | An analysis has found that 50% of the open source BIOS security bugs are due to buffer overflows and integer overflows. There are a variety of tools and techniques to prevent these bugs, by identifying and eliminating the vulnerability or by ensuring the vulnerability is not exploitable. Alternatively, instead of providing an ever-increasing set of guidance and tools to address these bugs, we could seek ways to avoid introducing the bugs in the first place. An emerging approach is to use memory-safe programming languages. 325 | 326 | `Rust `_ is a promising new programming language that can eliminate memory safety issues at compile time. Engineers at Microsoft have made a `case `_ for using memory-safe languages like Rust. A number of firmware and embedded projects are embracing Rust, including `oreboot `_ system firmware, RISC-V `rustsbi `_ and `tock `_ embedded OS. Rust also supports UEFI toolchains, x86-64-unknown-uefi and i686-unknown-uefi, which can be used to generate a UEFI executable directly. There are UEFI related Rust projects including `r-efi `_ and `uefi-rs `_. 327 | 328 | EDKII firmware may use Rust to build a component with `RustPkg `_. A lightweight pure `rust-firmware `_ is also possible to boot the system with Intel FSP. 329 | 330 | .. image:: images/image7.png 331 | :width: 5in 332 | :height: 2.8125in 333 | 334 | **Figure 14 A pure Rust-firmware** 335 | 336 | Experimentation so far has shown that, with compile-time checking, Rust can eliminate uninitialized variable, use after free, and double free vulnerabilities. With runtime checking, Rust can help break exploitation of memory boundary check and integer overflow check issues. 337 | 338 | In addition to memory safety benefits, Rust also has good software engineering tools support and is interoperable with C. With Rust, developers can easily generate documents (cargo doc), perform unit tests (cargo test), fix coding style issues (cargo fmt), do static analysis (cargo clippy), and more. All those tools are integrated into the Rust cargo package manager. Rust can even get faster performance than C because the code can be determined at compile time, saving time at runtime execution. 339 | 340 | Break Exploitation 341 | ~~~~~~~~~~~~~~~~~~ 342 | 343 | If a platform may contain the vulnerablities, the platform should adopt defence in deptch to break the exploitation. `Memory Protection in UEFI BIOS `_, `Mitigate Buffer Overflow in UEFI `_, `Secure SMM Communication `_, and `CET in SMM `_ provides guideline on how to mitigate those threats. 344 | 345 | Data Execution Prevention (DEP) 346 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 347 | 348 | A platform should set data memory to be non-executable and code memory to be read-only. As such, the data page (including stack, heap, global data, and usable memory) cannot be executed. It is an efficient way to prevent code injection. 349 | 350 | Control Flow Guard (CFG) 351 | ^^^^^^^^^^^^^^^^^^^^^^^^ 352 | 353 | Control flow attack is feasiable even if the DEP is enabled. A platform may enable compiler feature (stack cookie) or use the CPU feature such as Intel Control Flow Enforcement Technology (CET) to guard the control flow. 354 | 355 | Address Space Layout Randomization (ASLR) 356 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 357 | 358 | ASLR is makes it more difficult for an attacker to predict target addresses even if there is vulnerability in the program. The randomization technology can include shuffling, most likely for the image, or shifting, most likely for the data. 359 | 360 | Contain Damage 361 | ~~~~~~~~~~~~~~ 362 | 363 | If a platform does not have an efficient way to break the exploitation, the platform may consider to limit the damage in a small scope. 364 | 365 | Deprevilege Execution 366 | ^^^^^^^^^^^^^^^^^^^^^ 367 | 368 | By default, the system firwmare execution environment is in ring-0. Platform may run untrusted component in a deprevileged environment ring-3. 369 | 370 | For example, the UEFI firmware can run 3rd party option ROM in ring-3, a small SMM CPU code can run the OEM SMM driver in ring-3, etc. 371 | 372 | If the vulnerabilities in option ROM or OEM SMM code are exploited, the damage will only be in the ring-3 component and will not impact the system. 373 | 374 | Limit Attack Window 375 | ~~~~~~~~~~~~~~~~~~~ 376 | 377 | If a platform really has vulnerablity escaping from all defense and impact the system, we need patch it platform in time. 378 | 379 | Live Patching 380 | ^^^^^^^^^^^^^^ 381 | 382 | Live patching is trend in the industry. For example, Linux kernel implemented live patching of a running kernel. 383 | 384 | The system firmware may consider using similar mechanims to patch the runtime component if there is. 385 | 386 | Firmware Component Manifest 387 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 388 | 389 | Before a firmware patch is deployed, an adiminstrator may need to know how many systems are impacted. 390 | 391 | A platform may include many firmware components, which are from different sources. Now we need a way to collect those information. We define 2 category of firmwares in below table 392 | 393 | .. list-table:: 394 | :widths: auto 395 | :header-rows: 1 396 | 397 | * - Type 398 | - Sub-Type 399 | - Loader (Loaded/Measured/Authenticated by) 400 | - Location (Loaded from) 401 | - Execution Environment (Executed in) 402 | - Example 403 | * - Type-I 404 | - I-A 405 | - Host 406 | - System Firmware 407 | - Host 408 | - BIOS, Intel FSP, CPU Microcode 409 | * - Type-I 410 | - I-B 411 | - Host 412 | - Peripheral Device 413 | - Host 414 | - PCI Option ROM 415 | * - Type-II 416 | - II-A 417 | - Non-Host 418 | - Non-Host Firmware 419 | - Non-Host 420 | - BMC, EC, Intel CSME 421 | * - Type-II 422 | - II-B 423 | - Peripheral Device 424 | - Peripheral Device 425 | - Peripheral Device 426 | - NIC, NVMe, Graphic Card 427 | 428 | We define 2 types of firmwares: 429 | 430 | * Type-I firmware indicates the firmware loaded, measured, authenticated in host environment. 431 | * Type-I-A indicates the one loaded from system firmware location, such as BIOS, FSP, CPU Microcode. 432 | * Type-I-B indicates the one loaded from peripheral device, such as PCI option ROM. 433 | * Type-II firmware indicates the firmware loaded, measured, authenticated not in host environment. 434 | * Type-II-A indicates the one loaded from non-host firmware location, such as BMC, EC, Intel CSME. 435 | * Type-II-B indicates the one loaded from peripheral device, such as NIC, NVMe, Graphic Card. 436 | 437 | For Type-I firmware, the component provider may provide a reference integrity manifest (RIM) for this specific component. 438 | 439 | Intel `FSP 2.x measurement and attesation `_ defines a mechanism to report FSP manifest according to TCG `PC Client Reference Integrity Manifest Specification `_. The RIM format could be `SWID `_ or `CoSWID `_. 440 | 441 | The universal payload should use SWID or CoSWID with below information: 442 | 443 | .. list-table:: 444 | :widths: auto 445 | :header-rows: 1 446 | 447 | * - Element 448 | - Attribute 449 | - Required 450 | - Description 451 | * - Software Identity 452 | - Name 453 | - Required 454 | - Name of the Universal payload 455 | * - 456 | - Version 457 | - Required 458 | - Version of the Universal payload 459 | * - 460 | - TagId 461 | - Required 462 | - GUID to identify the Universal payload 463 | * - 464 | - TagVersion 465 | - Required 466 | - Version to the tag, "0" 467 | * - 468 | - Corpus 469 | - Optional 470 | - "FALSE" 471 | * - 472 | - Patch 473 | - Optional 474 | - "FALSE" : Initial RIM. "TRUE" : Subsequential RIM 475 | * - 476 | - Supplemental 477 | - Optional 478 | - "FALSE" : First RIM (e.g. primary RIM). "TRUE" : not firmst RIM (e.g. issued by System Integrator or Value Add Reseller) 479 | * - Entity 480 | - Name 481 | - Required 482 | - The entity that creates the Universal Payload, could be "USF". 483 | * - 484 | - RegId 485 | - Optional 486 | - URI for the entity to create the Universal Payload, could be "https://github.com/UniversalScalableFirmware". 487 | * - 488 | - Role 489 | - Required 490 | - "softwareCreator, tagCreator" 491 | * - 492 | - Thumbprint 493 | - Required 494 | - digest of the signing certificate 495 | * - Link 496 | - Href rel= "installation media" 497 | - Optional 498 | - Download URL 499 | * - 500 | - Href rel= "supersedes", "patches", "requires" 501 | - Optional 502 | - Link to previous RIM 503 | * - Meta 504 | - colloquialVersion 505 | - Required 506 | - Marketing version of the Universal Payload 507 | * - 508 | - Edition 509 | - Required 510 | - Specification version of the Universal Payload 511 | * - 512 | - Production 513 | - Required 514 | - Name of the Universal Payload 515 | * - 516 | - Revision 517 | - Required 518 | - Revision of the Universal Payload 519 | * - 520 | - PayloadType 521 | - Optional 522 | - "Direct" 523 | * - 524 | - PlatformManufacturerStr 525 | - Required 526 | - Name of the Manufacturer 527 | * - 528 | - PlatformManufacturerId 529 | - Required 530 | - IANA identifier of the Manufacturer 531 | * - 532 | - PlatformModel 533 | - Required 534 | - Name of the Platform Model 535 | * - 536 | - PlatformVersion 537 | - Required 538 | - Version of the Platform 539 | * - 540 | - FirmwareManufacturerStr 541 | - Required 542 | - Name of the Firmware Manufacturer 543 | * - 544 | - FirmwareManufacturerId 545 | - Required 546 | - IANA identifier of the Firmware Manufacturer 547 | * - 548 | - FirmwareModel 549 | - Required 550 | - Name of the Firmware Model 551 | * - 552 | - FirmwareVersion 553 | - Required 554 | - Version of the Firmware 555 | * - 556 | - BindingSpec 557 | - Required 558 | - "RIMIM" 559 | * - 560 | - BindingSpecVersion 561 | - Required 562 | - "0.1" 563 | * - 564 | - pcURILocal 565 | - Optional 566 | - URI for this RIM in local device 567 | * - 568 | - pcURIGlobal 569 | - Optional 570 | - URI for this RIM on web 571 | * - 572 | - RIMLinkHash 573 | - Optional 574 | - Not needed for Base RIM 575 | * - Payload 576 | - File, Directory 577 | - Required 578 | - Location and File Name of the Universal Payload component 579 | * - 580 | - Name 581 | - Required 582 | - Name of the Universal Payload component 583 | * - 584 | - Size 585 | - Required 586 | - Size of the Universal Payload component 587 | * - 588 | - Hash 589 | - Required 590 | - Hash of the Universal Payload component 591 | * - 592 | - supportRIMType 593 | - Optional 594 | - N/A 595 | * - 596 | - supportRIMFormat 597 | - Optional 598 | - N/A 599 | * - 600 | - supportRIMURIGlobal 601 | - Optional 602 | - N/A 603 | 604 | At runtime, the system firmware records a specific component measurement entry, then the verifier can compare the measurement in the event log with the reference value in the RIM. Figure 15 shows the Type-I firmware component RIM concept. 605 | 606 | .. image:: images/image20.png 607 | :width: 5in 608 | :height: 2.8125in 609 | 610 | **Figure 15 Component Manifest for Type-I Firmware** 611 | 612 | For Type-II firmware, the component provider may provide a device firmware manifest. The RIM format could be `CoMID `_ 613 | 614 | At runtime, the system firmware may use a standard way - `SPDM `_ protocol - to obtain the measurement from the device and put it into TPM PCR according to TCG `PC Client Specific Platform Firmware Profile Specification `_. The verifier can get the runtime value from the TCG event log and compare it with the reference value in the device RIM. Figure 16 shows the Type-II firmware component RIM concept. 615 | 616 | .. image:: images/image21.png 617 | :width: 5in 618 | :height: 2.8125in 619 | 620 | **Figure 16 Component Manifest for Type II Firmware** 621 | 622 | A platform should have a way to report a list of manifest and collect the runtime firmware measurement. As such, we can know the detailed firmware component information on a given platform. 623 | 624 | To support the supply chain, the platform vendor should follow 625 | `TCG Platform Certificate Profile `_, 626 | `TCG PC Client Reference Integrity Manifest `_, 627 | and `TCG PC Client Firmware Integrity Manifest `_ 628 | to provide platform certificate and reference integrity manifest. 629 | -------------------------------------------------------------------------------- /source/3_platform_orchestration_layer.rst: -------------------------------------------------------------------------------- 1 | .. _platform-orchestration-layer-pol: 2 | 3 | Platform Orchestration Layer (POL) 4 | ================================== 5 | 6 | Introduction 7 | ------------ 8 | 9 | The Platform Orchestration Layer (POL) is aimed to provide guidelines on 10 | writing platform code that leverage a Scalable Intel Firmware Support 11 | Package (sFSP) interface and payload to coordinate the overall platform 12 | initialization flow. 13 | 14 | Motivation for POL 15 | ~~~~~~~~~~~~~~~~~~ 16 | 17 | Following the Next Generation Firmware initiative, the Intel system 18 | firmware (BIOS) is evolving to be a multilayer, modular, scalable FW 19 | solution which fulfills all the modern FW requirements in a super 20 | complex HW IP centric world. The layers are shown in Figure 1. 21 | 22 | The Platform Orchestration Layer sits between the SOC Abstraction Layer 23 | (SAL), as abstracted by the Scalable FSP interface, and the Payload 24 | Layer. The Platform Orchestration Layer coordinates the board-specific 25 | boot sequence, invoking the sFSP interfaces for any silicon specific 26 | work, and produces the interface to launch the payload environment along 27 | with industry standard tables that are an amalgam of silicon and 28 | platform, such as SMBIOS and ACPI. 29 | 30 | .. image:: images/image3.png 31 | :width: 6.5in 32 | :height: 3.65625in 33 | 34 | Figure 2 Layers of Universal Scalable Firmware 35 | 36 | Therefore, the missions of POL layer are: 37 | 38 | - Initialize the board by programming board specific resources and 39 | invoking the sFSP for SOC and/or XPU specific resources 40 | 41 | - Invoke payloads for OS boot environment and possible XPU and runtime. 42 | 43 | POL Design Principles 44 | ~~~~~~~~~~~~~~~~~~~~~ 45 | 46 | POL is considered as the layer for platform code. It plays a major role 47 | in providing vendor specific features and mainboard-specific 48 | initialization, as distinct from the sFSP that is scoped to be 49 | SOC-specific. The POL will be the vehicle to convey policy into the 50 | sFSP, interact with the sFSP for initialization, and retrieve state 51 | information from the sFSP. The architectural design of a POL shall 52 | follow the below principles: 53 | 54 | - Compatibility - POL shall be compliant with FSP Specification and 55 | provide the configuration information into the sFSP and retrieve 56 | resultant output information from the sFSP. 57 | 58 | - Portability – POL will attempt to be as SOC independent as possible 59 | and allow for source level compatibility between different open 60 | source platform code frameworks such as EDKII, coreboot, oreboot, and 61 | U-Boot. The OS boot specific code is abstracted via payloads. 62 | 63 | - Determinism/Simplicity – POL should abstract SOC initialization 64 | through sFSP interfaces and have a simple boot flow. 65 | 66 | Audience / Document scope 67 | ~~~~~~~~~~~~~~~~~~~~~~~~~ 68 | 69 | The audience for this document is BIOS/system firmware architects and 70 | developers that design or implement or consume Intel silicon 71 | initialization code. The document is intended to describe the 72 | architecture directions and requirements. 73 | 74 | .. _terminology-1: 75 | 76 | Terminology 77 | ~~~~~~~~~~~ 78 | 79 | .. _terminology_table: 80 | 81 | **Table 1: Terminology** 82 | 83 | ======= ==================================== 84 | Term Definition 85 | ======= ==================================== 86 | Config Abstracted configuration information 87 | Payload OS boot container 88 | sFSP SOC initialization 89 | ======= ==================================== 90 | 91 | Reference documents 92 | ~~~~~~~~~~~~~~~~~~~ 93 | 94 | The following documents are referenced in this specification. 95 | 96 | .. _reference_documents: 97 | 98 | **Table 2: Reference Documents** 99 | 100 | +-----------------+-------------------------------------------------------------------------+-------------+ 101 | | Abbreviation | Document | Version | 102 | +=================+=========================================================================+=============+ 103 | | FSP_EAS | Intel® FSP External Architecture | Version 2.2 | 104 | | | Specification v2.2: | May 2020 | 105 | | | https://cdrdv2.intel.com/v1/dl/getContent/627153 | | 106 | +-----------------+-------------------------------------------------------------------------+-------------+ 107 | | PI_SPECS | Platform Initialization | Version 1.4 | 108 | | | Specification: | | 109 | | | http://www.uefi.org/sites/default/files/resources/PI_1_4.zip | April 2015 | 110 | | | | | 111 | | | - Volume I: PEI | | 112 | | | | | 113 | | | - Volume II: DXE CIS | | 114 | | | | | 115 | | | - Volume III: Shared Architecture | | 116 | | | Elements | | 117 | | | | | 118 | | | - Volume IV: SMM | | 119 | | | | | 120 | | | - Volume V: Standards | | 121 | +-----------------+-------------------------------------------------------------------------+-------------+ 122 | | UEFI_SPEC | Unified Extensible Firmware | Version 2.0 | 123 | | | Interface Specification: | April 2015 | 124 | | | http://www.uefi.org/sites/default/files/resources/UEFI%202_5.pdf | | 125 | +-----------------+-------------------------------------------------------------------------+-------------+ 126 | | FSP 2.3 | https://cdrdv2.intel.com/v1/dl/getContent/644852 | | 127 | +-----------------+-------------------------------------------------------------------------+-------------+ 128 | | FSP Measurement | https://cdrdv2.intel.com/v1/dl/getContent/644001 | | 129 | +-----------------+-------------------------------------------------------------------------+-------------+ 130 | | | | | 131 | +-----------------+-------------------------------------------------------------------------+-------------+ 132 | | YAML config | https://github.com/joshloo/fsp_yaml_cfg/tree/master/Tools/UserManuals | | 133 | +-----------------+-------------------------------------------------------------------------+-------------+ 134 | | coreboot | https://github.com/coreboot/coreboot | | 135 | +-----------------+-------------------------------------------------------------------------+-------------+ 136 | | Oreboot | https://github.com/oreboot/oreboot | | 137 | +-----------------+-------------------------------------------------------------------------+-------------+ 138 | | Min platform | https://www.tianocore.org | | 139 | +-----------------+-------------------------------------------------------------------------+-------------+ 140 | | u-boot | https://github.com/u-boot/u-boot | | 141 | +-----------------+-------------------------------------------------------------------------+-------------+ 142 | | Slim bootloader | https://slimbootloader.github.io/ | | 143 | +-----------------+-------------------------------------------------------------------------+-------------+ 144 | | Payload | https://github.com/universalpayload/documentation | | 145 | +-----------------+-------------------------------------------------------------------------+-------------+ 146 | | libspdm | https://github.com/DMTF/libspdm | | 147 | +-----------------+-------------------------------------------------------------------------+-------------+ 148 | 149 | Architecture 150 | ------------ 151 | 152 | The following section describes the architecture of the POL. 153 | 154 | POL Overview 155 | ~~~~~~~~~~~~ 156 | 157 | Following the guiding principles in chapter 1.2, the high-level 158 | architecture of POL is shown in Figure 2. POL interfaces with the sFSP 159 | API specification, e.g. the 6 APIs and HOB/UPD defined in FSP 2.2 spec. 160 | On the other end, POL interfaces with the universal payload. It should 161 | invoke the payload API after providing board initialization. 162 | 163 | Within the POL, it has several stages: 164 | 165 | - POL early initialization 166 | 167 | - Maps to 168 | 169 | - coreboot romstage 170 | 171 | - EDKII SEC/PEI 172 | 173 | - Slim bootloader stage 1 174 | 175 | - POL late initialization 176 | 177 | - Maps to 178 | 179 | - Coreboot ramstage 180 | 181 | - Slim bootloader stage 2 182 | 183 | - EDKII DXE 184 | 185 | - POL runtime 186 | 187 | - OEM SMM 188 | 189 | .. image:: images/image4.PNG 190 | :alt: POL High Level Architecture 191 | :width: 4.16992in 192 | :height: 3.125in 193 | 194 | Figure 3 POL High Level Architecture 195 | 196 | Another aspect of the POL is to allow for maximum platform code re-use 197 | across different SOC generations. 198 | 199 | .. image:: images/image5.PNG 200 | :alt: POL re-use 201 | :width: 6.36547in 202 | :height: 1.21892in 203 | 204 | Figure 4 POL re-use 205 | 206 | Beyond re-use of platform code with different SOC’s, the POL should be 207 | re-useable across the most used or popular boot paradigms such as a full 208 | UEFI boot, LinuxBoot, VaultBoot or an embedded hypervisor. 209 | 210 | .. image:: images/image6.PNG 211 | :alt: Different Payloads 212 | :width: 6.5in 213 | :height: 2.34653in 214 | 215 | Figure 5 Different Payloads 216 | 217 | The Universal Payload provides the right hand side interface. There 218 | could be additional payloads, such as an XPU initialization payload or a 219 | validation payload, such as FSP-V. But in either case the POL 220 | implementation should be largely independent of the SOC and the payload. 221 | 222 | Finally, UFS allows for a world where there are various compositions of 223 | the firmware stack. This can include RUST-based firmware as either a 224 | payload or the platform layer implementation, as described in the figure 225 | below: 226 | 227 | .. image:: images/image7.png 228 | :width: 5in 229 | :height: 2.8125in 230 | 231 | **Figure 6 Modern language-based usage** 232 | 233 | This architecture is based upon https://github.com/jyao1/rust-firmware. 234 | 235 | The rust API for FSP wrapper is at https://github.com/jyao1/rust-firmware/tree/master/rust-fsp-wrapper. 236 | 237 | Configuration Introduction 238 | -------------------------- 239 | 240 | The Platform Orchestration Layer (POL) is aimed to provide guidelines on writing platform code that leverage a Scalable Intel Firmware Support Package (sFSP) interface and payload to coordinate the overall platform initialization flow. It needs to expose configuration, as do the layers below. 241 | 242 | To that end, YAML, which is a variant of JSON that allows for embedding comments, is employed in order to have a consistent language across various codebase configuration efforts. 243 | 244 | Platform configuration 245 | ~~~~~~~~~~~~~~~~~~~~~~ 246 | 247 | **Goals of the Configuration Efforts** 248 | 249 | * Normalize how configuration is done across various codebases and firmware domains (e.g. FSP, Boot Firmware, other on-board devices). 250 | 251 | - Deliver a unified API-based FW programming model across bootloaders for all Intel platforms, XPUs/SOCs, and IPs. 252 | 253 | * Make adoption by stakeholders/partners as pain-free as possible. 254 | 255 | - Prepare internal stakeholders, ecosystem partners, and customers to take advantage of the transition to a common configuration paradigm. 256 | 257 | **Why do this?** 258 | 259 | * Intel has stakeholders and customers with investments in a variety of codebases, each of which have different underlying methods for firmware configuration. 260 | 261 | * This makes it difficult to have a consistent user/developer experience when configuring platforms based on various underlying firmware technologies. This is a problem for both internal stakeholders and Intel customers. 262 | 263 | .. image:: images/POL_common_config_tool_diagram.png 264 | :alt: new common config tool diagram 265 | 266 | *New common config tool diagram* 267 | 268 | **Tasks associated with the effort** 269 | 270 | Create a unified approach to configuring a platform regardless of the underlying codebase without requiring the product group to change what they’re doing in any significant way. Low touch/Enable via tools. 271 | 272 | * Assume no significant changes needed in the native codebase to support this solution. 273 | 274 | * Use YAML to express configuration data 275 | 276 | * Gap analysis between the various config methodologies 277 | 278 | - XML-->YAML, BSF-->YAML, VPD/HII/etc --> YAML 279 | 280 | * Create build-time tools to import codebase config data, modify it, and export it back into its native form. 281 | 282 | - This is especially important and useful when some codebases have config data scattered in many places, thus increasing the usability for developers in configuring the defaults of the codebase. 283 | 284 | * Runtime config 285 | 286 | - Scripting in runtime may be needed for manufacturing line usage etc – something to consider. 287 | 288 | * Telemetry? 289 | 290 | - Address how we expose necessary data from the machine. 291 | 292 | * Port ESRT content into an ACPI context. 293 | 294 | - More easily enable firmware updates without an underlying UEFI infrastructure/assumption. 295 | 296 | Although the POL strives to be SOC independent, the system board’s SOC, with its respective sFSP, and the usage of payloads, may require different configuration. To that end, a consistent set of YAML based configuration will be exposed to the system board builder and platform user to configure the various elements. 297 | 298 | 299 | YAML based settings 300 | ^^^^^^^^^^^^^^^^^^^ 301 | 302 | Although the POL strives to be SOC independent, the system board’s SOC, 303 | with its respective sFSP, and the usage of payloads, may require 304 | different configuration. To that end, a consistent set of YAML based 305 | configuration will be exposed to the system board builder and platform 306 | user to configure the various elements. 307 | 308 | YAML based configuration will be provided to abstract all of the 309 | platform configurable elements 310 | 311 | - sFSP UPD 312 | 313 | - Platform configuration 314 | 315 | - PCD/VFR for EDKII 316 | 317 | - KConfig for coreboot/oreboot/u-boot 318 | 319 | - DSC for slim bootloader 320 | 321 | - YAML native for XPU payload 322 | 323 | Example configuration 324 | ^^^^^^^^^^^^^^^^^^^^^ 325 | 326 | An example of an often configurable object for the platform developer is 327 | GPIO. 328 | 329 | An example of GPIO configuration is as follows: 330 | 331 | - $ACTION : 332 | 333 | page : GIO 334 | 335 | - GPIO_CFG_DATA : 336 | 337 | - !expand { CFGHDR_TMPL : [ GPIO_CFG_DATA, 0x400, 1, 0 ] } 338 | 339 | - GPIO_CFG_HDR : 340 | 341 | - GpioHeaderSize : 342 | 343 | length : 0x01 344 | 345 | value : \_LENGTH_GPIO_CFG_HDR\_ 346 | 347 | - GpioBaseTableId : 348 | 349 | length : 0x01 350 | 351 | value : 0xFF 352 | 353 | - GpioItemSize : 354 | 355 | length : 0x02 356 | 357 | value : 8 358 | 359 | - GpioItemCount : 360 | 361 | length : 0x02 362 | 363 | value : (_LENGTH_GPIO_CFG_DATA\_ - \_LENGTH_GPIO_CFG_HDR\_ - 8) / 8 364 | 365 | # Bit start offset within each GPIO entry array to identify a GPIO pin 366 | uniquely. EX: GPIO group id + pad id 367 | 368 | # Offset is 2nd DWORD BIT16 = 1 \* 32 + 16 = 48 369 | 370 | - GpioItemIdBitOff : 371 | 372 | length : 0x01 373 | 374 | value : 48 375 | 376 | # Bit length within each GPIO entry array to identify a GPIO pin 377 | uniquely. 378 | 379 | # Length is 2nd DWORD BIT16 to BIT28 = 13 380 | 381 | - GpioItemIdBitLen : 382 | 383 | length : 0x01 384 | 385 | value : 13 386 | 387 | # Bit offset within each GPIO entry array to indicate SKIP a GPIO 388 | programming 389 | 390 | # Offset is 2nd DWORD BIT31 = 63 391 | 392 | - GpioItemValidBitOff : 393 | 394 | length : 0x01 395 | 396 | value : 63 397 | 398 | - GpioItemUnused : 399 | 400 | length : 0x01 401 | 402 | value : 0 403 | 404 | # Need 1 bit per GPIO. So this mask byte length needs to be at least 405 | (GpioNumber + 7) / 8 406 | 407 | # Padding can be added to let the whole length aligned at DWORD boundary 408 | 409 | - GpioBaseTableBitMask : 410 | 411 | length : 38 412 | 413 | value : {0} 414 | 415 | - GpioTableData : 416 | 417 | length : 0 418 | 419 | value : 0 420 | 421 | 1.1.1 Example implementation 422 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 423 | 424 | An example of implementation in EDKII is Intel Seamless Board 425 | Configuration (SBC). This feature provides a standardized and 426 | centralized interface for various board HW configuration, including 427 | GPIO, PCIe Clock, USB OC, DRAM, I2C, etc. The interface currently is 428 | leveraging Structured PCD in VPD which allows both manually and tool 429 | assisted modification for different HW setting in EDK2 Platform Payload. 430 | 431 | SBC also supports multiple board configuration scenario with board 432 | identifier mapped to SkuId in EDKII PCD. 433 | 434 | .. image:: images/image8.png 435 | :width: 4.4375in 436 | :height: 2.86458in 437 | 438 | Figure 6 Board configuration 439 | 440 | Example implementation with Structured PCD: 441 | 442 | gBoardModuleTokenSpaceGuid.VpdPcdBoardGpioTable|*|{CODE({ 443 | 444 | | {GPIO_PIN_1, {GpioSettingA,GpioSettingB, GpioSettingC, ...}}, 445 | | {GPIO_PIN_2, {GpioSettingA,GpioSettingB, GpioSettingC, ...}}, 446 | | … 447 | 448 | {0x0} // terminator 449 | 450 | })} 451 | 452 | Components in EDKII Bootloader will consume these HW configuration while 453 | the configuration data is already selected based on SkuId during POST. 454 | Then these setting will be applied into silicon or board HW via sFSP. 455 | Necessary information will also be wrapped and passed to OS, such as 456 | GPIO related setting in ACPI Table. 457 | 458 | Shareable platform code 459 | ~~~~~~~~~~~~~~~~~~~~~~~ 460 | 461 | For the platform implementation, there are two means of code sharing. 462 | One way to share content is via binary universal payloads, and the other 463 | is via source code. 464 | 465 | TBD – example source code. Cite moving of PciBus DXE driver to slim 466 | bootloader stage 2 code 467 | 468 | OpenSPDM example as source code for sharing across POL implementations. 469 | 470 | Advanced features represent a set of platform technologies that are not 471 | needed for basic boot. These features provide a way to extend the 472 | platform firmware capabilities. 473 | 474 | For these features to be sharable and extensible, they must adopt a 475 | high-cohesive, low-coupling design. This means an advanced feature 476 | should be mostly self-contained and expose a set of well defined 477 | interfaces that can be called by components outside the feature scope. 478 | 479 | An advanced feature should not directly depend on another advanced 480 | feature. Such a dependency should be resolved via an integration layer 481 | (e.g. Board layer). The following represents a high level design of 482 | Advanced Features. 483 | 484 | +-------------+ 485 | | AFP1 | 486 | +=============+ 487 | | AFP2 | 488 | +-------------+ 489 | | AFP3 | 490 | +-------------+ 491 | | AFP4 | 492 | +-------------+ 493 | | Board Layer | 494 | +-------------+ 495 | 496 | Advanced feature details 497 | ~~~~~~~~~~~~~~~~~~~~~~~~ 498 | 499 | The low-level design and implementation of Advanced feature may vary 500 | based on boot loaders and other preferences. 501 | 502 | The EDKII Min Platform boot loader follows a rich set of design 503 | guidelines conforming EDKII software framework and UEFI specification. 504 | 505 | Examples of construction of a Min Platform can be found at 506 | https://github.com/tianocore/edk2-platforms/blob/master/Platform/Intel/MinPlatformPkg/Docs/A_Tour_Beyond_BIOS_Open_Source_IA_Firmware_Platform_Design_Guide_in_EFI_Developer_Kit_II%20-%20V2.pdf 507 | 508 | Shareable platform code - definition 509 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 510 | 511 | +In this specification, the shareable platform code focuses on **source 512 | code sharing**. Binary sharing should be considered in scalable FSP. 513 | 514 | 1. The shareable platform code SHALL be reusable by multiple 515 | bootloaders, including but not limited, to EDKII, slim bootloader, 516 | coreboot. 517 | 518 | 2. The shareable platform code SHOULD be reusable across different boot 519 | phase, such as EDKII PEI/DXE/SMM phase, the coreboot ROM/RAM stage. 520 | This highly depends upon the use case. 521 | 522 | 3. The shareable platform code MAY be used for other firmware. For 523 | example, the `libspdm `_ library may be used for system firmware, BMC 524 | firmware, or even device firmware. It also depends upon the use case 525 | – if there is business need for sharing. 526 | 527 | Shareable platform code - guideline 528 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 529 | 530 | 1. Don’t consume any boot load specific API. For example, UEFI boot 531 | services, PCI IO Protocol. 532 | 533 | 2. Don’t consume standard C library. Not all boot load includes standard 534 | C library. 535 | 536 | 3. Use static link library if possible. Don’t use dynamic link library. 537 | 538 | 4. Use heap carefully. Some environment might not have heap. 539 | 540 | 5. Use global variable carefully. Some environment may only support 541 | read-only variable because the code runs on the flash. 542 | 543 | 6. Don’t use inline assembly. Some build environment may not support 544 | inline assembly. 545 | 546 | 7. Another guideline is to not expose internal function in public header 547 | file. The internal header file should be hidden. 548 | 549 | 8. Define the boot loader provided library dependency clearly, such as 550 | Hardware Abstract Layer (HAL). It can make library porting easier. 551 | 552 | 9. Define the boot loader caller provided function dependency clearly, 553 | such as a callback function. 554 | 555 | Shareable platform code – RUST binding API 556 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 557 | 558 | 1. Include length parameter for any buffer. 559 | 560 | 2. Have single owner for one buffer. If the caller allocates the buffer, 561 | the caller shall free the buffer. 562 | 563 | 3. Define the contract between the caller and callee. E.g. If the input 564 | buffer is trusted or untrusted? 565 | 566 | 4. Define the error behavior clearly. Return? Deadloop? Assert? 567 | 568 | Interface definitions 569 | ~~~~~~~~~~~~~~~~~~~~~ 570 | 571 | Shareable platform code APIs 572 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 573 | 574 | Min Platform Advanced Feature Packages (AFP) in EDKII, coreboot 3rd party directory code 575 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 576 | 577 | Provide example of the Pci enumeration code/library 578 | 579 | Show the generic code such as sharable `libspdm `_ 580 | 581 | Shareable board ASL 582 | ^^^^^^^^^^^^^^^^^^^ 583 | 584 | TBD 585 | ''' 586 | 587 | Shareable platform code APIs – Rust bindings 588 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 589 | 590 | A Rust library can be created on top of C - API. For example: 591 | 592 | * `rust-openssl `_ is a Rust binding for `openssl `_ library. 593 | 594 | * `rust-mbedtls `_ is a Rust binding for `mbedtls `_ library. 595 | 596 | In firmware, we have below example: 597 | 598 | * `r-efi `_ defines a set of Rust style UEFI data structure. 599 | 600 | * `uefi-rs `_ provides a set of UEFI services interface in Rust. 601 | 602 | * `rust-fsp-wrapper `_ provides a set of Intel FSP APIs for the FSP wrapper. 603 | 604 | 605 | XPU considerations 606 | ------------------ 607 | 608 | One of the goals of the USF effort is to help support all classes of 609 | silicon , namely XPU’s. An XPU can be a CPU, such as the SOC based upon 610 | Intel Core, Intel Atom, RISC-V or ARM. In addition, the XPU can include 611 | integrated or discrete graphics (iGFX/dGFX), FPGA, AI, networking, or 612 | acceleration. 613 | 614 | To that end, there are various aspects of the XPU support. 615 | 616 | These include configuration, update, monitoring, and access, both during 617 | the pre-OS and at OS runtime. In the future the latter may move into 618 | level 0, but for now the USF shall treat these. 619 | 620 | Like other aspects of USF, XPU considerations are in the POL 621 | specification since the platform is where all of the system components 622 | come together. 623 | 624 | Configuration 625 | ~~~~~~~~~~~~~ 626 | 627 | To configure the XPU, a canonical YAML based configuration file will be 628 | provided. 629 | 630 | Build time 631 | ^^^^^^^^^^ 632 | 633 | Post ship 634 | ^^^^^^^^^ 635 | 636 | Pre-OS 637 | '''''' 638 | 639 | Runtime 640 | ''''''' 641 | 642 | Initialization 643 | ~~~~~~~~~~~~~~ 644 | 645 | Initialization can include having the XPU as part of the sFSP, a 646 | dedicated payload, a UEFI or legacy BIOS option ROM, or some open source 647 | POL portable library. 648 | 649 | Open source portable initialization code 650 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 651 | 652 | Dedicated payload 653 | ^^^^^^^^^^^^^^^^^ 654 | 655 | Option ROM (e.g., dGFX or networking HBA) 656 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 657 | 658 | sFSP element (e.g., iGFX in Core CPUs) 659 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 660 | 661 | Update 662 | ~~~~~~ 663 | 664 | It is critical to support both the factory time integration of the XPU 665 | support into the IFWI and/or post ship update of XPU support code. 666 | 667 | Slim bootloader update payload 668 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 669 | 670 | Overview 671 | '''''''' 672 | 673 | SBL embedded a built-in Firmware Update (FWU) payload to perform a 674 | secure and power fail-safe firmware update flow. It contains redundant 675 | boot partitions and depends on hardware assisted boot partition switch 676 | to support fail-safe update. 677 | 678 | SBL provides abstracted ACPI/WMI interface to trigger FWU flow, EDK2 679 | similar capsule update mechanism to pass the new firmware to bootloader, 680 | and EDK2 similar way to report the FWU status back to OS through ACPI 681 | table. 682 | 683 | Firmware Update Flow 684 | '''''''''''''''''''' 685 | 686 | SBL firmware update flow utilizes redundant boot partition to perform 687 | firmware update in a reliable way. It involves the following high-level 688 | steps: 689 | 690 | - Boot from Partition A 691 | 692 | - Update Partition B 693 | 694 | - Activate Partition B 695 | 696 | - Reboot 697 | 698 | - Boot from Partition B 699 | 700 | - Update Partition A 701 | 702 | - Activate Partition A 703 | 704 | - Reboot 705 | 706 | - Report Firmware Update status 707 | 708 | - Terminate firmware update flow. 709 | 710 | - Reset system to continue booting to operating system. 711 | 712 | Below is a detailed FWU flow chart for SBL. 713 | 714 | .. image:: images/image9.png 715 | :width: 6.14124in 716 | :height: 4.89583in 717 | 718 | Figure 7 719 | 720 | - Firmware Update capsule is copied to designated location. This 721 | location is configurable through SBL configuration options. 722 | 723 | - Firmware update is triggered from SBL shell or from Operating system 724 | and followed by a system reset. 725 | 726 | - SBL detects firmware update signal and sets platform into firmware 727 | update mode. 728 | 729 | - SBL identifies firmware update mode and loads firmware update payload 730 | to start update flow. 731 | 732 | - Firmware Update payload gathers capsule image from selected media and 733 | verifies capsule data. If successful, continues with firmware update. 734 | 735 | - Firmware update payload initializes state machine and identifies the 736 | update images in the capsule. 737 | 738 | - FWU payload loops through and updates each firmware identified in the 739 | capsule image. 740 | 741 | - FWU records update status after each firmware update. 742 | 743 | - If the firmware is requesting reset after update, reset the system to 744 | continue updating other firmware in the capsule. 745 | 746 | - In case of a power failure, FWU payload will use the state machine 747 | stored in flash to resume from the interrupted state. 748 | 749 | Firmware Update Triggering 750 | '''''''''''''''''''''''''' 751 | 752 | SBL provides a platform independent abstracted way of triggering 753 | firmware update from operating system through ACPI or WMI interfaces. 754 | 755 | SBL provides common ACPI methods, DWMI.WQ00 for read and DWMI.WS00 for 756 | write to a platform specific chipset register that can survive a reset 757 | to signal firmware update. This ACPI method can be called by driver or 758 | application to request triggering a firmware update. On the following 759 | reboot flow, once the firmware update signal is detected, this signal 760 | will be stored into flash so that the following firmware update flow can 761 | resume in case of a power failure in the middle of the process. 762 | 763 | For OS that supports WMI, such as Windows, SBL further exposes 764 | AcpiFirmwareCommunication WMI service through ACPI table to allow 765 | triggering firmware updates directly using WMI from applications. 766 | 767 | Firmware Update Status 768 | '''''''''''''''''''''' 769 | 770 | SBL reports firmware update status through custom defined Firmware 771 | Update status (FWST) ACPI table. FWST ACPI table will be available as 772 | part of RSDT and can be identified with a table signature “FWST”. FWST 773 | ACPI table makes use of EFI_SYSTEM_RESOURCE_TABLE defined in UEFI 774 | specification to report firmware update status. It adds additional ACPI 775 | header on top of it to make it conform to ACPI speciation. OS can use 776 | this ACPI table to retrieve the previous firmware update information. 777 | 778 | UEFI capsule update 779 | ^^^^^^^^^^^^^^^^^^^ 780 | 781 | AB update of payload for coreboot 782 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 783 | 784 | Monitoring 785 | ~~~~~~~~~~ 786 | 787 | The ability to ascertain status of the platform and XPU’s has various 788 | modalities. 789 | 790 | UEFI tables 791 | ^^^^^^^^^^^ 792 | 793 | ACPI 794 | ^^^^ 795 | 796 | POL examples 797 | ------------ 798 | 799 | This chapter gives a reference implementation of POL under EDKII 800 | framework. Below shows the code layout that POL has a dedicated package 801 | to hold all POL related code. 802 | 803 | Slim bootloader 804 | ~~~~~~~~~~~~~~~ 805 | 806 | Slim Bootloader (SBL) is a flexible, lightweight, and open-source 807 | reference boot loader solution designed for Intel platforms. SBL is 808 | architected with a modular approach by providing very basic hardware 809 | initialization in bootloader, then launching a payload to boot to final 810 | OS or application. The payload is flexible and can be at user’s choice 811 | to meet special needs. The SBL overall architecture is shown in the 812 | diagram below: 813 | 814 | .. image:: images/image10.png 815 | :width: 6.36458in 816 | :height: 2.10417in 817 | 818 | Figure 8: SBL Architecture 819 | 820 | SBL takes a linear staged boot approach to initialize the platform. As 821 | illustrated in the diagram below, in each stage, SBL utilizes Intel® FSP 822 | API interfaces to initialize the silicon and utilizes static library 823 | interfaces to initialize the board. 824 | 825 | .. image:: images/image11.png 826 | 827 | **Figure 9: SBL Linear Staged Boot Approach** 828 | 829 | These static library interfaces are aligned with EDK2 base library implementation to the abstract board initialization API. For examples, see Figure 9 above and GPIO initialization, ACPI 830 | initialization, etc. 831 | 832 | The detailed SBL stages are listed in the table below: 833 | 834 | +----------+----------------------------------------------------------+ 835 | | Stage | Description | 836 | +==========+==========================================================+ 837 | | Stage 1A | Stage 1A contains reset vector and is first stage to | 838 | | | gain control. It is responsible for very basic platform | 839 | | | execution environment initialization to enable following | 840 | | | stage execution. It includes temporary memory, debug | 841 | | | port, etc. | 842 | +----------+----------------------------------------------------------+ 843 | | Stage 1B | Stage 1B is the “pre-memory” stage and is responsible | 844 | | | for loading configuration data and initialization system | 845 | | | main memory. After memory is available, it will load and | 846 | | | verify Stage2 for execution. | 847 | +----------+----------------------------------------------------------+ 848 | | Stage 2 | Stage 2 is the “post-memory” stage and is responsible | 849 | | | for all initialization the remaining platform, including | 850 | | | chipset, CPU, I/O, ACPI, PCI, etc. | 851 | +----------+----------------------------------------------------------+ 852 | | Payload | Payload is the bridge between bootloader and the OS. It | 853 | | | provides standard boot device initialize to further | 854 | | | load, verify and launch OS images. It also performs | 855 | | | specific actions, such as firmware update. | 856 | +----------+----------------------------------------------------------+ 857 | 858 | As stated above, SBL utilizes static library class to abstract the API 859 | interfaces for platform initialization. These libraries are written in 860 | pure C language so that it can easily be shared between different boot 861 | solutions. For example, many base library instances in EDK2 MdePkg are 862 | directly leveraged by SBL. Many other libraries, such as SoC access 863 | libraries, feature libraries are also ported from corresponding EDK2 864 | libraries through removing UEFI specific dependencies. In addition, ACPI 865 | ASL files are also borrowed from EDK2 directly. These sharable libraries 866 | and files make it easier to quickly enable a platform using the boot 867 | solution at user’s choice. 868 | 869 | .. image:: images/image12.png 870 | :width: 5in 871 | :height: 3.03125in 872 | 873 | u-boot 874 | ~~~~~~ 875 | 876 | U-Boot can be fabricated as a POL or a payload. 877 | 878 | Oreboot 879 | ~~~~~~~ 880 | 881 | Oreboot is a RUST-based POL example 882 | 883 | coreboot 884 | ~~~~~~~~ 885 | 886 | coreboot is a POL example 887 | 888 | EDKII 889 | ~~~~~ 890 | 891 | | EDKII can be used to create an FSP, such as 892 | https://github.com/tianocore/edk2/tree/master/IntelFsp2Pkg described in https://www.intel.com/content/dam/develop/public/us/en/documents/a-tour-beyond-bios-creating-the-intel-firmware-support-package-with-the-efi-developer-kit-ii-fsp2-0.pdf 893 | | EDKII can also be a POL, including the MinPlatform 894 | https://github.com/tianocore/edk2-platforms/blob/master/Platform/Intel/Readme.md. 895 | 896 | EDKII can also be used to create a payload, such as 897 | https://github.com/tianocore/edk2/tree/master/UefiPayloadPkg. 898 | 899 | Components 900 | ^^^^^^^^^^ 901 | 902 | Components in EDKII based firmware can be separated into three 903 | categories: 904 | 905 | - EDKII Bootloader 906 | 907 | - UEFI Universal Payload 908 | 909 | - EDKII UEFI Platform Payload (Optional) 910 | 911 | .. image:: images/image13.png 912 | :width: 6.5in 913 | :height: 0.79583in 914 | 915 | **Figure 10** 916 | 917 | The system boot starts from EDKII Bootloader where the FSP is invoked to 918 | initialize the silicon. Then the Bootloader follows the Payload 919 | specification to load and start UEFI Universal Payload. It may pass 920 | additional FV location information to UEFI Universal Payload which tells 921 | the optional EDKII UEFI Platform Payload. 922 | 923 | EDKII Bootloader consists of reset vector code, necessary platform 924 | specific code and EDKII generic code that launches FSP. In the end of 925 | EDKII Bootloader, it transfers the control from EDKII Bootloader to UEFI 926 | Universal Payload through DxeIpl PEIM. Each platform vendor develops its 927 | EDKII Bootloader and the implementations for different platforms are 928 | different. 929 | 930 | UEFI Universal Payload consists of all the platform agnostic drivers 931 | that prepare the UEFI OS booting environment. For example, the RTC 932 | driver to support UEFI time services, the MTC driver to support the UEFI 933 | Monotonic Counter services. The “Universal” in the name stands for the 934 | goal that the same payload binary can be used by different bootloaders 935 | and different platforms. There is only one implementation instance of 936 | the UEFI Universal Payload. For example, Slim bootloader and EDKII 937 | Bootloader can boot to UEFI OS by using the same UEFI Universal Payload. 938 | All the SOC and platform specific information is abstracted in EDKII 939 | Bootloader and passed to UEFI Universal Payload. The abstraction format 940 | is defined by Payload specification. 941 | 942 | EDKII UEFI Platform Payload is an optional component. It consists of 943 | platform specific implementations: 944 | 945 | .. image:: images/image14.png 946 | 947 | that must be done in payload phase. 948 | 949 | Theoretically this component can be eliminated by moving all 950 | implementations to EDKII Bootloader. 951 | 952 | Figure 11 953 | 954 | Data Flow 955 | ^^^^^^^^^ 956 | 957 | EDKII Bootloader passes SOC and platform information through HOBs to 958 | UEFI Universal Payload. UEFI Universal Payload interacts with EDKII UEFI 959 | Platform Payload through Protocols. EDKII Bootloader can use any 960 | mechanism to pass information to EDKII UEFI Platform Payload since both 961 | are owned by the platform vendor. 962 | 963 | .. image:: images/image15.png 964 | :alt: Universal Payload, UEFI Platform Payload, and EDKII Bootloader 965 | :width: 6.5in 966 | :height: 2.86319in 967 | 968 | **Figure 12: Universal Payload, UEFI Platform Payload, and EDKII Bootloader** 969 | 970 | --------------------------------------------------------------------------------