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.aka...@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.g...@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 > > >
