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]>

source/chapter1-about.rst

@@ -173,6 +173,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

@@ -69,6 +69,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
+
 .. _section-required-plat-specific-elems:
 
 Required Platform Specific Elements
@@ -178,6 +181,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
 -------------------------
 
@@ -205,6 +217,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"
@@ -230,6 +245,9 @@ processing after restart as found in :UEFI:`8.5.6`. [#FWUpNote]_
    * - `CapsuleLast`
      - Variable for platform to publish the last `CapsuleNNNN` created.
 
+.. versionadded:: TBD
+   Required Variables for "on disk"
+
 Block device partitioning
 -------------------------
 
@@ -286,6 +304,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
 ^^^^^^^^^^^^^^^^^^^
 
@@ -358,6 +379,9 @@ specification [#VersionsNote]_.
     { 0x9073eed4, 0xe50d, 0x11ee, \
     { 0xb8, 0xb0, 0x8b, 0x68, 0xda, 0x62, 0xfc, 0x80 }}
 
+.. versionadded:: 2.1.0
+   Conformance Profile Table
+
 Devicetree
 ----------
 
@@ -389,6 +413,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 Protocols
 ==============
 
@@ -432,6 +462,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)
 ---------------------------
 
@@ -510,6 +543,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
 -----------------------
 
@@ -543,6 +582,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
 -----------------------
 
@@ -595,6 +637,9 @@ Even when `SetVariable()` is not supported during runtime services, firmware
 should cache variable names and values in `EfiRuntimeServicesData` memory so
 that `GetVariable()` and `GetNextVariableName()` can behave as specified.
 
+.. versionadded:: 1.0.1
+   `EFI_RT_PROPERTIES_TABLE`
+
 .. _section-fw-update:
 
 Firmware Update
@@ -650,6 +695,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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -666,3 +720,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

@@ -35,9 +35,15 @@ It is recommended that firmware implements PSCI 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
 ===========