[PATCH v5 04/11] doc: uefi: document dynamic UUID generation

[Sughosh Ganu]

hi Caleb,

On Fri, 19 Jul 2024 at 18:14, Caleb Connolly <caleb.connolly at linaro.org> wrote:
>
> Document how platforms can generate GUIDs at runtime rather than
> maintaining a list of UUIDs per-board.
>
> Reviewed-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>
> Signed-off-by: Caleb Connolly <caleb.connolly at linaro.org>
> ---
>  doc/develop/uefi/uefi.rst | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index d450b12bf801..b284736cf6c2 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -448,8 +448,35 @@ 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.
>
> +Dynamic FWU GUIDs
> +*****************

I believe you are using FWU as an acronym for firmware update ? If so,
can you mention it that way ? We use FWU in the A/B update context, so
it would be better not to use the term.

-sughosh

> +
> +The image_type_id contains a GUID value which is specific to the image
> +and board being updated, that is to say it should uniquely identify the
> +board model (and revision if relevant) and image pair. Traditionally,
> +these GUIDs are generated manually and hardcoded on a per-board basis,
> +however this scheme makes it difficult to scale up to support many
> +boards.
> +
> +To address this, v5 GUIDs can be used to generate board-specific GUIDs
> +at runtime, based on the board's devicetree root compatible
> +(e.g. "qcom,qrb5165-rb5").
> +
> +These strings are combined with the fw_image name to generate GUIDs for
> +each image. Support for dynamic UUIDs can be enabled by generating a new
> +namespace UUID and setting EFI_CAPSULE_NAMESPACE_GUID to it. Dynamic GUID
> +generation is only enabled if the image_type_id property is unset for your
> +firmware images, this is to avoid breaking existing boards with hardcoded
> +GUIDs.
> +
> +The mkeficapsule tool can be used to determine the GUIDs for a particular
> +board and image. It can be found in the tools directory.
> +
> +Firmware update images
> +**********************
> +
>  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
>
> --
> 2.45.2
>