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

[Stefan Herbrechtsmeier]

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