diff mbox series

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

Message ID 20240719-b4-dynamic-uuid-v5-4-8a83de3fe3dc@linaro.org
State Superseded
Headers show
Series efi: CapsuleUpdate: support for dynamic UUIDs | expand

Commit Message

Caleb Connolly July 19, 2024, 12:43 p.m. UTC 
Document how platforms can generate GUIDs at runtime rather than
maintaining a list of UUIDs per-board.

Reviewed-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
Signed-off-by: Caleb Connolly <caleb.connolly@linaro.org>
---
 doc/develop/uefi/uefi.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

Comments

Sughosh Ganu July 22, 2024, 5:33 p.m. UTC | #1 
hi Caleb,

On Fri, 19 Jul 2024 at 18:14, Caleb Connolly <caleb.connolly@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@linaro.org>
> Signed-off-by: Caleb Connolly <caleb.connolly@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
>
diff mbox series

Patch

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
+*****************
+
+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