[v11,15/15] FWU: doc: Add documentation for the FWU feature

Add documentation for the FWU Multi Bank Update feature. The document
describes the steps needed for setting up the platform for the
feature, as well as steps for enabling the feature on the platform.

Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
---
Changes since V10:
* Fix review comments suggested by Etienne
* Add a paragraph in the capsule update section to highlight the
  difference in ImageIndex correlation with DFU alt num with FWU feature
  enabled

 doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
 doc/develop/uefi/index.rst       |   1 +
 doc/develop/uefi/uefi.rst        |  10 ++
 3 files changed, 184 insertions(+)
 create mode 100644 doc/develop/uefi/fwu_updates.rst

Hello Sughosh,

2 comments on the documentation. Otherwise it looks all good to me.

Best regards,
Etienne

On Wed, 28 Sept 2022 at 11:31, Sughosh Ganu <sughosh.ganu@linaro.org> wrote:
>
> Add documentation for the FWU Multi Bank Update feature. The document
> describes the steps needed for setting up the platform for the
> feature, as well as steps for enabling the feature on the platform.
>
> Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> ---
> Changes since V10:
> * Fix review comments suggested by Etienne
> * Add a paragraph in the capsule update section to highlight the
>   difference in ImageIndex correlation with DFU alt num with FWU feature
>   enabled
>
>  doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
>  doc/develop/uefi/index.rst       |   1 +
>  doc/develop/uefi/uefi.rst        |  10 ++
>  3 files changed, 184 insertions(+)
>  create mode 100644 doc/develop/uefi/fwu_updates.rst
>
> diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
> new file mode 100644
> index 0000000000..292feceb9a
> --- /dev/null
> +++ b/doc/develop/uefi/fwu_updates.rst
> @@ -0,0 +1,173 @@
> +.. 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_CMD_FWU_METADATA=y

Actually the command is optional. Even without cmd support, capsules
can be consumed from CAPSULE_ON_DISK_EARLY.
Is it worth mentioning here?

> +    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
> +
> +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.
> +
> +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

Here or below, maybe mention FWU metadata1/2 and ESP (at least) expect
dedicated partition type guid and reference the 2 U-Boot macros
FWU_MDATA_GUID and PARTITION_SYSTEM_GUID.


> +
> +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.
> +
> +Similarly, the FWU specification defines the GUID value to be used
> +for the metadata partitions. This would be the PartitionTypeGUID for
> +the metadata partitions.
> +
> +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.
> +
> +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> +
>  When using the FMP for FIT images, the image index value needs to be
>  set to 1.
>
> --
> 2.34.1
>

hi Etienne,

On Fri, 30 Sept 2022 at 11:57, Etienne Carriere
<etienne.carriere@linaro.org> wrote:
>
> Hello Sughosh,
>
> 2 comments on the documentation. Otherwise it looks all good to me.
>
> Best regards,
> Etienne
>
> On Wed, 28 Sept 2022 at 11:31, Sughosh Ganu <sughosh.ganu@linaro.org> wrote:
> >
> > Add documentation for the FWU Multi Bank Update feature. The document
> > describes the steps needed for setting up the platform for the
> > feature, as well as steps for enabling the feature on the platform.
> >
> > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> > ---
> > Changes since V10:
> > * Fix review comments suggested by Etienne
> > * Add a paragraph in the capsule update section to highlight the
> >   difference in ImageIndex correlation with DFU alt num with FWU feature
> >   enabled
> >
> >  doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
> >  doc/develop/uefi/index.rst       |   1 +
> >  doc/develop/uefi/uefi.rst        |  10 ++
> >  3 files changed, 184 insertions(+)
> >  create mode 100644 doc/develop/uefi/fwu_updates.rst
> >
> > diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
> > new file mode 100644
> > index 0000000000..292feceb9a
> > --- /dev/null
> > +++ b/doc/develop/uefi/fwu_updates.rst
> > @@ -0,0 +1,173 @@
> > +.. 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_CMD_FWU_METADATA=y
>
> Actually the command is optional. Even without cmd support, capsules
> can be consumed from CAPSULE_ON_DISK_EARLY.
> Is it worth mentioning here?

Yes, the command is more useful from getting the understanding of
which bank is currently active and if the images are accepted or not.
I can put a separate statement saying that the command can be used to
get the metadata information.

>
> > +    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
> > +
> > +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.
> > +
> > +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
>
> Here or below, maybe mention FWU metadata1/2 and ESP (at least) expect
> dedicated partition type guid and reference the 2 U-Boot macros
> FWU_MDATA_GUID and PARTITION_SYSTEM_GUID.

I have mentioned the FWU metadata GUIDs below. Is this not good enough?

"Similarly, the FWU specification defines the GUID value to be used
for the metadata partitions. This would be the PartitionTypeGUID for
the metadata partitions."

Maybe similarly I can mention that the ESP GUID can be obtained from
the UEFI specification.

-sughosh

>
>
> > +
> > +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.
> > +
> > +Similarly, the FWU specification defines the GUID value to be used
> > +for the metadata partitions. This would be the PartitionTypeGUID for
> > +the metadata partitions.
> > +
> > +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.
> > +
> > +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> > +
> >  When using the FMP for FIT images, the image index value needs to be
> >  set to 1.
> >
> > --
> > 2.34.1
> >

Sughosh,

On Wed, Sep 28, 2022 at 02:59:56PM +0530, Sughosh Ganu wrote:
> Add documentation for the FWU Multi Bank Update feature. The document
> describes the steps needed for setting up the platform for the
> feature, as well as steps for enabling the feature on the platform.
> 
> Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> ---
> Changes since V10:
> * Fix review comments suggested by Etienne
> * Add a paragraph in the capsule update section to highlight the
>   difference in ImageIndex correlation with DFU alt num with FWU feature
>   enabled
> 
>  doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
>  doc/develop/uefi/index.rst       |   1 +
>  doc/develop/uefi/uefi.rst        |  10 ++
>  3 files changed, 184 insertions(+)
>  create mode 100644 doc/develop/uefi/fwu_updates.rst
> 
> diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
> new file mode 100644
> index 0000000000..292feceb9a
> --- /dev/null
> +++ b/doc/develop/uefi/fwu_updates.rst
> @@ -0,0 +1,173 @@
> +.. 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_CMD_FWU_METADATA=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
> +
> +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.
> +
> +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.

Well, what is not clear to me here is:
- who is responsible to set up FWU metadata and when
- how FWU metadata is related to fw_images and update_info
  which are used in normal case, which is mentioned in develop/uefi/uefi.rst

I know the whole text here is dedicated to A/B update, but I think
it would also be helpful to have a single document which covers both cases
for developers to understand how differently FWU is configured for those cases.

-Takahiro Akashi

> +
> +Similarly, the FWU specification defines the GUID value to be used
> +for the metadata partitions. This would be the PartitionTypeGUID for
> +the metadata partitions.
> +
> +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.
> +
> +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> +
>  When using the FMP for FIT images, the image index value needs to be
>  set to 1.
>  
> -- 
> 2.34.1
>

hi Takahiro,

On Tue, 4 Oct 2022 at 08:24, Takahiro Akashi <takahiro.akashi@linaro.org> wrote:
>
> Sughosh,
>
> On Wed, Sep 28, 2022 at 02:59:56PM +0530, Sughosh Ganu wrote:
> > Add documentation for the FWU Multi Bank Update feature. The document
> > describes the steps needed for setting up the platform for the
> > feature, as well as steps for enabling the feature on the platform.
> >
> > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> > ---
> > Changes since V10:
> > * Fix review comments suggested by Etienne
> > * Add a paragraph in the capsule update section to highlight the
> >   difference in ImageIndex correlation with DFU alt num with FWU feature
> >   enabled
> >
> >  doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
> >  doc/develop/uefi/index.rst       |   1 +
> >  doc/develop/uefi/uefi.rst        |  10 ++
> >  3 files changed, 184 insertions(+)
> >  create mode 100644 doc/develop/uefi/fwu_updates.rst
> >
> > diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
> > new file mode 100644
> > index 0000000000..292feceb9a
> > --- /dev/null
> > +++ b/doc/develop/uefi/fwu_updates.rst
> > @@ -0,0 +1,173 @@
> > +.. 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_CMD_FWU_METADATA=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
> > +
> > +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.
> > +
> > +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.
>
> Well, what is not clear to me here is:
> - who is responsible to set up FWU metadata and when

Initially, when the board is being provisioned, the metadata is
supposed to be installed on two separate partitions. This is described
under "Setting up the device for GPT partitioned storage".

> - how FWU metadata is related to fw_images and update_info
>   which are used in normal case, which is mentioned in develop/uefi/uefi.rst

The entire update process is the same as the UEFI capsule update. This
is being highlighted in the first paragraph under "Performing the
Update". I have also added a paragraph under "Performing the update"
which specifies how the image index value used with the FWU feature
enabled is different from the normal capsule update.

>
> I know the whole text here is dedicated to A/B update, but I think
> it would also be helpful to have a single document which covers both cases
> for developers to understand how differently FWU is configured for those cases.

I would think that it would be more clear to have a separate document
for the FWU updates. In any case, the fwu_updates.rst is under the
same directory as the uefi.rst which explains the normal capsule
update functionality. There would also be addition of the section for
the FWU updates on platforms using MTD based devices. So I think it
would be better to keep the documents separate. Even if we move the
content in fwu_updates.rst under uefi.rst, the actual update process
would still be explained by the section under
'uefi_capsule_update_ref'. Do you see difficulty in understanding the
FWU update feature being kept in a separate file?

-sughosh

>
> -Takahiro Akashi
>
> > +
> > +Similarly, the FWU specification defines the GUID value to be used
> > +for the metadata partitions. This would be the PartitionTypeGUID for
> > +the metadata partitions.
> > +
> > +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.
> > +
> > +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> > +
> >  When using the FMP for FIT images, the image index value needs to be
> >  set to 1.
> >
> > --
> > 2.34.1
> >

On Tue, Oct 04, 2022 at 12:10:27PM +0530, Sughosh Ganu wrote:
> hi Takahiro,
> 
> On Tue, 4 Oct 2022 at 08:24, Takahiro Akashi <takahiro.akashi@linaro.org> wrote:
> >
> > Sughosh,
> >
> > On Wed, Sep 28, 2022 at 02:59:56PM +0530, Sughosh Ganu wrote:
> > > Add documentation for the FWU Multi Bank Update feature. The document
> > > describes the steps needed for setting up the platform for the
> > > feature, as well as steps for enabling the feature on the platform.
> > >
> > > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> > > ---
> > > Changes since V10:
> > > * Fix review comments suggested by Etienne
> > > * Add a paragraph in the capsule update section to highlight the
> > >   difference in ImageIndex correlation with DFU alt num with FWU feature
> > >   enabled
> > >
> > >  doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++
> > >  doc/develop/uefi/index.rst       |   1 +
> > >  doc/develop/uefi/uefi.rst        |  10 ++
> > >  3 files changed, 184 insertions(+)
> > >  create mode 100644 doc/develop/uefi/fwu_updates.rst
> > >
> > > diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst
> > > new file mode 100644
> > > index 0000000000..292feceb9a
> > > --- /dev/null
> > > +++ b/doc/develop/uefi/fwu_updates.rst
> > > @@ -0,0 +1,173 @@
> > > +.. 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_CMD_FWU_METADATA=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
> > > +
> > > +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.
> > > +
> > > +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.
> >
> > Well, what is not clear to me here is:
> > - who is responsible to set up FWU metadata and when
> 
> Initially, when the board is being provisioned, the metadata is
> supposed to be installed on two separate partitions. This is described
> under "Setting up the device for GPT partitioned storage".
> 
> > - how FWU metadata is related to fw_images and update_info
> >   which are used in normal case, which is mentioned in develop/uefi/uefi.rst
> 
> The entire update process is the same as the UEFI capsule update. This
> is being highlighted in the first paragraph under "Performing the
> Update".

I think of developers.

For instance, as I mentioned above, image_type_uuid/image_index in FWU metadata
must match with the ones in fw_images.
And how about update_info, especially dfu_string? This field won't be used
in A/B update IIUC.
There are a couple of points that developers should be aware.
That is why I suggested the whole explanation is in one place.

> I have also added a paragraph under "Performing the update"
> which specifies how the image index value used with the FWU feature
> enabled is different from the normal capsule update.
> 
> >
> > I know the whole text here is dedicated to A/B update, but I think
> > it would also be helpful to have a single document which covers both cases
> > for developers to understand how differently FWU is configured for those cases.
> 
> I would think that it would be more clear to have a separate document
> for the FWU updates. In any case, the fwu_updates.rst is under the
> same directory as the uefi.rst which explains the normal capsule
> update functionality. There would also be addition of the section for
> the FWU updates on platforms using MTD based devices. So I think it
> would be better to keep the documents separate. Even if we move the
> content in fwu_updates.rst under uefi.rst, the actual update process
> would still be explained by the section under
> 'uefi_capsule_update_ref'. Do you see difficulty in understanding the
> FWU update feature being kept in a separate file?

Yes.

I don't care whether the text is contained in a physically-single document,
but do expect that the normal case and A/B update are described (in different
sections) under the logically-same chapter for better understanding of differences.

-Takahiro Akashi


> -sughosh
> 
> >
> > -Takahiro Akashi
> >
> > > +
> > > +Similarly, the FWU specification defines the GUID value to be used
> > > +for the metadata partitions. This would be the PartitionTypeGUID for
> > > +the metadata partitions.
> > > +
> > > +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.
> > > +
> > > +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> > > +
> > >  When using the FMP for FIT images, the image index value needs to be
> > >  set to 1.
> > >
> > > --
> > > 2.34.1
> > >

Akashi-san


> > > > +
> > > > +* 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.
> > >
> > > Well, what is not clear to me here is:
> > > - who is responsible to set up FWU metadata and when
> >
> > Initially, when the board is being provisioned, the metadata is
> > supposed to be installed on two separate partitions. This is described
> > under "Setting up the device for GPT partitioned storage".
> >
> > > - how FWU metadata is related to fw_images and update_info
> > >   which are used in normal case, which is mentioned in develop/uefi/uefi.rst
> >
> > The entire update process is the same as the UEFI capsule update. This
> > is being highlighted in the first paragraph under "Performing the
> > Update".
>
> I think of developers.
>
> For instance, as I mentioned above, image_type_uuid/image_index in FWU metadata
> must match with the ones in fw_images.
> And how about update_info, especially dfu_string? This field won't be used
> in A/B update IIUC.
> There are a couple of points that developers should be aware.
> That is why I suggested the whole explanation is in one place.
>
> > I have also added a paragraph under "Performing the update"
> > which specifies how the image index value used with the FWU feature
> > enabled is different from the normal capsule update.
> >
> > >
> > > I know the whole text here is dedicated to A/B update, but I think
> > > it would also be helpful to have a single document which covers both cases
> > > for developers to understand how differently FWU is configured for those cases.
> >
> > I would think that it would be more clear to have a separate document
> > for the FWU updates. In any case, the fwu_updates.rst is under the
> > same directory as the uefi.rst which explains the normal capsule
> > update functionality. There would also be addition of the section for
> > the FWU updates on platforms using MTD based devices. So I think it
> > would be better to keep the documents separate. Even if we move the
> > content in fwu_updates.rst under uefi.rst, the actual update process
> > would still be explained by the section under
> > 'uefi_capsule_update_ref'. Do you see difficulty in understanding the
> > FWU update feature being kept in a separate file?
>
> Yes.
>
> I don't care whether the text is contained in a physically-single document,
> but do expect that the normal case and A/B update are described (in different
> sections) under the logically-same chapter for better understanding of differences.

That would make the document quite big though wouldn't it?  Wouldn't
it be a bit more readable to add a link in the capsule update
documentation pointing to the FWU functionality? IOW add a paragraph
in capsule updates describing the basics and then have a link the the
existing FWU documentation.

Regards
/Ilias

> -Takahiro Akashi
>
>
> > -sughosh
> >
> > >
> > > -Takahiro Akashi
> > >
> > > > +
> > > > +Similarly, the FWU specification defines the GUID value to be used
> > > > +for the metadata partitions. This would be the PartitionTypeGUID for
> > > > +the metadata partitions.
> > > > +
> > > > +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.
> > > > +
> > > > +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 7e65dbc5d5..e26b1fbe05 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 941e427093..b5c83db65a 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,14 @@ 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.
> > > > +
> > > >  When using the FMP for FIT images, the image index value needs to be
> > > >  set to 1.
> > > >
> > > > --
> > > > 2.34.1
> > > >