[PATCH 4/5] doc: uefi: update mkeficapsule documentation

[Heinrich Schuchardt]

On 6/16/23 13:34, Stefan Herbrechtsmeier wrote:
> From: Malte Schmidt <malte.schmidt at weidmueller.com>
>
> mkeficapsule now supports multiple blobs. Update the documentation
> accordingly. Although the image blob can still be specified as
> positional parameter for backwards compatibility, remove it from
> the documentation to discourage its usage.
>
> Signed-off-by: Malte Schmidt <malte.schmidt at weidmueller.com>
> Signed-off-by: Stefan Herbrechtsmeier <stefan.herbrechtsmeier at weidmueller.com>
> ---
>
>   doc/develop/uefi/uefi.rst | 31 +++++++++++++++++++++----------
>   1 file changed, 21 insertions(+), 10 deletions(-)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index 6626ceec52..b513934d31 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -304,6 +304,7 @@ Creating a capsule file
>   ***********************
>
>   A capsule file can be created by using tools/mkeficapsule.
> +A capsule file can contain multiple images to update.
>   To build this tool, enable::
>
>       CONFIG_TOOLS_MKEFICAPSULE=y
> @@ -314,10 +315,14 @@ Run the following command
>   .. code-block:: console
>
>       $ mkeficapsule \
> -      --index <index> --instance 0 \
> -      --guid <image GUID> \
> +      --index <index list> \
> +      --instance <instance list> \
> +      --guid <image GUID list> \
> +      --image_blob <image_blob list> \
>         <capsule_file_name>
>
> +The list entries must be comma-separated.
> +
>   The UEFI specification does not define the firmware versioning mechanism.
>   EDK II reference implementation inserts the FMP Payload Header right before

%s/EDK/The EDK/

>   the payload. It coutains the fw_version and lowest supported version,

%s/coutains/contains/
%s/fw_version/new firmware version/

Do I understand it correctly?

"... the lowest supported version which can be upgraded by the capsule."

> @@ -337,14 +342,16 @@ add --fw-version option in mkeficapsule tool.
>   .. code-block:: console
>
>       $ mkeficapsule \
> -      --index <index> --instance 0 \
> -      --guid <image GUID> \
> -      --fw-version 5 \
> +      --index <index list> \
> +      --instance <instance list> \
> +      --guid <image GUID list> \
> +      --fw-version <version list> \
>         <capsule_file_name>
>
>   If the --fw-version option is not set, FMP Payload Header is not inserted
>   and fw_version is set as 0.

%s/FMP/the FMP/

How do you set the lowest supported version which you mention above?

It remains unmentioned how the comma separated lists are related. Should
they all have the same number of entries? Are they matched by index? Can
an entry be left out to use the default, e.g.:

-fw-version 22,,33,44

Wouldn't it be preferable to provide a full command example?

Best regards

Heinrich

>
> +
>   Performing the update
>   *********************
>
> @@ -465,9 +472,11 @@ following command can be issued
>   .. code-block:: bash
>
>       $ ./tools/mkeficapsule \
> -      --index 0x3 --instance 0 \
> +      --index 0x3 \
> +      --instance 0 \
>         --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \
> -      optee.bin optee.capsule
> +      --image_blob optee.bin \
> +      optee.capsule
>
>
>   Enabling Capsule Authentication
> @@ -509,9 +518,11 @@ and used by the steps highlighted below.
>       $ mkeficapsule --monotonic-count 1 \
>         --private-key CRT.key \
>         --certificate CRT.crt \
> -      --index 1 --instance 0 \
> -      [--fit | --raw | --guid <guid-string] \
> -      <image_blob> <capsule_file_name>
> +      --index 1 \
> +      --instance 0 \
> +      [--fit | --raw | --guid <guid-string>] \
> +      --image_blob <image_blob> \
> +      <capsule_file_name>
>
>   4. Insert the signature list into a device tree in the following format::
>