Merge branch '2022-10-31-FWU-add-FWU-multi-bank-update-feature-support'

To quote the author:
The patchset adds support for the FWU Multi Bank Update[1]
feature. Certain aspects of the Dependable Boot[2] specification have
also been implemented.

The FWU multi bank update feature is used for supporting multiple
sets(also called banks) of firmware image(s), allowing the platform to
boot from a different bank, in case it fails to boot from the active
bank. This functionality is supported by keeping the relevant
information in a structure called metadata, which provides information
on the images. Among other parameters, the metadata structure contains
information on the currect active bank that is being used to boot
image(s).

Functionality is being added to work with the UEFI capsule driver in
u-boot. The metadata is read to gather information on the update bank,
which is the bank to which the firmware images would be flashed to. On
a successful completion of the update of all components, the active
bank field in the metadata is updated, to reflect the bank from which
the platform will boot on the subsequent boots.

Currently, the feature is being enabled on the STM32MP157C-DK2 and
Synquacer boards. The DK2 board boots a FIP image from a uSD card
partitioned with the GPT partioning scheme, while the Synquacer board
boots a FIP image from a MTD partitioned SPI NOR flash device.

This feature also requires changes in a previous stage of
bootloader, which parses the metadata and selects the bank to boot the
image(s) from. Support has being added in tf-a(BL2 stage) for the
STM32MP157C-DK2 board to boot the active bank images. These changes
have been merged to the upstream tf-a repository.

The patch for adding a python test for the feature has been developed,
and was sent in the version 5 of the patches[3]. However, the test
script depends on adding support for the feature on MTD SPI NOR
devices, and that is being done as part of the Synquacer
patches. Hence these set of patches do not have the test script for
the feature. That will be added through the patches for adding support
for the feauture on Synquacer platform.

[1] - https://developer.arm.com/documentation/den0118/a
[2] - https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e18d4319e108a758d02e/mbfw.pdf
[3] - https://lists.denx.de/pipermail/u-boot/2022-June/485992.html

7 files changed, 299 insertions, 7 deletions

diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
new file mode 100644
index 00000000000..72c850a7908
--- /dev/null
+++ b/doc/develop/uefi/fwu_updates.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2022 Linaro Limited
+
+FWU Multi Bank Updates in U-Boot
+================================
+
+The FWU Multi Bank Update feature implements the firmware update
+mechanism described in the PSA Firmware Update for A-profile Arm
+Architecture specification [1]. Certain aspects of the Dependable
+Boot specification [2] are also implemented. The feature provides a
+mechanism to have multiple banks of updatable firmware images and for
+updating the firmware images on the non-booted bank. On a successful
+update, the platform boots from the updated bank on subsequent
+boot. The UEFI capsule-on-disk update feature is used for performing
+the actual updates of the updatable firmware images.
+
+The bookkeeping of the updatable images is done through a structure
+called metadata. Currently, the FWU metadata supports identification
+of images based on image GUIDs stored on a GPT partitioned storage
+media. There are plans to extend the metadata structure for non GPT
+partitioned devices as well.
+
+Accessing the FWU metadata is done through generic API's which are
+defined in a driver which complies with the U-Boot's driver model. A
+new uclass UCLASS_FWU_MDATA has been added for accessing the FWU
+metadata. Individual drivers can be added based on the type of storage
+media, and its partitioning method. Details of the storage device
+containing the FWU metadata partitions are specified through a U-Boot
+specific device tree property `fwu-mdata-store`. Please refer to
+U-Boot `doc <doc/device-tree-bindings/firmware/fwu-mdata-gpt.yaml>`__
+for the device tree bindings.
+
+Enabling the FWU Multi Bank Update feature
+------------------------------------------
+
+The feature can be enabled by specifying the following configs::
+
+    CONFIG_EFI_CAPSULE_ON_DISK=y
+    CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y
+    CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y
+
+    CONFIG_FWU_MULTI_BANK_UPDATE=y
+    CONFIG_FWU_MDATA=y
+    CONFIG_FWU_MDATA_GPT_BLK=y
+    CONFIG_FWU_NUM_BANKS=<val>
+    CONFIG_FWU_NUM_IMAGES_PER_BANK=<val>
+
+in the .config file
+
+By enabling the CONFIG_CMD_FWU_METADATA config option, the
+fwu_mdata_read command can be used to check the current state of the
+FWU metadata structure.
+
+The first group of configuration settings enable the UEFI
+capsule-on-disk update functionality. The second group of configs
+enable the FWU Multi Bank Update functionality. Please refer to the
+section :ref:`uefi_capsule_update_ref` for more details on generation
+of the UEFI capsule.
+
+Setting up the device for GPT partitioned storage
+-------------------------------------------------
+
+Before enabling the functionality in U-Boot, a GPT partitioned storage
+device is required. Assuming a GPT partitioned storage device, the
+storage media needs to be partitioned with the correct number of
+partitions, given the number of banks and number of images per bank
+that the platform is going to support. Each updatable firmware image
+will be stored on a separate partition. In addition, the two copies
+of the FWU metadata will be stored on two separate partitions. These
+partitions need to be created at the time of the platform's
+provisioning.
+
+As an example, a platform supporting two banks with each bank
+containing three images would need to have 2 * 3 = 6 partitions plus
+the two metadata partitions, or 8 partitions. In addition the storage
+media can have additional partitions of non-updatable images, like the
+EFI System Partition(ESP), a partition for the root file system
+etc. An example list of images on the storage medium would be
+
+* FWU metadata 1
+* U-Boot 1
+* OP-TEE 1
+* FWU metadata 2
+* OP-TEE 2
+* U-Boot 2
+* ESP
+* rootfs
+
+When generating the partitions, a few aspects need to be taken care
+of. Each GPT partition entry in the GPT header has two GUIDs::
+
+* PartitionTypeGUID
+* UniquePartitionGUID
+
+The PartitionTypeGUID value should correspond to the
+``image_type_uuid`` field of the FWU metadata. This field is used to
+identify a given type of updatable firmware image, e.g. U-Boot,
+OP-TEE, FIP etc. This GUID should also be used for specifying the
+`--guid` parameter when generating the capsule.
+
+The UniquePartitionGUID value should correspond to the ``image_uuid``
+field in the FWU metadata. This GUID is used to identify images of a
+given image type in different banks.
+
+The FWU specification defines the GUID value to be used for the
+metadata partitions. This would be the PartitionTypeGUID for the
+metadata partitions. Similarly, the UEFI specification defines the ESP
+GUID to be be used.
+
+When generating the metadata, the ``image_type_uuid`` and the
+``image_uuid`` values should match the *PartitionTypeGUID* and the
+*UniquePartitionGUID* values respectively.
+
+Performing the Update
+---------------------
+
+Once the storage media has been partitioned and populated with the
+metadata partitions, the UEFI capsule-on-disk update functionality can
+be used for performing the update. Refer to the section
+:ref:`uefi_capsule_update_ref` for details on how the update can be
+invoked.
+
+On a successful update, the FWU metadata gets updated to reflect the
+bank from which the platform would be booting on subsequent boot.
+
+Based on the value of bit15 of the Flags member of the capsule header,
+the updated images would either be accepted by the U-Boot's UEFI
+implementation, or by the Operating System. If the Operating System is
+accepting the firmware images, it does so by generating an empty
+*accept* capsule. The Operating System can also reject the updated
+firmware by generating a *revert* capsule. The empty capsule can be
+applied by using the exact same procedure used for performing the
+capsule-on-disk update.
+
+The task of accepting the different firmware images, post an update
+may be done by multiple, separate components in the Operating
+System. To help identify the firmware image that is being accepted,
+the accept capsule passes the image GUID of the firmware image being
+accepted. The relevant code in U-Boot then sets the Accept bit of the
+corresponding firmware image for which the accept capsule was
+found. Only when all the firmware components in a bank have been
+accepted does the platform transition from trial state to regular
+state.
+
+The revert capsule on the other hand does not pass any image GUID,
+since reverting any image of the bank has the same result of the
+platform booting from the other bank on subsequent boot.
+
+In the scenario that bit15 of the Flags member of the capsule header
+has not been set, the images being updated are accepted by the
+U-Boot's UEFI firmware implementation by default, on successful
+update of the image.
+
+Generating an empty capsule
+---------------------------
+
+The empty capsule can be generated using the mkeficapsule utility. To
+build the tool, enable::
+
+    CONFIG_TOOLS_MKEFICAPSULE=y
+
+Run the following commands to generate the accept/revert capsules::
+
+.. code-block:: bash
+
+    $ ./tools/mkeficapsule \
+      [--fw-accept --guid <image guid>] | \
+      [--fw-revert] \
+      <capsule_file_name>
+
+Some examples of using the mkeficapsule tool for generation of the
+empty capsule would be::
+
+.. code-block:: bash
+
+    $ ./tools/mkeficapsule --fw-accept --guid <image guid> \
+    <accept_capsule_name>
+    $ ./tools/mkeficapsule --fw-revert <revert_capsule_name>
+
+Links
+-----
+
+* [1] https://developer.arm.com/documentation/den0118/a/ - FWU Specification
+* [2] https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e18d4319e108a758d02e/mbfw.pdf - Dependable Boot Specification
diff --git a/doc/develop/uefi/index.rst b/doc/develop/uefi/index.rst
index 7e65dbc5d5e..e26b1fbe05c 100644
--- a/doc/develop/uefi/index.rst
+++ b/doc/develop/uefi/index.rst
@@ -13,3 +13,4 @@ can be run an UEFI payload.
    uefi.rst
    u-boot_on_efi.rst
    iscsi.rst
+   fwu_updates.rst
diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index cd847069530..e0835beba41 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -277,6 +277,8 @@ Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE`
 
 [1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html
 
+.. _uefi_capsule_update_ref:
+
 Enabling UEFI Capsule Update feature
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -377,6 +379,16 @@ following command::
 
     dfu list
 
+When the FWU Multi Bank Update feature is enabled on the platform, the
+image index is used only to identify the image index with the image
+GUID. The image index would not correspond to the dfu alt number. This
+is because the FWU feature supports multiple partitions(banks) of
+updatable images, and the actual dfu alt number to which the image is
+to be written to is determined at runtime, based on the value of the
+update bank to which the image is to be written. For more information
+on the FWU Multi Bank Update feature, please refer `doc
+<doc/develop/uefi/fwu_updates.rst>`__.
+
 When using the FMP for FIT images, the image index value needs to be
 set to 1.
 
diff --git a/doc/device-tree-bindings/firmware/fwu-mdata-gpt.yaml b/doc/device-tree-bindings/firmware/fwu-mdata-gpt.yaml
new file mode 100644
index 00000000000..0735191ff15
--- /dev/null
+++ b/doc/device-tree-bindings/firmware/fwu-mdata-gpt.yaml
@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/fwu-mdata-gpt.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: FWU metadata on device with GPT partitioned layout
+
+maintainers:
+ - Sughosh Ganu <[email protected]>
+
+properties:
+  compatible:
+    items:
+      - const: u-boot,fwu-mdata-gpt
+
+  fwu-mdata-store:
+    maxItems: 1
+    description: Phandle of the device which contains the FWU medatata partition.
+
+required:
+  - compatible
+  - fwu-mdata-store
+
+additionalProperties: false
+
+examples:
+  - |
+    fwu-mdata {
+        compatible = "u-boot,fwu-mdata-gpt";
+        fwu-mdata-store = <&sdmmc1>;
+    };
diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1
index 09bdc242957..6fb2dd0810d 100644
--- a/doc/mkeficapsule.1
+++ b/doc/mkeficapsule.1
@@ -8,7 +8,7 @@ mkeficapsule \- Generate EFI capsule file for U-Boot
 
 .SH SYNOPSIS
 .B mkeficapsule
-.RI [ options "] " image-blob " " capsule-file
+.RI [ options ] " " [ image-blob ] " " capsule-file
 
 .SH "DESCRIPTION"
 .B mkeficapsule
@@ -23,8 +23,13 @@ Optionally, a capsule file can be signed with a given private key.
 In this case, the update will be authenticated by verifying the signature
 before applying.
 
+Additionally, an empty capsule file can be generated for acceptance or
+rejection of firmware images by a governing component like an Operating
+System. The empty capsules do not require an image-blob input file.
+
+
 .B mkeficapsule
-takes any type of image files, including:
+takes any type of image files when generating non empty capsules, including:
 .TP
 .I raw image
 format is a single binary blob of any type of firmware.
@@ -36,18 +41,16 @@ multiple binary blobs in a single capsule file.
 This type of image file can be generated by
 .BR mkimage .
 
-.PP
-If you want to use other types than above two, you should explicitly
-specify a guid for the FMP driver.
-
 .SH "OPTIONS"
+
 .TP
 .BI "-g\fR,\fB --guid " guid-string
 Specify guid for image blob type. The format is:
     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 The first three elements are in little endian, while the rest
-is in big endian.
+is in big endian. The option must be specified for all non empty and
+image acceptance capsules
 
 .TP
 .BI "-i\fR,\fB --index " index
@@ -57,6 +60,22 @@ Specify an image index
 .BI "-I\fR,\fB --instance " instance
 Specify a hardware instance
 
+.PP
+For generation of firmware accept empty capsule
+.BR --guid
+is mandatory
+.TP
+.BI "-A\fR,\fB --fw-accept "
+Generate a firmware acceptance empty capsule
+
+.TP
+.BI "-R\fR,\fB --fw-revert "
+Generate a firmware revert empty capsule
+
+.TP
+.BI "-o\fR,\fB --capoemflag "
+Capsule OEM flag, value between 0x0000 to 0xffff
+
 .TP
 .BR -h ", " --help
 Print a help message
diff --git a/doc/usage/cmd/fwu_mdata.rst b/doc/usage/cmd/fwu_mdata.rst
new file mode 100644
index 00000000000..ea3c22724a3
--- /dev/null
+++ b/doc/usage/cmd/fwu_mdata.rst
@@ -0,0 +1,43 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+fwu_mdata_read command
+======================
+
+Synopsis
+--------
+
+::
+
+    fwu_mdata_read
+
+Description
+-----------
+
+The fwu_mdata_read command is used to read the FWU metadata
+structure. The command prints out information about the current active
+bank, the previous active bank, image GUIDs, image acceptance etc.
+
+The output may look like:
+
+::
+
+    => fwu_mdata_read
+            FWU Metadata
+    crc32: 0xec4fb997
+    version: 0x1
+    active_index: 0x0
+    previous_active_index: 0x1
+            Image Info
+
+    Image Type Guid: 19D5DF83-11B0-457B-BE2C-7559C13142A5
+    Location Guid: 49272BEB-8DD8-46DF-8D75-356C65EFF417
+    Image Guid:  D57428CC-BB9A-42E0-AA36-3F5A132059C7
+    Image Acceptance: yes
+    Image Guid:  2BE37D6D-8281-4938-BD7B-9A5BBF80869F
+    Image Acceptance: yes
+
+Configuration
+-------------
+
+To use the fwu_mdata_read command, CONFIG_CMD_FWU_METADATA needs to be
+enabled.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index c601d3576d5..df50746c349 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -50,6 +50,7 @@ Shell commands
    cmd/fdt
    cmd/font
    cmd/for
+   cmd/fwu_mdata
    cmd/gpio
    cmd/load
    cmd/loadm