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

[Heinrich Schuchardt]

On 19.04.24 08:55, Sughosh Ganu wrote:
> The UEFI capsule can now be generated by specifying the capsule
> parameters through a config file. 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 0389b269c0..8586127a83 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>

The users deserve a man-page mkeficapsule.1 that can be installed by
distros as /usr/share/doc/man/man1/mkeficapsule.1.

Do not expect the user to look up the information online.

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

Why do we need CONFIG_EFI_CAPSULE_CFG_FILE? You could use a fixed path
or an environment parameter.

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

Is this one file? Are these multiple files? If these are multiple files,
please, put them in different code blocks.

What are the curly braces good for? Please, use an established file
format like YAML or JSON.

> +
> +The following are the keys that specify the capsule parameters
> +
> +..code-block:: none
> +
> +    image-guid: Image GUID

Please use the following formatting:

image-guid
     Image GUID

fw-version
     Image version

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

Please, explain what a hardware instance is.

> +    monotonic-count: Monotonic count value

Please, explain what it is used for.

> +    capsule-type: Specifies capsule type. normal(default), accept or revert

ditto

> +    oemflags: 16bit Oemflags value to be used(populated in capsule header)

ditto

> +
> +When generating capsules through a config file, the command would look
> +like
> +
> +.. code-block:: console
> +
> +    $ mkeficapsule --cfg-file </path/to/the/config/file>

All available command line parameters of mkeficapsule should be
described in one place.

Best regards

Heinrich

> +
> +
>   Capsule with firmware version
>   *****************************
>