[PATCH v14 15/15] FWU: doc: Add documentation for the FWU feature

Thu Oct 20 16:04:50 CEST 2022

On Tue, 18 Oct 2022 at 16:26, Ilias Apalodimas
<ilias.apalodimas at linaro.org> wrote:
>
> On Tue, Oct 18, 2022 at 05:13:37PM +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 at linaro.org>
> > ---
> > Changes since V13: None
> >
> >  doc/develop/uefi/fwu_updates.rst | 184 +++++++++++++++++++++++++++++++
> >  doc/develop/uefi/index.rst       |   1 +
> >  doc/develop/uefi/uefi.rst        |  12 ++
> >  3 files changed, 197 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..068616ce83
> > --- /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
> > +updation of the image.

s/updation/update/

For this fixed, Acked-by: Etienne Carriere <etienne.carriere at linaro.org>

br,
etienne

> > +
> > +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 cd84706953..e0835beba4 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.
> >
> > --
> > 2.34.1
> >
>
> Acked-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>