[PATCH v4 07/12] doc: Add documentation to highlight capsule generation related updates

Sughosh Ganu sughosh.ganu at linaro.org
Sat Jul 15 15:45:28 CEST 2023

The UEFI capsule can now be generate by specifying the capsule
parameters through a config file. Additionally, the capsules can be
generated as part of u-boot build, through binman. Highlight these
changes in the documentation.

Signed-off-by: Sughosh Ganu <sughosh.ganu at linaro.org>
Changes since V3:
* Move the paragraph on version support under a separate subsection.
* Move the description on generating capsules through config file
  under the section to describe capsule generation.
* Add a subsection highlighting generation of capsules through

 doc/develop/uefi/uefi.rst | 84 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
index 3d07aa33b8..251eaa13fd 100644
--- a/doc/develop/uefi/uefi.rst
+++ b/doc/develop/uefi/uefi.rst
@@ -318,6 +318,79 @@ Run the following command
       --guid <image GUID> \
+Alternatively, the capsules can be generated through a config
+file. When generating the capsules through a config file, the Kconfig
+symbol CONFIG_EFI_CAPSULE_CFG_FILE is to be used for specifying the
+path to the config file.
+The config file describes the parameters that are used for generating
+one or more capsules. The parameters for a given capsule file are
+specified within curly braces, in the form of "key:value" pairs. All
+the parameters that are currently supported by the mkeficapsule tool
+can be specified through the config file.
+The following are some example payload parameters specified through
+the config file.
+.. code-block:: none
+	{
+	    image-guid: 02f4d760-cfd5-43bd-8e2d-a42acb33c660
+	    hardware-instance: 0
+	    monotonic-count: 1
+	    payload: u-boot.bin
+	    image-index: 1
+	    fw-version: 2
+	    private-key: /path/to/priv/key
+	    pub-key-cert: /path/to/pub/key
+	    capsule: u-boot.capsule
+	}
+	{
+	    image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e
+	    hardware-instance: 0
+	    payload: u-boot.itb
+	    image-index: 2
+	    fw-version: 7
+	    oemflags: 0x8000
+	    capsule: fit.capsule
+	}
+	{
+	    capsule-type: accept
+	    image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e
+	    capsule: accept.capsule
+	}
+	{
+	    capsule-type: revert
+	    capsule: revert.capsule
+	}
+The following are the keys that specify the capsule parameters
+..code-block:: none
+    image-guid: Image GUID
+    image-index: Image index value
+    fw-version: Image version
+    private-key: Path to the private key file used for capsule signing
+    pub-key-cert: Path to the public key crt file used for capsule signing
+    payload: Path to the capsule payload file
+    capsule: Path to the output capsule file that is generated
+    hardware-instance: Hardware Instance value
+    monotonic-count: Monotonic count value
+    capsule-type: Specifies capsule type. normal(default), accept or revert
+    oemflags: 16bit Oemflags value to be used(populated in capsule header)
+When generating capsules through a config file, the command would look
+.. code-block:: console
+    $ mkeficapsule --cfg-file </path/to/the/config/file>
+Capsule with firmware version
 The UEFI specification does not define the firmware versioning mechanism.
 EDK II reference implementation inserts the FMP Payload Header right before
 the payload. It coutains the fw_version and lowest supported version,
@@ -345,6 +418,17 @@ add --fw-version option in mkeficapsule tool.
 If the --fw-version option is not set, FMP Payload Header is not inserted
 and fw_version is set as 0.
+Capsule Generation through binman
+Support has also been added to generate capsules during u-boot build
+through binman. This requires the platform's DTB to be populated with
+the capsule entry nodes for binman. The capsules then can be generated
+by specifying the capsule parameters either through a config file, or
+by specifying them as properties in the capsule entry node.
 Performing the update

More information about the U-Boot mailing list