RFC: version annotations

Add version annotations for new and updated requirements, starting from
EBBR v1.0.

This is a request-for-comments, to fuel discussions, and is not to be
merged.

Signed-off-by: Vincent Stehlé <[email protected]>

Author: vstehle

source/chapter1-about.rst

@@ -172,6 +172,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 a requirement was
+introduced or significantly changed after v1.0:
+
+.. versionadded:: 2.1.0
+   Example new requirement
+
+.. versionchanged:: 2.1.0
+   Example changed requirement
+
 Features, which will not be supported by a future version of this specification
 are indicated with a warning such as the following one:
 

source/chapter2-uefi.rst

@@ -67,6 +67,9 @@ All of the following UEFI elements are required for EBBR compliance.
    * - `EFI_DECOMPRESS_PROTOCOL`
      - Native EFI decompression is rarely used and therefore not required.
 
+.. versionchanged:: 2.0.0
+   Required Elements
+
 Required Platform Specific Elements
 -----------------------------------
 
@@ -170,6 +173,15 @@ interface specific UEFI protocols, and so they have been made optional.
        For this reason EBBR implementations are not required to support option
        ROM loading.
 
+.. versionchanged:: 2.0.0
+   Required Platform Specific Elements
+
+.. versionadded:: 2.1.0
+   `RISCV_EFI_BOOT_PROTOCOL`
+
+.. versionchanged:: TBD
+   Clarify `ConnectController`
+
 Required Global Variables
 -------------------------
 
@@ -197,6 +209,9 @@ Variables as found in :UEFI:`3.3`.
    * - `OsIndicationsSupported`
      - Variable for firmware to indicate which features can be enabled.
 
+.. versionchanged:: 2.0.0
+   Required Global Variables
+
 .. _section-required-vars-for-on-disk:
 
 Required Variables for capsule update "on disk"
@@ -222,6 +237,9 @@ processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_
 
 .. [#FWUpNote] See section :ref:`section-fw-update`.
 
+.. versionadded:: TBD
+   Required Variables for "on disk"
+
 Block device partitioning
 -------------------------
 
@@ -278,6 +296,9 @@ 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
+   RISC-V
+
 UEFI Boot at S mode
 ^^^^^^^^^^^^^^^^^^^
 
@@ -340,6 +361,9 @@ specification [#VersionsNote]_.
    versions of this specification differing only by their last digit (or "patch
    number") are expected to be compatible.
 
+.. versionadded:: 2.1.0
+   Conformance Profile Table
+
 Devicetree
 ----------
 
@@ -371,6 +395,12 @@ 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:: 1.0.1
+   Devicetree
+
+.. versionadded:: 2.1.0
+   ```/chosen``, ``/chosen/stdout-path``
+
 UEFI Boot Services
 ==================
 
@@ -398,6 +428,9 @@ If the platform does not implement the monotonic counter, the
 .. [#MonoNote] `EFI_UNSUPPORTED` is not an allowed status code for
    `GetNextMonotonicCount()`.
 
+.. versionadded:: TBD
+   `EFI_DEVICE_ERROR`
+
 UEFI Secure Boot (Optional)
 ---------------------------
 
@@ -476,6 +509,12 @@ are required to be implemented during boot services and runtime services.
      - Optional
      - Optional
 
+.. versionadded:: 1.0.1
+   `EFI_RT_PROPERTIES_TABLE`
+
+.. versionchanged:: 2.0.0
+   RTC present, wakeup supported, `UpdateCapsule`
+
 Runtime Device Mappings
 -----------------------
 
@@ -509,6 +548,9 @@ However, if firmware does not support access to the RTC after
 `ExitBootServices()`, then `GetTime()` and `SetTime()` shall return
 `EFI_UNSUPPORTED` and the OS must use a device driver to control the RTC.
 
+.. versionchanged:: 2.0.0
+   RTC present
+
 UEFI Reset and Shutdown
 -----------------------
 
@@ -561,6 +603,9 @@ that `GetVariable()` and `GetNextVariableName()` can behave as specified.
 
    https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
 
+.. versionadded:: 1.0.1
+   `EFI_RT_PROPERTIES_TABLE`
+
 .. _section-fw-update:
 
 Firmware Update
@@ -608,6 +653,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.
 
+.. versionadded:: 2.0.0
+   `UpdateCapsule()`
+
+.. versionadded:: 2.1.0
+   ESRT
+
+.. versionadded:: TBD
+   "On disk"
+
 Out-of-band firmware update
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -624,3 +678,6 @@ the `GetNextHighMonotonicCount()` runtime service. [#BootNote]_
 
 .. [#BootNote] The platform's monotonic counter is made optional in section
    :ref:`section-misc-boot-services`.
+
+.. versionadded:: TBD
+   Monotonic

source/chapter3-secureworld.rst

@@ -40,8 +40,14 @@ It is recommended that firmware implementing PSCI supports version 1.0 or later
 .. [#SMCCCNote] Starting with SMCCC version 1.1, support for the `SMCCC_VERSION`
    function is required, for standardized discovery.
 
+.. versionadded:: TBD
+   SMCCC
+
 RISC-V Multiprocessor Startup Protocol
 ======================================
 The resident firmware in M mode or hypervisor running in HS mode must implement
 and conform to at least SBI [RVSBISPEC]_ v0.2 with HART State Management(HSM)
 extension for both RV32 and RV64.
+
+.. versionadded:: 2.0.1
+   RISC-V

source/chapter4-firmware-media.rst

@@ -127,6 +127,9 @@ Given the choice, platforms should use protective partitions over
 adjusting the placement of GPT data structures because protective partitions
 provide explicit information about the protected region.
 
+.. versionchanged:: 2.0.0
+   GPT partitioning
+
 .. _section-mbr-parts:
 
 MBR partitioning
@@ -142,6 +145,9 @@ immutable feature of the platform makes this impossible.
 OS partitioning tools must not create partitions in the first 1MiB
 of the storage device, and must not remove protective partitions.
 
+.. versionchanged:: 2.0.0
+   MBR partitioning
+
 .. _section-fw-partition-fs:
 
 Firmware Partition Filesystem

source/chapter5-variable-storage.rst

@@ -15,6 +15,9 @@ and the operating system can rely on.
 
 All integer fields are stored in little-endian byte order.
 
+.. versionadded:: TBD
+   File format
+
 File header
 -----------