[PATCH 2/4] doc: Document capsule generation through a config file

[Ilias Apalodimas]

Hi Sughosh,

On Tue, Nov 21, 2023 at 12:30:26PM +0530, Sughosh Ganu wrote:
> 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>
> ---
>  doc/develop/uefi/uefi.rst | 70 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 70 insertions(+)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index fb16ac743a..b9a9ed5491 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -318,6 +318,76 @@ 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.

This sounds a bit weird. The tool is compiled and used by distros. How are
they supposed to use the config file?

Briefly looking at the patches, we use those config options on testing.
Can't we add a flag in the tool itself that can be used for normal use
cases and limit those Kconfig flags in our testing only?  Or alternatively
the paths for the config files can be hardcoded for sandbox and we get rid
of the config options entirely?

Thanks
/Ilias
> +
> +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>
> +
> +
>  Capsule with firmware version
>  *****************************
>
> --
> 2.34.1
>