Merge tag 'efi-next-20230608' of https://source.denx.de/u-boot/custodians/u-boot-efi into next

Pull request efi-next-20230608

UEFI:

* Support for firmware versions in capsule updates

3 files changed, 98 insertions, 0 deletions

diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index ffe25ca2318..ffd13cebe98 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -318,6 +318,33 @@ Run the following command
       --guid <image GUID> \
       <capsule_file_name>
 
+The UEFI specification does not define the firmware versioning mechanism.
+EDK II reference implementation inserts the FMP Payload Header right before
+the payload. It coutains the fw_version and lowest supported version,
+EDK II reference implementation uses these information to implement the
+firmware versioning and anti-rollback protection, the firmware version and
+lowest supported version is stored into EFI non-volatile variable.
+
+In U-Boot, the firmware versioning is implemented utilizing
+the FMP Payload Header same as EDK II reference implementation,
+reads the FMP Payload Header and stores the firmware version into
+"FmpStateXXXX" EFI non-volatile variable. XXXX indicates the image index,
+since FMP protocol handles multiple image indexes.
+
+To add the fw_version into the FMP Payload Header,
+add --fw-version option in mkeficapsule tool.
+
+.. code-block:: console
+
+    $ mkeficapsule \
+      --index <index> --instance 0 \
+      --guid <image GUID> \
+      --fw-version 5 \
+      <capsule_file_name>
+
+If the --fw-version option is not set, FMP Payload Header is not inserted
+and fw_version is set as 0.
+
 Performing the update
 *********************
 
@@ -510,6 +537,45 @@ where signature.dts looks like::
             };
     };
 
+Anti-rollback Protection
+************************
+
+Anti-rollback prevents unintentional installation of outdated firmware.
+To enable anti-rollback, you must add the lowest-supported-version property
+to dtb and specify --fw-version when creating a capsule file with the
+mkeficapsule tool.
+When executing capsule update, U-Boot checks if fw_version is greater than
+or equal to lowest-supported-version. If fw_version is less than
+lowest-supported-version, the update will fail.
+For example, if lowest-supported-version is set to 7 and you run capsule
+update using a capsule file with --fw-version of 5, the update will fail.
+When the --fw-version in the capsule file is updated, lowest-supported-version
+in the dtb might be updated accordingly.
+
+To insert the lowest supported version into a dtb
+
+.. code-block:: console
+
+    $ dtc -@ -I dts -O dtb -o version.dtbo version.dts
+    $ fdtoverlay -i orig.dtb -o new.dtb -v version.dtbo
+
+where version.dts looks like::
+
+    /dts-v1/;
+    /plugin/;
+    &{/} {
+            firmware-version {
+                    image1 {
+                            image-type-id = "09D7CF52-0720-4710-91D1-08469B7FE9C8";
+                            image-index = <1>;
+                            lowest-supported-version = <3>;
+                    };
+            };
+    };
+
+The properties of image-type-id and image-index must match the value
+defined in the efi_fw_image array as image_type_id and image_index.
+
 Executing the boot manager
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/device-tree-bindings/firmware/firmware-version.txt b/doc/device-tree-bindings/firmware/firmware-version.txt
new file mode 100644
index 00000000000..ee90ce31170
--- /dev/null
+++ b/doc/device-tree-bindings/firmware/firmware-version.txt
@@ -0,0 +1,22 @@
+firmware-version bindings
+-------------------------------
+
+Required properties:
+- image-type-id			: guid for image blob type
+- image-index			: image index
+- lowest-supported-version	: lowest supported version
+
+Example:
+
+	firmware-version {
+		image1 {
+			image-type-id = "09D7CF52-0720-4710-91D1-08469B7FE9C8";
+			image-index = <1>;
+			lowest-supported-version = <3>;
+		};
+		image2 {
+			image-type-id = "5A7021F5-FEF2-48B4-AABA-832E777418C0";
+			image-index = <2>;
+			lowest-supported-version = <7>;
+		};
+	};
diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1
index 1ca245a10f8..c4c2057d5c7 100644
--- a/doc/mkeficapsule.1
+++ b/doc/mkeficapsule.1
@@ -62,6 +62,16 @@ Specify an image index
 Specify a hardware instance
 
 .PP
+FMP Payload Header is inserted right before the payload if
+.BR --fw-version
+is specified
+
+
+.TP
+.BI "-v\fR,\fB --fw-version " firmware-version
+Specify a firmware version, 0 if omitted
+
+.PP
 For generation of firmware accept empty capsule
 .BR --guid
 is mandatory