From: Etienne Carriere <etienne.carriere@linaro.org>
To: Sughosh Ganu <sughosh.ganu@linaro.org>
Cc: u-boot@lists.denx.de, Heinrich Schuchardt <xypron.glpk@gmx.de>,
Ilias Apalodimas <ilias.apalodimas@linaro.org>,
Takahiro Akashi <takahiro.akashi@linaro.org>,
Patrick Delaunay <patrick.delaunay@foss.st.com>,
Patrice Chotard <patrice.chotard@foss.st.com>,
Simon Glass <sjg@chromium.org>, Bin Meng <bmeng.cn@gmail.com>,
Tom Rini <trini@konsulko.com>, Michal Simek <monstr@monstr.eu>,
Jassi Brar <jaswinder.singh@linaro.org>
Subject: Re: [PATCH v11 15/15] FWU: doc: Add documentation for the FWU feature
Date: Fri, 30 Sep 2022 08:27:24 +0200 [thread overview]
Message-ID: <CAN5uoS9PxAe0V6zz++h_Ecy9vphcY9udK2B=F2A7=Gpa_n4gFA@mail.gmail.com> (raw)
In-Reply-To: <20220928092956.2535777-16-sughosh.ganu@linaro.org>
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
>
next prev parent reply other threads:[~2022-09-30 6:27 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-09-28 9:29 [PATCH v11 00/15] FWU: Add FWU Multi Bank Update feature support Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 01/15] dt/bindings: Add bindings for GPT based FWU Metadata storage device Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 02/15] FWU: Add FWU metadata structure and driver for accessing metadata Sughosh Ganu
2022-09-30 5:54 ` Etienne Carriere
2022-10-03 6:27 ` Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 03/15] FWU: Add FWU metadata access driver for GPT partitioned block devices Sughosh Ganu
2022-09-30 6:10 ` Etienne Carriere
2022-09-28 9:29 ` [PATCH v11 04/15] stm32mp1: dk2: Add a node for the FWU metadata device Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 05/15] stm32mp1: dk2: Add image information for capsule updates Sughosh Ganu
2022-09-30 5:51 ` Etienne Carriere
2022-10-03 10:56 ` Takahiro Akashi
2022-10-03 11:10 ` Sughosh Ganu
2022-10-04 3:04 ` Takahiro Akashi
2022-09-28 9:29 ` [PATCH v11 06/15] FWU: Add helper functions for accessing FWU metadata Sughosh Ganu
2022-10-03 9:51 ` Ilias Apalodimas
2022-09-28 9:29 ` [PATCH v11 07/15] FWU: STM32MP1: Add support to read boot index from backup register Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 08/15] event: Add an event for main_loop Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 09/15] FWU: Add boot time checks as highlighted by the FWU specification Sughosh Ganu
2022-10-03 9:56 ` Ilias Apalodimas
2022-10-03 10:31 ` Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 10/15] FWU: Add support for the FWU Multi Bank Update feature Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 11/15] FWU: cmd: Add a command to read FWU metadata Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 12/15] test: dm: Add test cases for FWU Metadata uclass Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 13/15] mkeficapsule: Add support for generating empty capsules Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 14/15] mkeficapsule: Add support for setting OEM flags in capsule header Sughosh Ganu
2022-09-28 9:29 ` [PATCH v11 15/15] FWU: doc: Add documentation for the FWU feature Sughosh Ganu
2022-09-30 6:27 ` Etienne Carriere [this message]
2022-09-30 8:23 ` Sughosh Ganu
2022-10-04 2:54 ` Takahiro Akashi
2022-10-04 6:40 ` Sughosh Ganu
2022-10-04 7:09 ` Takahiro Akashi
2022-10-04 7:46 ` Ilias Apalodimas
2022-10-02 23:50 ` [PATCHv2 0/5] FWU: Add support for mtd backed feature on DeveloperBox jassisinghbrar
2022-10-02 23:51 ` [PATCHv2 1/5] FWU: Add FWU metadata access driver for MTD storage regions jassisinghbrar
2022-10-14 7:07 ` Ilias Apalodimas
2022-10-31 23:37 ` Jassi Brar
2022-10-02 23:51 ` [PATCHv2 2/5] FWU: mtd: Add helper functions for accessing FWU metadata jassisinghbrar
2022-10-14 7:10 ` Ilias Apalodimas
2022-10-02 23:51 ` [PATCHv2 3/5] dt: fwu: developerbox: enable fwu banks and mdata regions jassisinghbrar
2022-10-14 7:33 ` Ilias Apalodimas
2022-10-02 23:52 ` [PATCHv2 4/5] fwu: DeveloperBox: add support for FWU jassisinghbrar
2022-10-03 11:04 ` AKASHI Takahiro
2022-10-03 13:40 ` Jassi Brar
2022-10-03 13:51 ` Ilias Apalodimas
2022-10-04 1:06 ` AKASHI Takahiro
2022-10-04 2:00 ` Jassi Brar
2022-10-04 2:44 ` AKASHI Takahiro
2022-10-04 2:53 ` Jassi Brar
2022-10-02 23:52 ` [PATCHv2 5/5] tools: Add mkfwumdata tool for FWU metadata image jassisinghbrar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAN5uoS9PxAe0V6zz++h_Ecy9vphcY9udK2B=F2A7=Gpa_n4gFA@mail.gmail.com' \
--to=etienne.carriere@linaro.org \
--cc=bmeng.cn@gmail.com \
--cc=ilias.apalodimas@linaro.org \
--cc=jaswinder.singh@linaro.org \
--cc=monstr@monstr.eu \
--cc=patrice.chotard@foss.st.com \
--cc=patrick.delaunay@foss.st.com \
--cc=sjg@chromium.org \
--cc=sughosh.ganu@linaro.org \
--cc=takahiro.akashi@linaro.org \
--cc=trini@konsulko.com \
--cc=u-boot@lists.denx.de \
--cc=xypron.glpk@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).