From 3ddb7d34af8baca26f63cc47775c74e23400a68a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vincent=20Stehl=C3=A9?= Date: Tue, 13 Jan 2026 17:33:12 +0100 Subject: [PATCH 1/2] Render version annotations in italic in the pdf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit By default version annotations have no special formatting when rendered with Sphinx and LaTeX as pdf, while they are in displayed in italic in the HTML. Customize the LaTeX pdf formatting to render version annotations in italic for consistency. This has no visible impact until we have version annotations. Signed-off-by: Vincent Stehlé --- source/latex/custom.tex.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/latex/custom.tex.txt b/source/latex/custom.tex.txt index 8454beb..c0f8444 100644 --- a/source/latex/custom.tex.txt +++ b/source/latex/custom.tex.txt @@ -2,3 +2,6 @@ % Using the hyphenat package allows to break e.g. UEFI Protocol names. \usepackage{hyphenat} + +% Render version annotations in italic, to align with HTML. +\newcommand{\DUroleversionmodified}[1]{\textit{#1}} From cdd23be1c8cc0b78f1efc5471e219bbc8e8e5476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vincent=20Stehl=C3=A9?= Date: Fri, 9 Jan 2026 09:29:16 +0100 Subject: [PATCH 2/2] Add version annotations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add version annotations for new and updated requirements, starting from the last EBBR major revision (v2.0.0). Add a few words in the README about version annotations. Signed-off-by: Vincent Stehlé --- README.rst | 15 ++++++++++++++ source/chapter1-about.rst | 9 ++++++++ source/chapter2-uefi.rst | 31 ++++++++++++++++++++++++++++ source/chapter3-secureworld.rst | 11 ++++++++++ source/chapter5-variable-storage.rst | 2 ++ 5 files changed, 68 insertions(+) diff --git a/README.rst b/README.rst index dbdb2ad..320e1c1 100644 --- a/README.rst +++ b/README.rst @@ -174,6 +174,21 @@ extension described below instead. Make sure that citations labels (such as "DTSPEC" above) have 8 characters maximum as this is the limit of the Sphinx LaTeX writer. +Version annotations +^^^^^^^^^^^^^^^^^^^ + +For version annotations, use a directive line at the end of the concerned +section, optionally followed on the next line by a quick mention of which +requirement was added or changed:: + + .. versionadded:: 2.3.0 + UEFI Boot Manager requirements. + + .. versionchanged:: 2.4.0 + +Annotate only changes in requirements; there is no need to annotate changes in +recommendations. + Sphinx Extensions ----------------- diff --git a/source/chapter1-about.rst b/source/chapter1-about.rst index 5ffa0fe..b9630e3 100644 --- a/source/chapter1-about.rst +++ b/source/chapter1-about.rst @@ -181,6 +181,15 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in :rfc:`2119`. +The following annotations are used to highlight when requirements were +introduced or significantly changed since the last major version of this +specification: + +.. versionadded:: 2.3.0 + UEFI Boot Manager requirements. + +.. versionchanged:: 2.4.0 + Features, which will not be supported by a future version of this specification are indicated with a warning such as the following one: diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst index c9f899b..e896b38 100644 --- a/source/chapter2-uefi.rst +++ b/source/chapter2-uefi.rst @@ -12,6 +12,8 @@ UEFI Version This document uses version 2.11 of the UEFI specification [UEFI]_. +.. versionchanged:: 2.3.0 + UEFI Compliance =============== @@ -186,6 +188,9 @@ interface specific UEFI protocols, and so they have been made optional. `EFI_EDID_OVERRIDE_PROTOCOL`, and producing `EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL` is not required. +.. versionadded:: 2.1.0 + Require `RISCV_EFI_BOOT_PROTOCOL` on RISC-V platforms. + .. _section-required-global-vars: Required Global Variables @@ -240,6 +245,8 @@ processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_ * - `CapsuleLast` - Variable for platform to publish the last `CapsuleNNNN` created. +.. versionadded:: 2.2.0 + Block device partitioning ------------------------- @@ -296,6 +303,8 @@ Resident UEFI firmware can be executed in M mode or S/HS mode during POST. However, the UEFI images must be loaded in HS or VS mode if virtualization is available at OS load time. +.. versionadded:: 2.0.1 + UEFI Boot at S mode ^^^^^^^^^^^^^^^^^^^ @@ -384,6 +393,8 @@ specification [#VersionsNote]_. { 0xf2bb0422, 0xda8e, 0x11f0, \ { 0xa6, 0x7b, 0x1b, 0xe2, 0x20, 0x85, 0x40, 0x98 }} +.. versionadded:: 2.1.0 + Devicetree ---------- @@ -416,6 +427,9 @@ The DTB must be contained in memory of type `EfiACPIReclaimMemory`. .. [#ACPIMemNote] `EfiACPIReclaimMemory` was chosen to match the recommendation for ACPI tables which fulfill the same task as the DTB. +.. versionadded:: 2.1.0 + DTB Nodes and Properties requirements table. + UEFI Protocols ============== @@ -432,6 +446,8 @@ Trusted Platform Module (TPM) Not all embedded systems include a TPM but if a TPM is present, then firmware shall implement the `EFI_TCG2_PROTOCOL` as defined in [TCG2]_. +.. versionadded:: 2.2.0 + UEFI Boot Services ================== @@ -459,6 +475,8 @@ If the platform does not implement the monotonic counter, the .. [#MonoNote] `EFI_UNSUPPORTED` is not an allowed status code for `GetNextMonotonicCount()`. +.. versionadded:: 2.2.0 + UEFI Secure Boot (Optional) --------------------------- @@ -676,6 +694,15 @@ Firmware must support the delivery of capsules via file on mass storage device implementation of the `UpdateCapsule()` runtime service and of the ESRT, as detailed in :UEFI:`23.3` and :UEFI:`23.4` respectively. +.. versionchanged:: 2.3.0 + Require authenticated firmware updates. + +.. versionadded:: 2.1.0 + Require an ESRT. + +.. versionadded:: 2.2.0 + Require support for delivery of capsules "on disk". + Out-of-band firmware update ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -693,6 +720,8 @@ the `GetNextHighMonotonicCount()` runtime service. [#BootNote]_ .. [#BootNote] The platform's monotonic counter is made optional in section :ref:`section-misc-boot-services`. +.. versionadded:: 2.2.0 + UEFI Boot Manager ================= @@ -772,3 +801,5 @@ been made optional. This is outside the scope of this specification. .. [#LF2Note] https://docs.u-boot.org/en/v2024.10/develop/uefi/uefi.html#load-file-2-protocol + +.. versionadded:: 2.3.0 diff --git a/source/chapter3-secureworld.rst b/source/chapter3-secureworld.rst index e578241..9b86df6 100644 --- a/source/chapter3-secureworld.rst +++ b/source/chapter3-secureworld.rst @@ -47,6 +47,9 @@ It is recommended that firmware implements PSCI version 1.0 or later .. warning:: A future version of this specification will require minimum PSCI and SMCCC versions. +.. versionchanged:: 2.3.0 + Require PSCI and SMCCC for platforms without EL3. + AArch64 SoC Identification ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -71,6 +74,8 @@ version compatible with caller version 1.2. [#FFANote]_ 1.x, with x >= 2, are compatible with caller versions 1.0 to 1.x, which includes caller version 1.2. +.. versionadded:: 2.4.0 + AArch64 Platform Fault Detection -------------------------------- @@ -83,6 +88,8 @@ defined in [PFDI]_ § 5 Compliance Requirements, and it must support a version request fault detection checks from Platform Firmware. At the time of writing, only PFDI version 1.0 is defined. +.. versionadded:: 2.4.0 + AArch64 System Control and Management ------------------------------------- @@ -138,6 +145,8 @@ implementation requirements take precedence. [#SCMINote]_ which eases agents and platforms interoperability, and this is therefore the recommended implementation. +.. versionadded:: 2.4.0 + AArch64 Random Number Generator ------------------------------- @@ -160,3 +169,5 @@ extensions: * HART State Management Extension (HSM) * System Reset Extension (SRST) * Debug Console Extension (DBCN) if a serial console is present + +.. versionchanged:: 2.4.0 diff --git a/source/chapter5-variable-storage.rst b/source/chapter5-variable-storage.rst index 7c76ad6..d22a41e 100644 --- a/source/chapter5-variable-storage.rst +++ b/source/chapter5-variable-storage.rst @@ -13,6 +13,8 @@ and the operating system can rely on. All integer fields are stored in little-endian byte order. +.. versionadded:: 2.2.0 + File header ===========