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 =========== 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}}