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

Ilias Apalodimas ilias.apalodimas at linaro.org
Tue Oct 4 09:46:38 CEST 2022 

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

More information about the U-Boot mailing list