| Message ID | 20220414105448.559043-9-sughosh.ganu@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | efi: capsule: Capsule Update fixes and enhancements | expand |
Hi Sughosh, 2022年4月14日(木) 19:55 Sughosh Ganu <sughosh.ganu@linaro.org>: > > Update the capsule update functionality related documentation to > refect the additional definitions that need to be made per platform > for supporting the capsule update feature. Thanks for adding the example. This is good to me. Reviewed-by: Masami Hiramatsu <masami.hiramatsu@linaro.org> Thank you, > > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> > --- > > Changes since V6: > * Add example for the struct efi_fw_image array and struct > efi_capsule_update_info as suggested by Takahiro > > doc/develop/uefi/uefi.rst | 98 ++++++++++++++++++++++++++++++++++++++- > 1 file changed, 96 insertions(+), 2 deletions(-) > > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst > index fe337c88bd..1aea04a4e8 100644 > --- a/doc/develop/uefi/uefi.rst > +++ b/doc/develop/uefi/uefi.rst > @@ -312,8 +312,8 @@ Run the following command > .. code-block:: console > > $ mkeficapsule \ > - --index 1 --instance 0 \ > - [--fit <FIT image> | --raw <raw image>] \ > + --index <index> --instance 0 \ > + --guid <image GUID> \ > <capsule_file_name> > > Performing the update > @@ -333,9 +333,102 @@ won't be taken over across the reboot. If this is the case, you can skip > this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS) > set. > > +A few values need to be defined in the board file for performing the > +capsule update. These values are defined in the board file by > +initialisation of a structure which provides information needed for > +capsule updates. The following structures have been defined for > +containing the image related information > + > +.. code-block:: c > + > + struct efi_fw_images { > + efi_guid_t image_type_id; > + u16 *fw_name; > + u8 image_index; > + }; > + > + struct efi_capsule_update_info { > + const char *dfu_string; > + struct efi_fw_image *images; > + }; > + > + > +A string is defined which is to be used for populating the > +dfu_alt_info variable. This string is used by the function > +set_dfu_alt_info. Instead of taking the variable from the environment, > +the capsule update feature requires that the variable be set through > +the function, since that is more robust. Allowing the user to change > +the location of the firmware updates is not a very secure > +practice. Getting this information from the firmware itself is more > +secure, assuming the firmware has been verified by a previous stage > +boot loader. > + > +The firmware images structure defines the GUID values, image index > +values and the name of the images that are to be updated through > +the capsule update feature. These values are to be defined as part of > +an array. These GUID values would be used by the Firmware Management > +Protocol(FMP) to populate the image descriptor array and also > +displayed as part of the ESRT table. The image index values defined in > +the array should be one greater than the dfu alt number that > +corresponds to the firmware image. So, if the dfu alt number for an > +image is 2, the value of image index in the fw_images array for that > +image should be 3. The dfu alt number can be obtained by running the > +following command:: > + > + dfu list > + > +When using the FMP for FIT images, the image index value needs to be > +set to 1. > + > Finally, the capsule update can be initiated by rebooting the board. > > +An example of setting the values in the struct efi_fw_image and > +struct efi_capsule_update_info is shown below > + > +.. code-block:: c > + > + struct efi_fw_image fw_images[] = { > + { > + .image_type_id = DEVELOPERBOX_UBOOT_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-UBOOT", > + .image_index = 1, > + }, > + { > + .image_type_id = DEVELOPERBOX_FIP_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-FIP", > + .image_index = 2, > + }, > + { > + .image_type_id = DEVELOPERBOX_OPTEE_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-OPTEE", > + .image_index = 3, > + }, > + }; > + > + struct efi_capsule_update_info update_info = { > + .dfu_string = "mtd nor1=u-boot.bin raw 200000 100000;" > + "fip.bin raw 180000 78000;" > + "optee.bin raw 500000 100000", > + .images = fw_images, > + }; > + > +The platform will define a fw_images array which contains information > +of all the firmware images that are to be updated through capsule > +update mechanism. The dfu_string is the string that is to be set as > +dfu_alt_info. In the example above, the image index to be set for > +u-boot.bin binary is 0x1, for fip.bin is 0x2 and for optee.bin is 0x3. > + > +As an example, for generating the capsule for the optee.bin image, the > +following command can be issued > + > +.. code-block:: bash > + > + $ ./tools/mkeficapsule \ > + --index 0x3 --instance 0 \ > + --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \ > + optee.bin optee.capsule > + > + > Enabling Capsule Authentication > ******************************* > > -- > 2.25.1 > -- Masami Hiramatsu
On Thu, Apr 14, 2022 at 04:24:48PM +0530, Sughosh Ganu wrote: > Update the capsule update functionality related documentation to > refect the additional definitions that need to be made per platform > for supporting the capsule update feature. Your code seems to expect that a global variable, "update_info", exists for each platform. If so, please describe this requirement explicitly in a document. -Takahiro Akashi > > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> > --- > > Changes since V6: > * Add example for the struct efi_fw_image array and struct > efi_capsule_update_info as suggested by Takahiro > > doc/develop/uefi/uefi.rst | 98 ++++++++++++++++++++++++++++++++++++++- > 1 file changed, 96 insertions(+), 2 deletions(-) > > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst > index fe337c88bd..1aea04a4e8 100644 > --- a/doc/develop/uefi/uefi.rst > +++ b/doc/develop/uefi/uefi.rst > @@ -312,8 +312,8 @@ Run the following command > .. code-block:: console > > $ mkeficapsule \ > - --index 1 --instance 0 \ > - [--fit <FIT image> | --raw <raw image>] \ > + --index <index> --instance 0 \ > + --guid <image GUID> \ > <capsule_file_name> > > Performing the update > @@ -333,9 +333,102 @@ won't be taken over across the reboot. If this is the case, you can skip > this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS) > set. > > +A few values need to be defined in the board file for performing the > +capsule update. These values are defined in the board file by > +initialisation of a structure which provides information needed for > +capsule updates. The following structures have been defined for > +containing the image related information > + > +.. code-block:: c > + > + struct efi_fw_images { > + efi_guid_t image_type_id; > + u16 *fw_name; > + u8 image_index; > + }; > + > + struct efi_capsule_update_info { > + const char *dfu_string; > + struct efi_fw_image *images; > + }; > + > + > +A string is defined which is to be used for populating the > +dfu_alt_info variable. This string is used by the function > +set_dfu_alt_info. Instead of taking the variable from the environment, > +the capsule update feature requires that the variable be set through > +the function, since that is more robust. Allowing the user to change > +the location of the firmware updates is not a very secure > +practice. Getting this information from the firmware itself is more > +secure, assuming the firmware has been verified by a previous stage > +boot loader. > + > +The firmware images structure defines the GUID values, image index > +values and the name of the images that are to be updated through > +the capsule update feature. These values are to be defined as part of > +an array. These GUID values would be used by the Firmware Management > +Protocol(FMP) to populate the image descriptor array and also > +displayed as part of the ESRT table. The image index values defined in > +the array should be one greater than the dfu alt number that > +corresponds to the firmware image. So, if the dfu alt number for an > +image is 2, the value of image index in the fw_images array for that > +image should be 3. The dfu alt number can be obtained by running the > +following command:: > + > + dfu list > + > +When using the FMP for FIT images, the image index value needs to be > +set to 1. > + > Finally, the capsule update can be initiated by rebooting the board. > > +An example of setting the values in the struct efi_fw_image and > +struct efi_capsule_update_info is shown below > + > +.. code-block:: c > + > + struct efi_fw_image fw_images[] = { > + { > + .image_type_id = DEVELOPERBOX_UBOOT_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-UBOOT", > + .image_index = 1, > + }, > + { > + .image_type_id = DEVELOPERBOX_FIP_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-FIP", > + .image_index = 2, > + }, > + { > + .image_type_id = DEVELOPERBOX_OPTEE_IMAGE_GUID, > + .fw_name = u"DEVELOPERBOX-OPTEE", > + .image_index = 3, > + }, > + }; > + > + struct efi_capsule_update_info update_info = { > + .dfu_string = "mtd nor1=u-boot.bin raw 200000 100000;" > + "fip.bin raw 180000 78000;" > + "optee.bin raw 500000 100000", > + .images = fw_images, > + }; > + > +The platform will define a fw_images array which contains information > +of all the firmware images that are to be updated through capsule > +update mechanism. The dfu_string is the string that is to be set as > +dfu_alt_info. In the example above, the image index to be set for > +u-boot.bin binary is 0x1, for fip.bin is 0x2 and for optee.bin is 0x3. > + > +As an example, for generating the capsule for the optee.bin image, the > +following command can be issued > + > +.. code-block:: bash > + > + $ ./tools/mkeficapsule \ > + --index 0x3 --instance 0 \ > + --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \ > + optee.bin optee.capsule > + > + > Enabling Capsule Authentication > ******************************* > > -- > 2.25.1 >
diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index fe337c88bd..1aea04a4e8 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -312,8 +312,8 @@ Run the following command .. code-block:: console $ mkeficapsule \ - --index 1 --instance 0 \ - [--fit <FIT image> | --raw <raw image>] \ + --index <index> --instance 0 \ + --guid <image GUID> \ <capsule_file_name> Performing the update @@ -333,9 +333,102 @@ won't be taken over across the reboot. If this is the case, you can skip this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS) set. +A few values need to be defined in the board file for performing the +capsule update. These values are defined in the board file by +initialisation of a structure which provides information needed for +capsule updates. The following structures have been defined for +containing the image related information + +.. code-block:: c + + struct efi_fw_images { + efi_guid_t image_type_id; + u16 *fw_name; + u8 image_index; + }; + + struct efi_capsule_update_info { + const char *dfu_string; + struct efi_fw_image *images; + }; + + +A string is defined which is to be used for populating the +dfu_alt_info variable. This string is used by the function +set_dfu_alt_info. Instead of taking the variable from the environment, +the capsule update feature requires that the variable be set through +the function, since that is more robust. Allowing the user to change +the location of the firmware updates is not a very secure +practice. Getting this information from the firmware itself is more +secure, assuming the firmware has been verified by a previous stage +boot loader. + +The firmware images structure defines the GUID values, image index +values and the name of the images that are to be updated through +the capsule update feature. These values are to be defined as part of +an array. These GUID values would be used by the Firmware Management +Protocol(FMP) to populate the image descriptor array and also +displayed as part of the ESRT table. The image index values defined in +the array should be one greater than the dfu alt number that +corresponds to the firmware image. So, if the dfu alt number for an +image is 2, the value of image index in the fw_images array for that +image should be 3. The dfu alt number can be obtained by running the +following command:: + + dfu list + +When using the FMP for FIT images, the image index value needs to be +set to 1. + Finally, the capsule update can be initiated by rebooting the board. +An example of setting the values in the struct efi_fw_image and +struct efi_capsule_update_info is shown below + +.. code-block:: c + + struct efi_fw_image fw_images[] = { + { + .image_type_id = DEVELOPERBOX_UBOOT_IMAGE_GUID, + .fw_name = u"DEVELOPERBOX-UBOOT", + .image_index = 1, + }, + { + .image_type_id = DEVELOPERBOX_FIP_IMAGE_GUID, + .fw_name = u"DEVELOPERBOX-FIP", + .image_index = 2, + }, + { + .image_type_id = DEVELOPERBOX_OPTEE_IMAGE_GUID, + .fw_name = u"DEVELOPERBOX-OPTEE", + .image_index = 3, + }, + }; + + struct efi_capsule_update_info update_info = { + .dfu_string = "mtd nor1=u-boot.bin raw 200000 100000;" + "fip.bin raw 180000 78000;" + "optee.bin raw 500000 100000", + .images = fw_images, + }; + +The platform will define a fw_images array which contains information +of all the firmware images that are to be updated through capsule +update mechanism. The dfu_string is the string that is to be set as +dfu_alt_info. In the example above, the image index to be set for +u-boot.bin binary is 0x1, for fip.bin is 0x2 and for optee.bin is 0x3. + +As an example, for generating the capsule for the optee.bin image, the +following command can be issued + +.. code-block:: bash + + $ ./tools/mkeficapsule \ + --index 0x3 --instance 0 \ + --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \ + optee.bin optee.capsule + + Enabling Capsule Authentication ******************************* --
Update the capsule update functionality related documentation to refect the additional definitions that need to be made per platform for supporting the capsule update feature. Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org> --- Changes since V6: * Add example for the struct efi_fw_image array and struct efi_capsule_update_info as suggested by Takahiro doc/develop/uefi/uefi.rst | 98 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 2 deletions(-) 2.25.1