Hello Sughosh,
Thanks for the documentation. See comments on few typos found (with help of my editor) and suggestions.
Best regards, Etienne
On Thu, 15 Sept 2022 at 10:16, Sughosh Ganu sughosh.ganu@linaro.org wrote:
Add documentattion for the FWU Multi Bank Update feature. The document
s/documentattion/documentation/
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 V9: None
doc/develop/uefi/fwu_updates.rst | 165 +++++++++++++++++++++++++++++++ doc/develop/uefi/index.rst | 1 + doc/develop/uefi/uefi.rst | 2 + 3 files changed, 168 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..fad3fbb3a8 --- /dev/null +++ b/doc/develop/uefi/fwu_updates.rst @@ -0,0 +1,165 @@ +.. 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 it's partitioning method. Details of the storage device
s/it's/its/
+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=y
CONFIG_EFI_CAPSULE_FIRMWARE is not needed. Selected by the above.
- CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y
- CONFIG_FWU_MULTI_BANK_UPDATE=y
- CONFIG_CMD_FWU_METADATA=y
- CONFIG_DM_FWU_MDATA=y
Note also in efi_setup.c, CONFIG_FWU_MULTI_BANK_UPDATE enforces capsules are not checked at 1st EFI command. This means we need CONFIG_EFI_CAPSULE_ON_DISK_EARLY=y, if I'm right.
- 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 an separate partition. In addition, the two copies
s/an/a/
+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.
+Similarly, the FWU specifications defines the GUID value to be used
'FWU specifications define' or 'FWU specifications define'.
+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 to the regular state from trial +state.
nit: for clarity, I found you should rephrase as "from ... to ...":
'... 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>
Maybe examples as: + $ ./tools/mkeficapsule --guid <image guid> <image> <capsule_file_name> + $ ./tools/mkeficapsule --fw-accept --guid <image guid> + $ ./tools/mkeficapsule --fw-revert
+Links +-----
+* [1] https://developer.arm.com/documentation/den0118/a/ - FWU Specification +* [2] https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e... - 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..536b278dd9 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
-- 2.34.1