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

23 Apr 2024

hi Heinrich,
On Fri, 19 Apr 2024 at 13:01, Heinrich Schuchardt xypron.glpk@gmx.de wrote:
...
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@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.
Will add a man-page.
...
...
+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.
Will remove the config flags.
...
...



+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.
These are multiple files. But eventually, we will be using this
feature to generate a multi-payload capsule. Again, this is on similar
lines to how this is done with the EDKII script.
...
What are the curly braces good for? Please, use an established file
format like YAML or JSON.
As discussed over IRC, I will check if I can use the YAML format and
keep the format similar to the one used above -- in key:value pairs. I
would prefer keeping the format similar to what is used in the EDKII
capsule generation tool. But if I can use the mapping node type in
YAML for providing this information, I will explore using YAML with
the libcyaml library for parsing the configs.
...
...



+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
I have kept the format similar to what is used in EDKII.
...
...

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

monotonic-count: Monotonic count value

Please, explain what it is used for.
Okay
...
...

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.
Will fix
-sughosh
...
Best regards
Heinrich
...


Capsule with firmware version



    