[PATCH 5/5] doc: uefi: clarify capsule concept

[Heinrich Schuchardt]

On 6/16/23 13:34, Stefan Herbrechtsmeier wrote:
> From: Malte Schmidt <malte.schmidt at weidmueller.com>
>
> There seems to be some misused or inaccurate namings regarding the capsule
> concept. Set the naming straight and add a table showing the naming
> conventions. This table is based on the images found in chapter 23 of the
> UEFI 2.10 specifications [1]. The table should help to build a common
> understanding between the authors and readers of the documentation.
>
> [1] https://uefi.org/specs/UEFI/2.10/index.html
>
> 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 | 42 ++++++++++++++++++++++++++++++++++++---
>   1 file changed, 39 insertions(+), 3 deletions(-)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index b513934d31..56188c5b10 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -300,6 +300,42 @@ not present are ignored when determining the active boot option.
>   Please note that capsules will be applied in the alphabetic order of
>   capsule file names.
>
> +Structure of a capsule file
> +***************************
> +
> +The strucutre of a firmware management capsule as defined in [1] is shown

%s/strucutre/structure/

Best regards

Heinrich

> +below. The tools/mkeficapsule program supports creating firmware management
> +capsules with multiple payloads and optionally with firmware image
> +authentication.
> +
> +.. code-block:: text
> +
> +    +-------------------------------------------------------------------------+
> +    | EFI_CAPSULE_HEADER                                                      |
> +    +--------------+----------------------------------------------------------+
> +    | Capsule Body | EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER                   |
> +    |              +----------------------------------------------------------+
> +    |              | Optional Driver 1                                        |
> +    |              +----------------------------------------------------------+
> +    |              | Optional Driver 2                                        |
> +    |              +----------------------------------------------------------+
> +    |              | ...                                                      |
> +    |              +-----------+----------------------------------------------+
> +    |              | Payload 1 | EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER |
> +    |              |           +----------------------------------------------+
> +    |              |           | Firmware Image Authentication (optional)     |
> +    |              |           +----------------------------------------------+
> +    |              |           | Dependency Expression (optional)             |
> +    |              |           +----------------------------------------------+
> +    |              |           | Firmware Image                               |
> +    |              +-----------+----------------------------------------------+
> +    |              | Payload 2                                                |
> +    |              +----------------------------------------------------------+
> +    |              | ...                                                      |
> +    |              +----------------------------------------------------------+
> +    |              | Payload n                                                |
> +    +--------------+----------------------------------------------------------+
> +
>   Creating a capsule file
>   ***********************
>
> @@ -482,9 +518,9 @@ following command can be issued
>   Enabling Capsule Authentication
>   *******************************
>
> -The UEFI specification defines a way of authenticating the capsule to
> -be updated by verifying the capsule signature. The capsule signature
> -is computed and prepended to the capsule payload at the time of
> +The UEFI specification defines a way of authenticating the capsule payload
> +to be updated by verifying the signature of each capsule payload. The payload
> +signature is computed and prepended to the capsule payload at the time of
>   capsule generation. This signature is then verified by using the
>   public key stored as part of the X509 certificate. This certificate is
>   in the form of an efi signature list (esl) file, which is embedded in