I'd like to do a point release of EBBR in the near future. There is an important change to how RuntimeServicesSupported is described in the UEFI spec that needs to be adjusted in EBBR, and the DTB UUID was missing. The rest of the changes are minor editorial and typo fixes.
I've tagged v1.0.1-rc1 in github for review. Full diff is below. Please review and comment.
Thanks, g.
---
.travis.yml | 82 +++++++++++++++++------------------------ CONTRIBUTING.rst | 23 +----------- source/chapter2-uefi.rst | 40 +++++++++++++++++--- source/chapter3-secureworld.rst | 6 +-- source/index.rst | 3 ++ source/references.rst | 10 ++--- 6 files changed, 81 insertions(+), 83 deletions(-)
---
diff --git a/.travis.yml b/.travis.yml index 3688a67..4a63cb0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,63 +1,49 @@ sudo: false dist: trusty - cache: apt: true - env: global: - - SPHINXBUILD=~/.local/bin/sphinx-build - - DIFF_COMMIT=v0.5 - + - SPHINXBUILD=~/.local/bin/sphinx-build + - secure: Nn985mEk01BbYLY7IQToa51+jpVp8/f72Q+SY6GVe1cf41gRG4CWrrLFLo4Zrdd+e5a9tMKJ2o6WqT4m0i1AziVnoFx62QtC0dmJVsp4eVzQdhWkaRTcLdoKp18om0To6cVmBzYFzsIUROyOwwJfprpzwylQGFqNFoNG20UmnzTy5c/bg36Ohh/vcpt3HXO6emKDTychu1fBC8tuiy7k5BCfPekKAg6sKTqjsgKM+pEZuv9zTzrBY0HVqCoSLhWUraADko51baOtbBOzLtH4L4EO1rmiFs7/HpN/MzF6REurCAbBM5q82aS/z5KUoMGENt+OwWbeT9BcqUty1wYAFwuK7UwkDO2+YauqGhZ75GKOt213Fdn70Wx1xMkOerdEb8oSdH8Av/FWxwbfI6qxsAhjimYTZ5OCCZu06AVMBugxBnZeYxF89+83qVUxCHNGyGnql1PHJnlIiOzmCmcgjFo90u9fv24497m9O9QlEic/PnN0VLogPOftgcRUdoLjsYh9P6+BvXrWQ0omu41UwnzNJERaeUXuXV+iJsj6kBuj1j6EJ7OK4RyS/Td8mC7sGFBdwOX+HLaPqBTD2rm7z0wtST0jyFJjPfmvCU94+ovpCuYeMxgeudnUXT8T26v6v73nk7QLIIYm1Idg2ibSBfQy5IT220sH6291IryoY2c= git: depth: false - addons: apt: packages: - - python-pip - - latexmk - - libalgorithm-diff-perl - - texlive - - texlive-latex-extra - - texlive-humanities - - texlive-generic-recommended - - graphviz - - texlive-generic-extra - + - python-pip + - latexmk + - libalgorithm-diff-perl + - texlive + - texlive-latex-extra + - texlive-humanities + - texlive-generic-recommended + - graphviz + - texlive-generic-extra install: - - pip install --user mako - - pip install --user Sphinx - -before_script: - - wget https://github.com/ftilmann/latexdiff/releases/download/1.2.1/latexdiff-1.2.... - - tar xvf latexdiff-1.2.1.tar.gz - - export PATH=$PWD/latexdiff-1.2.1/:$PATH - +- pip install --user mako +- pip install --user Sphinx script: - - make latexpdf - - make html - - make singlehtml - +- make latexpdf +- make html +- make singlehtml before_deploy: - - cp build/latex/ebbr.pdf build/ebbr-$TRAVIS_TAG.pdf - +- cp build/latex/ebbr.pdf build/ebbr-$TRAVIS_TAG.pdf deploy: - - provider: releases - prerelease: true - api_key: - secure: QAzEatdHC5w1uC06y6ceeRwL6dXhTz8DmkvIirXbv9paEKC7OHpsNm2NtCvLQDLnT98CFBj64y13P29DTYV0ExHNExnixP+R0b9G5kvCG/mGf+k6teXJmtsDRezTCmqAWwxLp70rewcHM+gQ1SdRy+HlHuVC5D70p99vv/f5hK/6f/PodxB0ftrvmb2S+B733+O7kiEKvBZUq/gaX5MTe8x+N09W+4SUTC4Xy5e0KlADfMWiLRhlJvU0PgtQ0IhRaeHnD+gmz/HUaUE/bsdXzIwv9Vb3p9eVmXLj1nE+p1toM5MJwmpKClXgph55PsD2X9xBSwxBhHZ3JOCl6QCOYaqkNvcE0U3e3QzC1b92EHoHN5vMrZenkALe0y1z1u1G+cZybjUEQ2lTmNq1HmO/QLdVHBCShR9xkpjm+8m//NXON8TDgP5z+hIU/g2NLfcSLdinogRLz2vnSmR6SjWzhH8q29d+wg3f5//eMgTCQF1dSRvNt8SjYUQDrW9z1k4dV64Jcn5AWjWmcaErG2D8jWJQGzzrts84Hcv3N7fRUwvMxdQOQDvoMaIxNxg35rBsuGa1tJkLyurOW31uwbOzrLlRSEcypPimpFQWysBwnX+aNTudhY0Dv4HKSIO12iZdIz9pbsMrJCBMCQdAydIDj35Fu5tJ5Ns4/JRaw5IoBQU= - file_glob: true - file: - - "build/ebbr-*.pdf" - skip_cleanup: true - on: - tags: true - branch: master - - provider: pages - github_token: $GITHUB_TOKEN - local_dir: "build/singlehtml" - skip_cleanup: true - on: - branch: master - +- provider: releases + prerelease: true + api_key: + secure: QAzEatdHC5w1uC06y6ceeRwL6dXhTz8DmkvIirXbv9paEKC7OHpsNm2NtCvLQDLnT98CFBj64y13P29DTYV0ExHNExnixP+R0b9G5kvCG/mGf+k6teXJmtsDRezTCmqAWwxLp70rewcHM+gQ1SdRy+HlHuVC5D70p99vv/f5hK/6f/PodxB0ftrvmb2S+B733+O7kiEKvBZUq/gaX5MTe8x+N09W+4SUTC4Xy5e0KlADfMWiLRhlJvU0PgtQ0IhRaeHnD+gmz/HUaUE/bsdXzIwv9Vb3p9eVmXLj1nE+p1toM5MJwmpKClXgph55PsD2X9xBSwxBhHZ3JOCl6QCOYaqkNvcE0U3e3QzC1b92EHoHN5vMrZenkALe0y1z1u1G+cZybjUEQ2lTmNq1HmO/QLdVHBCShR9xkpjm+8m//NXON8TDgP5z+hIU/g2NLfcSLdinogRLz2vnSmR6SjWzhH8q29d+wg3f5//eMgTCQF1dSRvNt8SjYUQDrW9z1k4dV64Jcn5AWjWmcaErG2D8jWJQGzzrts84Hcv3N7fRUwvMxdQOQDvoMaIxNxg35rBsuGa1tJkLyurOW31uwbOzrLlRSEcypPimpFQWysBwnX+aNTudhY0Dv4HKSIO12iZdIz9pbsMrJCBMCQdAydIDj35Fu5tJ5Ns4/JRaw5IoBQU= + file_glob: true + file: + - build/ebbr-*.pdf + skip_cleanup: true + on: + tags: true + branch: master +- provider: pages + github_token: "$GITHUB_TOKEN" + local_dir: build/singlehtml + skip_cleanup: true + on: + branch: master diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a5643a3..7021f0f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -8,35 +8,14 @@ Anyone may contribute to the EBBR project. Contributions are licensed under CC-BY-SA-4.0_ and must be made with a Developer Certificate of Origin (DCO_) attestation as described below.
-EBBR discussion uses the boot-architecture_ and arm.ebbr-discuss mailing lists. -The 'official' list is arm.ebbr-discuss, but the list archives are not -yet public, so boot-architecture_ is being used to keep everything in -the open. +EBBR discussion uses the boot-architecture_ mailing list.
* boot-architecture@lists.linaro.org -* arm.ebbr-discuss@arm.com
Past discussions can be found in the boot-architecture-archive_.
We use the IRC channel `#ebbr`_ on OFTC_.
-There is a bi-weekly conference call to discuss EBBR topics on the 2nd -and 4th Tuesday of the month at 15:00 UTC/BST, 7:00 PST/PDT, 23:00/22:00 CST -(following UTC/BST daylight savings time shifts). -Anyone is welcome to join. - -- Online meeting: https://arm-onsite.webex.com/meet/gralik01 -- Phone - - - 1-408-792-6300 Call-in toll number (US/Canada) - - 1-877-668-4490 Call-in toll-free number (US/Canada) - - 44-203-478-5285 Call-in toll number (UK) - - 08-002061177 Call-in toll-free (UK) - - More access numbers: webex-global-numbers_ -- Access code: 809 053 990 - -.. _webex-global-numbers: https://arm-onsite.webex.com/cmp3300/webcomponents/widget/globalcallin/globa... - DCO Attestation ---------------
diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index f6a5802..c9c0101 100644 --- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -9,7 +9,7 @@ platforms.
UEFI Version ============ -This document uses version 2.7 of the UEFI specification [UEFI]_. +This document uses version 2.8 Errata A of the UEFI specification [UEFI]_.
UEFI Compliance =============== @@ -86,12 +86,41 @@ tables. - An Advanced Configuration and Power Interface [ACPI]_ table, or - a Devicetree [DTSPEC]_ system description
-As stated above, EBBR systems must not provide both ACPI and Devicetree +EBBR systems must not provide both ACPI and Devicetree tables at the same time. Systems that support both interfaces must provide a configuration mechanism to select either ACPI or Devicetree, and must ensure only the selected interface is provided to the OS loader.
+Devicetree +^^^^^^^^^^ + +If firmware provides a Devicetree system description then it must be provided +in Flattened Devicetree (DTB) format version 17 or higher as described in +[DTSPEC]_ § 5.1. +The following GUID must be used in the EFI system table ([UEFI]_ § 4) +to identify the DTB. +The DTB must be contained in memory of type EfiACPIReclaimMemory. + +.. code-block:: c + + #define EFI_DTB_GUID \ + EFI_GUID(0xb1b621d5, 0xf19c, 0x41a5, \ + 0x83, 0x0b, 0xd9, 0x15, 0x2c, 0x69, 0xaa, 0xe0) + +Firmware must have the DTB resident in memory and installed in the EFI system table +before executing any UEFI applications or drivers that are not part of the system +firmware image. +Once the DTB is installed as a configuration table, +the system firmware must not make any modification to it or reference any data +contained within the DTB. + +UEFI applications are permitted to modify or replace the loaded DTB. +System firmware must not depend on any data contained within the DTB. +If system firmware makes use of a DTB for its own configuration, +it should use a separate private copy that is not installed in the +EFI System Table or otherwise be exposed to EFI applications. + UEFI Secure Boot (Optional) ---------------------------
@@ -111,7 +140,7 @@ during both boot services and runtime services. However, it isn't always practical for all EFI_RUNTIME_SERVICES functions to be callable during runtime services due to hardware limitations. If any EFI_RUNTIME_SERVICES functions are only available during boot services -then firmware shall provide the global `RuntimeServicesSupported` variable to +then firmware shall provide the `EFI_RT_PROPERTIES_TABLE` to indicate which functions are available during runtime services. Functions that are not available during runtime services shall return EFI_UNSUPPORTED. @@ -148,7 +177,7 @@ Firmware shall not create runtime mappings, or perform any runtime IO that will conflict with device access by the OS. Normally this means a device may be controlled by firmware, or controlled by the OS, but not both. -e.g. If firmware attempts to access an eMMC device at runtime then it will +E.g. if firmware attempts to access an eMMC device at runtime then it will conflict with transactions being performed by the OS.
Devices that are provided to the OS (i.e., via PCIe discovery or ACPI/DT @@ -202,7 +231,8 @@ If a platform does not implement modifying non-volatile variables with SetVariable() after ExitBootServices(), then firmware shall return EFI_UNSUPPORTED for any call to SetVariable(), and must advertise that SetVariable() isn't available during runtime services -via the `RuntimeServicesSupported` variable as defined in UEFI version 2.8. +via the `RuntimeServicesSupported` value in the `EFI_RT_PROPERTIES_TABLE` +as defined in [UEFI]_ § 4.6. EFI applications can read `RuntimeServicesSupported` to determine if calls to SetVariable() need to be performed before calling ExitBootServices().
diff --git a/source/chapter3-secureworld.rst b/source/chapter3-secureworld.rst index 4e9fa61..9c51bca 100644 --- a/source/chapter3-secureworld.rst +++ b/source/chapter3-secureworld.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0
-****************************** -Priviledged or Secure Firmware -****************************** +***************************** +Privileged or Secure Firmware +*****************************
AArch32 Multiprocessor Startup Protocol ======================================= diff --git a/source/index.rst b/source/index.rst index 9bc4a09..7a5ded9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -45,6 +45,9 @@ Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 31 March 2019 1.0 - Remove unnecessary UEFI requirements appendix - Allow for ACPI vendor id in firmware path + 1 June 2020 1.0.1-rc1 - Update to UEFI 2.8 Errata A + - Specify UUID for passing DTB + - Typo and editorial fixes ================= ========= =============================================
.. toctree:: diff --git a/source/references.rst b/source/references.rst index a12c1a2..1eb0509 100644 --- a/source/references.rst +++ b/source/references.rst @@ -8,8 +8,8 @@ https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.2`_, `Devicetree.org https://devicetree.org`_
-.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.txt - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/tree/Documentation/arm64/booting.txt`_, +.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.rst + https://www.kernel.org/doc/html/latest/arm64/booting.html`_, Linux kernel
.. [PSCI] `Power State Coordination Interface Issue C (PSCI v1.0) @@ -20,6 +20,6 @@ https://static.docs.arm.com/den0044/b/DEN0044B_Server_Base_Boot_Requirements.pdf`_ 8 March 2016, `Arm Limited http://arm.com`_
-.. [UEFI] `Unified Extensable Firmware Interface Specification v2.7A - http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_7_A%20Sept%206.pdf`_, - August 2017, `UEFI Forum http://www.uefi.org`_ +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf`_, + February 2020, `UEFI Forum http://www.uefi.org`_
On 6/1/20 11:32 AM, Grant Likely wrote:
I'd like to do a point release of EBBR in the near future. There is an important change to how RuntimeServicesSupported is described in the UEFI spec that needs to be adjusted in EBBR, and the DTB UUID was missing. The rest of the changes are minor editorial and typo fixes.
I've tagged v1.0.1-rc1 in github for review. Full diff is below. Please review and comment.
Thanks, g.
.travis.yml | 82 +++++++++++++++++------------------------ CONTRIBUTING.rst | 23 +----------- source/chapter2-uefi.rst | 40 +++++++++++++++++--- source/chapter3-secureworld.rst | 6 +-- source/index.rst | 3 ++ source/references.rst | 10 ++--- 6 files changed, 81 insertions(+), 83 deletions(-)
diff --git a/.travis.yml b/.travis.yml index 3688a67..4a63cb0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,63 +1,49 @@ sudo: false dist: trusty
cache: apt: true
env: global: - - SPHINXBUILD=~/.local/bin/sphinx-build - - DIFF_COMMIT=v0.5
+ - SPHINXBUILD=~/.local/bin/sphinx-build + - secure: Nn985mEk01BbYLY7IQToa51+jpVp8/f72Q+SY6GVe1cf41gRG4CWrrLFLo4Zrdd+e5a9tMKJ2o6WqT4m0i1AziVnoFx62QtC0dmJVsp4eVzQdhWkaRTcLdoKp18om0To6cVmBzYFzsIUROyOwwJfprpzwylQGFqNFoNG20UmnzTy5c/bg36Ohh/vcpt3HXO6emKDTychu1fBC8tuiy7k5BCfPekKAg6sKTqjsgKM+pEZuv9zTzrBY0HVqCoSLhWUraADko51baOtbBOzLtH4L4EO1rmiFs7/HpN/MzF6REurCAbBM5q82aS/z5KUoMGENt+OwWbeT9BcqUty1wYAFwuK7UwkDO2+YauqGhZ75GKOt213Fdn70Wx1xMkOerdEb8oSdH8Av/FWxwbfI6qxsAhjimYTZ5OCCZu06AVMBugxBnZeYxF89+83qVUxCHNGyGnql1PHJnlIiOzmCmcgjFo90u9fv24497m9O9QlEic/PnN0VLogPOftgcRUdoLjsYh9P6+BvXrWQ0omu41UwnzNJERaeUXuXV+iJsj6kBuj1j6EJ7OK4RyS/Td8mC7sGFBdwOX+HLaPqBTD2rm7z0wtST0jyFJjPfmvCU94+ovpCuYeMxgeudnUXT8T26v6v73nk7QLIIYm1Idg2ibSBfQy5IT220sH6291IryoY2c=
git: depth: false
addons: apt: packages: - - python-pip - - latexmk - - libalgorithm-diff-perl - - texlive - - texlive-latex-extra - - texlive-humanities - - texlive-generic-recommended - - graphviz - - texlive-generic-extra
+ - python-pip + - latexmk + - libalgorithm-diff-perl + - texlive + - texlive-latex-extra + - texlive-humanities + - texlive-generic-recommended + - graphviz + - texlive-generic-extra install: - - pip install --user mako - - pip install --user Sphinx
-before_script: - - wget https://github.com/ftilmann/latexdiff/releases/download/1.2.1/latexdiff-1.2....
- - tar xvf latexdiff-1.2.1.tar.gz - - export PATH=$PWD/latexdiff-1.2.1/:$PATH
+- pip install --user mako +- pip install --user Sphinx script: - - make latexpdf - - make html - - make singlehtml
+- make latexpdf +- make html +- make singlehtml before_deploy: - - cp build/latex/ebbr.pdf build/ebbr-$TRAVIS_TAG.pdf
+- cp build/latex/ebbr.pdf build/ebbr-$TRAVIS_TAG.pdf deploy: - - provider: releases - prerelease: true - api_key: - secure: QAzEatdHC5w1uC06y6ceeRwL6dXhTz8DmkvIirXbv9paEKC7OHpsNm2NtCvLQDLnT98CFBj64y13P29DTYV0ExHNExnixP+R0b9G5kvCG/mGf+k6teXJmtsDRezTCmqAWwxLp70rewcHM+gQ1SdRy+HlHuVC5D70p99vv/f5hK/6f/PodxB0ftrvmb2S+B733+O7kiEKvBZUq/gaX5MTe8x+N09W+4SUTC4Xy5e0KlADfMWiLRhlJvU0PgtQ0IhRaeHnD+gmz/HUaUE/bsdXzIwv9Vb3p9eVmXLj1nE+p1toM5MJwmpKClXgph55PsD2X9xBSwxBhHZ3JOCl6QCOYaqkNvcE0U3e3QzC1b92EHoHN5vMrZenkALe0y1z1u1G+cZybjUEQ2lTmNq1HmO/QLdVHBCShR9xkpjm+8m//NXON8TDgP5z+hIU/g2NLfcSLdinogRLz2vnSmR6SjWzhH8q29d+wg3f5//eMgTCQF1dSRvNt8SjYUQDrW9z1k4dV64Jcn5AWjWmcaErG2D8jWJQGzzrts84Hcv3N7fRUwvMxdQOQDvoMaIxNxg35rBsuGa1tJkLyurOW31uwbOzrLlRSEcypPimpFQWysBwnX+aNTudhY0Dv4HKSIO12iZdIz9pbsMrJCBMCQdAydIDj35Fu5tJ5Ns4/JRaw5IoBQU=
- file_glob: true - file: - - "build/ebbr-*.pdf" - skip_cleanup: true - on: - tags: true - branch: master - - provider: pages - github_token: $GITHUB_TOKEN - local_dir: "build/singlehtml" - skip_cleanup: true - on: - branch: master
+- provider: releases + prerelease: true + api_key: + secure: QAzEatdHC5w1uC06y6ceeRwL6dXhTz8DmkvIirXbv9paEKC7OHpsNm2NtCvLQDLnT98CFBj64y13P29DTYV0ExHNExnixP+R0b9G5kvCG/mGf+k6teXJmtsDRezTCmqAWwxLp70rewcHM+gQ1SdRy+HlHuVC5D70p99vv/f5hK/6f/PodxB0ftrvmb2S+B733+O7kiEKvBZUq/gaX5MTe8x+N09W+4SUTC4Xy5e0KlADfMWiLRhlJvU0PgtQ0IhRaeHnD+gmz/HUaUE/bsdXzIwv9Vb3p9eVmXLj1nE+p1toM5MJwmpKClXgph55PsD2X9xBSwxBhHZ3JOCl6QCOYaqkNvcE0U3e3QzC1b92EHoHN5vMrZenkALe0y1z1u1G+cZybjUEQ2lTmNq1HmO/QLdVHBCShR9xkpjm+8m//NXON8TDgP5z+hIU/g2NLfcSLdinogRLz2vnSmR6SjWzhH8q29d+wg3f5//eMgTCQF1dSRvNt8SjYUQDrW9z1k4dV64Jcn5AWjWmcaErG2D8jWJQGzzrts84Hcv3N7fRUwvMxdQOQDvoMaIxNxg35rBsuGa1tJkLyurOW31uwbOzrLlRSEcypPimpFQWysBwnX+aNTudhY0Dv4HKSIO12iZdIz9pbsMrJCBMCQdAydIDj35Fu5tJ5Ns4/JRaw5IoBQU=
+ file_glob: true + file: + - build/ebbr-*.pdf + skip_cleanup: true + on: + tags: true + branch: master +- provider: pages + github_token: "$GITHUB_TOKEN" + local_dir: build/singlehtml + skip_cleanup: true + on: + branch: master diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a5643a3..7021f0f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -8,35 +8,14 @@ Anyone may contribute to the EBBR project. Contributions are licensed under CC-BY-SA-4.0_ and must be made with a Developer Certificate of Origin (DCO_) attestation as described below. -EBBR discussion uses the boot-architecture_ and arm.ebbr-discuss mailing lists. -The 'official' list is arm.ebbr-discuss, but the list archives are not -yet public, so boot-architecture_ is being used to keep everything in -the open. +EBBR discussion uses the boot-architecture_ mailing list. * boot-architecture@lists.linaro.org -* arm.ebbr-discuss@arm.com Past discussions can be found in the boot-architecture-archive_. We use the IRC channel `#ebbr`_ on OFTC_. -There is a bi-weekly conference call to discuss EBBR topics on the 2nd -and 4th Tuesday of the month at 15:00 UTC/BST, 7:00 PST/PDT, 23:00/22:00 CST -(following UTC/BST daylight savings time shifts). -Anyone is welcome to join.
-- Online meeting: https://arm-onsite.webex.com/meet/gralik01 -- Phone
- - 1-408-792-6300 Call-in toll number (US/Canada) - - 1-877-668-4490 Call-in toll-free number (US/Canada) - - 44-203-478-5285 Call-in toll number (UK) - - 08-002061177 Call-in toll-free (UK) - - More access numbers: webex-global-numbers_ -- Access code: 809 053 990
-.. _webex-global-numbers: https://arm-onsite.webex.com/cmp3300/webcomponents/widget/globalcallin/globa...
DCO Attestation --------------- diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index f6a5802..c9c0101 100644 --- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -9,7 +9,7 @@ platforms. UEFI Version ============ -This document uses version 2.7 of the UEFI specification [UEFI]_. +This document uses version 2.8 Errata A of the UEFI specification [UEFI]_. UEFI Compliance. =============== @@ -86,12 +86,41 @@ tables.
%s/tables./tables:/
- An Advanced Configuration and Power Interface [ACPI]_ table, or
%s/An/an/
- a Devicetree [DTSPEC]_ system description -As stated above, EBBR systems must not provide both ACPI and Devicetree +EBBR systems must not provide both ACPI and Devicetree tables at the same time.
This sentence is redundant. Above the spec already says: "Compliant systems are required to provide one, but not both, of the following tables." Please, remove the redundancy.
Systems that support both interfaces must provide a configuration mechanism to select either ACPI or Devicetree, and must ensure only the selected interface is provided to the OS loader. +Devicetree +^^^^^^^^^^
+If firmware provides a Devicetree system description then it must be provided +in Flattened Devicetree (DTB) format version 17 or higher as described in +[DTSPEC]_ § 5.1. +The following GUID must be used in the EFI system table ([UEFI]_ § 4) +to identify the DTB.
The device tree spec has a sentence starting "The Devicetree Blob (DTB) format ...". So maybe:
%s/the DTB./the Devicetree Blob (DTB)./
ACPI and DTB are missing in the glossary.
+The DTB must be contained in memory of type EfiACPIReclaimMemory.
The UEFI spec that says:
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData, EfiACPIReclaimMemory or EfiACPIMemoryNVS.
Our requirement contradicts this recommendation of the UEFI 2.8A spec.
But the spec also says: "ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS."
So I suggest to add a sentence here that explains our choice, e.g.:
"EfiACPIReclaimMemory was chosen to match the recommendation for ACPI tables which fulfill the same task as the DTB."
+.. code-block:: c
+ #define EFI_DTB_GUID \ + EFI_GUID(0xb1b621d5, 0xf19c, 0x41a5, \ + 0x83, 0x0b, 0xd9, 0x15, 0x2c, 0x69, 0xaa, 0xe0)
+Firmware must have the DTB resident in memory and installed in the EFI system table +before executing any UEFI applications or drivers that are not part of the system +firmware image. +Once the DTB is installed as a configuration table, +the system firmware must not make any modification to it or reference any data +contained within the DTB.
This is something I need to fix in U-Boot. Currently we are installing a new instance of the the device tree every time that the 'bootefi' command is executed.
How about the ACPI and SMBIOS tables? Shouldn't we require the same: "Do not change the ACPI and SMBIOS tables once they are passed to outside the system firmware."?
Why are the SMBIOS tables not mentioned at all in the EBBR?
In U-Boot we currently create:
BIOS Information (Type 0) System Information (Type 1) Baseboard(or Module) Information (Type 2) System Enclosure or Chassis (Type 3) Processor Information (Type 4) System Boot Information (Type 32) End-of-Table (Type 127)
Thanks for taking care of the release.
Best regards
Heinrich
+UEFI applications are permitted to modify or replace the loaded DTB. +System firmware must not depend on any data contained within the DTB. +If system firmware makes use of a DTB for its own configuration, +it should use a separate private copy that is not installed in the +EFI System Table or otherwise be exposed to EFI applications.
UEFI Secure Boot (Optional) --------------------------- @@ -111,7 +140,7 @@ during both boot services and runtime services. However, it isn't always practical for all EFI_RUNTIME_SERVICES functions to be callable during runtime services due to hardware limitations. If any EFI_RUNTIME_SERVICES functions are only available during boot services -then firmware shall provide the global `RuntimeServicesSupported` variable to +then firmware shall provide the `EFI_RT_PROPERTIES_TABLE` to indicate which functions are available during runtime services. Functions that are not available during runtime services shall return EFI_UNSUPPORTED. @@ -148,7 +177,7 @@ Firmware shall not create runtime mappings, or perform any runtime IO that will conflict with device access by the OS. Normally this means a device may be controlled by firmware, or controlled by the OS, but not both. -e.g. If firmware attempts to access an eMMC device at runtime then it will +E.g. if firmware attempts to access an eMMC device at runtime then it will conflict with transactions being performed by the OS. Devices that are provided to the OS (i.e., via PCIe discovery or ACPI/DT @@ -202,7 +231,8 @@ If a platform does not implement modifying non-volatile variables with SetVariable() after ExitBootServices(), then firmware shall return EFI_UNSUPPORTED for any call to SetVariable(), and must advertise that SetVariable() isn't available during runtime services -via the `RuntimeServicesSupported` variable as defined in UEFI version 2.8. +via the `RuntimeServicesSupported` value in the `EFI_RT_PROPERTIES_TABLE` +as defined in [UEFI]_ § 4.6. EFI applications can read `RuntimeServicesSupported` to determine if calls to SetVariable() need to be performed before calling ExitBootServices(). diff --git a/source/chapter3-secureworld.rst b/source/chapter3-secureworld.rst index 4e9fa61..9c51bca 100644 --- a/source/chapter3-secureworld.rst +++ b/source/chapter3-secureworld.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -****************************** -Priviledged or Secure Firmware -****************************** +***************************** +Privileged or Secure Firmware +***************************** AArch32 Multiprocessor Startup Protocol ======================================= diff --git a/source/index.rst b/source/index.rst index 9bc4a09..7a5ded9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -45,6 +45,9 @@ Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 31 March 2019 1.0 - Remove unnecessary UEFI requirements appendix - Allow for ACPI vendor id in firmware path + 1 June 2020 1.0.1-rc1 - Update to UEFI 2.8 Errata A + - Specify UUID for passing DTB + - Typo and editorial fixes ================= ========= ============================================= .. toctree:: diff --git a/source/references.rst b/source/references.rst index a12c1a2..1eb0509 100644 --- a/source/references.rst +++ b/source/references.rst @@ -8,8 +8,8 @@ https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.2`_,
`Devicetree.org https://devicetree.org`_ -.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.txt - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/tree/Documentation/arm64/booting.txt`_,
+.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.rst + https://www.kernel.org/doc/html/latest/arm64/booting.html`_, Linux kernel .. [PSCI] `Power State Coordination Interface Issue C (PSCI v1.0) @@ -20,6 +20,6 @@ https://static.docs.arm.com/den0044/b/DEN0044B_Server_Base_Boot_Requirements.pdf`_
8 March 2016, `Arm Limited http://arm.com`_ -.. [UEFI] `Unified Extensable Firmware Interface Specification v2.7A - http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_7_A%20Sept%206.pdf`_,
- August 2017, `UEFI Forum http://www.uefi.org`_ +.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A + https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf`_,
+ February 2020, `UEFI Forum http://www.uefi.org`_ _______________________________________________ boot-architecture mailing list boot-architecture@lists.linaro.org https://lists.linaro.org/mailman/listinfo/boot-architecture
On 01/06/2020 14:23, Heinrich Schuchardt wrote:
On 6/1/20 11:32 AM, Grant Likely wrote:
[...]
diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index f6a5802..c9c0101 100644 --- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -9,7 +9,7 @@ platforms.
UEFI Version
-This document uses version 2.7 of the UEFI specification [UEFI]_. +This document uses version 2.8 Errata A of the UEFI specification [UEFI]_.
UEFI Compliance.
@@ -86,12 +86,41 @@ tables.
%s/tables./tables:/
- An Advanced Configuration and Power Interface [ACPI]_ table, or
%s/An/an/
Done
- a Devicetree [DTSPEC]_ system description
-As stated above, EBBR systems must not provide both ACPI and Devicetree +EBBR systems must not provide both ACPI and Devicetree tables at the same time.
This sentence is redundant. Above the spec already says: "Compliant systems are required to provide one, but not both, of the following tables." Please, remove the redundancy.
The redundancy is intentional! :-) This has been a contentious point, so it is stated in two different ways to make the point that platforms should not try to do both.
Systems that support both interfaces must provide a configuration mechanism to select either ACPI or Devicetree, and must ensure only the selected interface is provided to the OS loader.
+Devicetree +^^^^^^^^^^
+If firmware provides a Devicetree system description then it must be provided +in Flattened Devicetree (DTB) format version 17 or higher as described in +[DTSPEC]_ § 5.1. +The following GUID must be used in the EFI system table ([UEFI]_ § 4) +to identify the DTB.
The device tree spec has a sentence starting "The Devicetree Blob (DTB) format ...". So maybe:
%s/the DTB./the Devicetree Blob (DTB)./
I went with %s/Devicetree (DTB)/Devicetree Blob (DTB)/ a couple of lines above.
ACPI and DTB are missing in the glossary.
+The DTB must be contained in memory of type EfiACPIReclaimMemory.
The UEFI spec that says:
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData, EfiACPIReclaimMemory or EfiACPIMemoryNVS.
Our requirement contradicts this recommendation of the UEFI 2.8A spec.
But the spec also says: "ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS."
So I suggest to add a sentence here that explains our choice, e.g.:
"EfiACPIReclaimMemory was chosen to match the recommendation for ACPI tables which fulfill the same task as the DTB."
Added this line verbatim. Thanks.
+.. code-block:: c
- #define EFI_DTB_GUID \
EFI_GUID(0xb1b621d5, 0xf19c, 0x41a5, \0x83, 0x0b, 0xd9, 0x15, 0x2c, 0x69, 0xaa, 0xe0)+Firmware must have the DTB resident in memory and installed in the EFI system table +before executing any UEFI applications or drivers that are not part of the system +firmware image. +Once the DTB is installed as a configuration table, +the system firmware must not make any modification to it or reference any data +contained within the DTB.
This is something I need to fix in U-Boot. Currently we are installing a new instance of the the device tree every time that the 'bootefi' command is executed.
How about the ACPI and SMBIOS tables? Shouldn't we require the same: "Do not change the ACPI and SMBIOS tables once they are passed to outside the system firmware."?
We've not had a debate about ACPI or SMBIOS. I don't know if there is any expectation of ACPI or SMBIOS tables being modified at ExitBootServices time (I simply don't have enough experience with either to know what is appropriate, so what I've written is focused on the DT use case).
Why are the SMBIOS tables not mentioned at all in the EBBR?
Hasn't come up in any previous discussions. Typically the debate is over ACPI vs. DT, and as I understand it ACPI doesn't require SMBIOS to be present. Nothing in EBBR excludes the creation of SMBIOS tables.
In U-Boot we currently create:
BIOS Information (Type 0) System Information (Type 1) Baseboard(or Module) Information (Type 2) System Enclosure or Chassis (Type 3) Processor Information (Type 4) System Boot Information (Type 32) End-of-Table (Type 127)
Thanks for taking care of the release.
Thanks for the review. g.
Best regards
Heinrich
+UEFI applications are permitted to modify or replace the loaded DTB. +System firmware must not depend on any data contained within the DTB. +If system firmware makes use of a DTB for its own configuration, +it should use a separate private copy that is not installed in the +EFI System Table or otherwise be exposed to EFI applications.
UEFI Secure Boot (Optional)
@@ -111,7 +140,7 @@ during both boot services and runtime services. However, it isn't always practical for all EFI_RUNTIME_SERVICES functions to be callable during runtime services due to hardware limitations. If any EFI_RUNTIME_SERVICES functions are only available during boot services -then firmware shall provide the global `RuntimeServicesSupported` variable to +then firmware shall provide the `EFI_RT_PROPERTIES_TABLE` to indicate which functions are available during runtime services. Functions that are not available during runtime services shall return EFI_UNSUPPORTED. @@ -148,7 +177,7 @@ Firmware shall not create runtime mappings, or perform any runtime IO that will conflict with device access by the OS. Normally this means a device may be controlled by firmware, or controlled by the OS, but not both. -e.g. If firmware attempts to access an eMMC device at runtime then it will +E.g. if firmware attempts to access an eMMC device at runtime then it will conflict with transactions being performed by the OS.
Devices that are provided to the OS (i.e., via PCIe discovery or ACPI/DT @@ -202,7 +231,8 @@ If a platform does not implement modifying non-volatile variables with SetVariable() after ExitBootServices(), then firmware shall return EFI_UNSUPPORTED for any call to SetVariable(), and must advertise that SetVariable() isn't available during runtime services -via the `RuntimeServicesSupported` variable as defined in UEFI version 2.8. +via the `RuntimeServicesSupported` value in the `EFI_RT_PROPERTIES_TABLE` +as defined in [UEFI]_ § 4.6. EFI applications can read `RuntimeServicesSupported` to determine if calls to SetVariable() need to be performed before calling ExitBootServices().
diff --git a/source/chapter3-secureworld.rst b/source/chapter3-secureworld.rst index 4e9fa61..9c51bca 100644 --- a/source/chapter3-secureworld.rst +++ b/source/chapter3-secureworld.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0
-****************************** -Priviledged or Secure Firmware -****************************** +***************************** +Privileged or Secure Firmware +*****************************
AArch32 Multiprocessor Startup Protocol
diff --git a/source/index.rst b/source/index.rst index 9bc4a09..7a5ded9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -45,6 +45,9 @@ Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 31 March 2019 1.0 - Remove unnecessary UEFI requirements appendix - Allow for ACPI vendor id in firmware path
- 1 June 2020 1.0.1-rc1 - Update to UEFI 2.8 Errata A
- Specify UUID for passing DTB- Typo and editorial fixes=============================================
.. toctree:: diff --git a/source/references.rst b/source/references.rst index a12c1a2..1eb0509 100644 --- a/source/references.rst +++ b/source/references.rst @@ -8,8 +8,8 @@
https://github.com/devicetree-org/devicetree-specification/releases/tag/v0.2`_,
`Devicetree.org <https://devicetree.org>`_-.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.txt
+.. [LINUXA64BOOT] `Linux Documentation/arm64/booting.rst
https://www.kernel.org/doc/html/latest/arm64/booting.html`_, Linux kernel
.. [PSCI] `Power State Coordination Interface Issue C (PSCI v1.0)
@@ -20,6 +20,6 @@
https://static.docs.arm.com/den0044/b/DEN0044B_Server_Base_Boot_Requirements.pdf`_
8 March 2016, `Arm Limited <http://arm.com>`_-.. [UEFI] `Unified Extensable Firmware Interface Specification v2.7A
http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_7_A%20Sept%206.pdf`_,
- August 2017, `UEFI Forum http://www.uefi.org`_
+.. [UEFI] `Unified Extensable Firmware Interface Specification v2.8 Errata A
https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf`_,
- February 2020, `UEFI Forum http://www.uefi.org`_
boot-architecture mailing list boot-architecture@lists.linaro.org https://lists.linaro.org/mailman/listinfo/boot-architecture
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.
boot-architecture@lists.linaro.org
-
Grant Likely -
Heinrich Schuchardt