[PATCH v5 08/12] doc: Add documentation to highlight capsule generation related updates

[Sughosh Ganu]

hi Simon,

On Wed, 26 Jul 2023 at 04:24, Simon Glass <sjg at chromium.org> wrote:
>
> Hi,
>
> On Tue, 25 Jul 2023 at 10:18, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
> >
> > On 25.07.23 10:57, 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>
> > > ---
> > > Changes since V4: None
> > >
> > >   doc/develop/uefi/uefi.rst | 84 +++++++++++++++++++++++++++++++++++++++
> > >   1 file changed, 84 insertions(+)
> > >
> > > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> > > index b2854b52a6..29955d943e 100644
> > > --- a/doc/develop/uefi/uefi.rst
> > > +++ b/doc/develop/uefi/uefi.rst
> > > @@ -318,6 +318,79 @@ 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
> > > +     }
> >
> > This seems to be neither YAML nor JSON. Can't we use a standardized
> > format? YAML is easily parsed in C with libfyaml (see
> > https://www.wpsoftware.net/andrew/pages/libyaml.html).
>
> Can we please get this series landed without the config file at first?
> If it useful we can add it later, but it is a complexity that is not
> necessary for an initial series.

We do need support for generation of capsules through the config file.
There is another patchset [1] which will be leveraging generation of
capsules through the config file. I believe AMD(Xilinx) too is looking
for support of such functionality, whereby the capsule gets generated
after reading the parameters from the config file. Not being able to
generate capsules through the config file as part of the build would
be a half baked support.

In my earlier reply [2] to your concern about using relative paths for
capsule generation, I had mentioned that if we cannot extend binman
tests to use absolute paths, we can drop testing this scenario in the
binman tests suite since this feature is actually getting tested as
part of the larger EFI capsule update feature testing. Would that not
be okay with you? Else we have the option of using absolute paths for
the indir and outdir, instead of the runtime generated directories,
only for this feature test of course.

-sughosh

[1] - https://lists.denx.de/pipermail/u-boot/2023-June/520407.html
[2] - https://lists.denx.de/pipermail/u-boot/2023-July/523779.html