hi Heinrich,
On Fri, 19 Apr 2024 at 13:01, Heinrich Schuchardt <xypron.g...@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.g...@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
> > *****************************
> >
>
