The UEFI capsule can now be generated by specifying the capsule parameters through a config file. Highlight these changes in the documentation.
Also document that payloads sharing the same capsule filename are automatically grouped into a single multi-payload capsule, and that payloads in such a group can be individually signed, with an example config demonstrating both behaviours. Signed-off-by: Sughosh Ganu <[email protected]> Signed-off-by: Balaji Selvanathan <[email protected]> --- doc/develop/uefi/uefi.rst | 112 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 3ca22b572a9..29d3909fea6 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -318,6 +318,118 @@ Run the following command --guid <image GUID> \ <capsule_file_name> +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 +like + +.. code-block:: console + + $ mkeficapsule --cfg-file </path/to/the/config/file> + +Generating multi-payload capsules +********************************** + +Payloads that specify the same ``capsule:`` filename in the config file +are automatically grouped together and bundled into a single multi-payload +capsule, instead of each producing its own separate capsule file. All the +payloads in such a group must use ``capsule-type: normal`` (the default); +if a group mixes normal payloads with accept or revert capsules, the tool +falls back to generating separate capsule files for each payload, named +``<capsule>.0``, ``<capsule>.1`` and so on, and prints a warning. + +Payloads in a group may individually specify ``private-key``, +``pub-key-cert`` and ``monotonic-count`` to be signed. Each payload is +signed independently, so a single multi-payload capsule can contain a mix +of signed and unsigned payloads. + +The following example config groups two payloads into a single +``update.capsule``, with the first payload signed and the second left +unsigned: + +.. code-block:: none + + { + image-guid: 02f4d760-cfd5-43bd-8e2d-a42acb33c660 + hardware-instance: 0 + monotonic-count: 1 + private-key: /path/to/priv/key + pub-key-cert: /path/to/pub/key + payload: u-boot.bin + image-index: 1 + capsule: update.capsule + } + { + image-guid: 4ce292da-1dd8-428d-a1c2-77743ef8b96e + hardware-instance: 0 + payload: u-boot.itb + image-index: 2 + capsule: update.capsule + } + +This generates a single ``update.capsule`` file containing both payloads. + + Capsule with firmware version ***************************** -- 2.34.1
