[PATCH v14 15/15] FWU: doc: Add documentation for the FWU feature
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 --- 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 00..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 `__ +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= +CONFIG_FWU_NUM_IMAGES_PER_BANK= + +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
Re: [PATCH v14 15/15] FWU: doc: Add documentation for the FWU feature
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 > --- > 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 00..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 `__ > +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= > +CONFIG_FWU_NUM_IMAGES_PER_BANK= > + > +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 t
Re: [PATCH v14 15/15] FWU: doc: Add documentation for the FWU feature
On Tue, 18 Oct 2022 at 16:26, Ilias Apalodimas 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 > > --- > > 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 00..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 `__ > > +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= > > +CONFIG_FWU_NUM_IMAGES_PER_BANK= > > + > > +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
Re: [PATCH v14 15/15] FWU: doc: Add documentation for the FWU feature
Hi Sughosh, For info I successfully tested your v14 series on my boards. (note i did not test case with a power failure in between mdata partition updates, discussed in patch v14 02/15). I'll run another tests round on next v15 to post my Tested-by tag. Br, Etienne On Tue, 18 Oct 2022 at 13:45, 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 > --- > 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 00..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 `__ > +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= > +CONFIG_FWU_NUM_IMAGES_PER_BANK= > + > +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 GP
