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`_