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

[Simon Glass]

Hi Sughosh,

On Wed, 26 Jul 2023 at 03:17, Sughosh Ganu <sughosh.ganu at linaro.org> wrote:
>
> 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.

Well let's drop it for now. It is creating a parallel description
format when we are trying to have just one (binman).

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

No, let's drop the config file for now. It is making everything too confusing.

Regards,
Simon


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