[v9,09/10] doc: Add documentation to highlight capsule generation related updates

The EFI capsules can now be generated as part of u-boot build, through
binman. Highlight these changes in the documentation.

Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
Changes since V8:
* Remove mention of capsule generation through config file.

 doc/develop/uefi/uefi.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

On Sat, Aug 12, 2023 at 11:27:24AM +0530, Sughosh Ganu wrote:

> The EFI capsules can now be generated as part of u-boot build, through
> binman. Highlight these changes in the documentation.
> 
> Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
[snip]
> +Capsule Generation through binman
> +*********************************
> +
> +Support has also been added to generate capsules during u-boot build
> +through binman. This requires the platform's DTB to be populated with
> +the capsule entry nodes for binman. The capsules then can be generated
> +by specifying the capsule parameters as properties in the capsule
> +entry node.
> +
> +Check the arch/sandbox/dts/sandbox_capsule.dtsi file for the sandbox
> +platform as reference for how to generate capsules through binman as
> +part of u-boot build.

In that I have any problems with the series at this point, it is this.
A 314 line example file is not a good example.  This is because it has
all of the tests.  I would frankly rather see an in-line example here of
what a typical capsule dtsi looks like instead.  I'm not NAK'ing the
series, and this could be a follow-up.

Hi Sughosh,

On Fri, 11 Aug 2023 at 23:58, Sughosh Ganu <sughosh.ganu@linaro.org> wrote:
>
> The EFI capsules can now be generated as part of u-boot build, through

U-Boot

> binman. Highlight these changes in the documentation.
>
> Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> ---
> Changes since V8:
> * Remove mention of capsule generation through config file.
>
>  doc/develop/uefi/uefi.rst | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
>
> diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> index a7a41f2fac..1ab5e5e2d1 100644
> --- a/doc/develop/uefi/uefi.rst
> +++ b/doc/develop/uefi/uefi.rst
> @@ -318,6 +318,9 @@ Run the following command
>        --guid <image GUID> \
>        <capsule_file_name>
>
> +Capsule with firmware version
> +*****************************
> +
>  The UEFI specification does not define the firmware versioning mechanism.
>  EDK II reference implementation inserts the FMP Payload Header right before
>  the payload. It coutains the fw_version and lowest supported version,
> @@ -345,6 +348,19 @@ add --fw-version option in mkeficapsule tool.
>  If the --fw-version option is not set, FMP Payload Header is not inserted
>  and fw_version is set as 0.
>
> +Capsule Generation through binman
> +*********************************
> +
> +Support has also been added to generate capsules during u-boot build

same

> +through binman. This requires the platform's DTB to be populated with
> +the capsule entry nodes for binman. The capsules then can be generated
> +by specifying the capsule parameters as properties in the capsule
> +entry node.
> +
> +Check the arch/sandbox/dts/sandbox_capsule.dtsi file for the sandbox
> +platform as reference for how to generate capsules through binman as
> +part of u-boot build.

same

Here you should add a link to the binman entry-type docs for efi-capsule, e.g.:

   See etype_efi_capsule_ for documentation about the efi-capsule entry type.

> +
>  Performing the update
>  *********************
>
> --
> 2.34.1
>

Regards,
SImon

hi Tom,

On Sat, 12 Aug 2023 at 19:47, Tom Rini <trini@konsulko.com> wrote:
>
> On Sat, Aug 12, 2023 at 11:27:24AM +0530, Sughosh Ganu wrote:
>
> > The EFI capsules can now be generated as part of u-boot build, through
> > binman. Highlight these changes in the documentation.
> >
> > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> > Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> [snip]
> > +Capsule Generation through binman
> > +*********************************
> > +
> > +Support has also been added to generate capsules during u-boot build
> > +through binman. This requires the platform's DTB to be populated with
> > +the capsule entry nodes for binman. The capsules then can be generated
> > +by specifying the capsule parameters as properties in the capsule
> > +entry node.
> > +
> > +Check the arch/sandbox/dts/sandbox_capsule.dtsi file for the sandbox
> > +platform as reference for how to generate capsules through binman as
> > +part of u-boot build.
>
> In that I have any problems with the series at this point, it is this.
> A 314 line example file is not a good example.  This is because it has
> all of the tests.  I would frankly rather see an in-line example here of
> what a typical capsule dtsi looks like instead.  I'm not NAK'ing the
> series, and this could be a follow-up.

The whole idea of this dtsi was to use the sandbox build as a kind of
illustrative example of how to generate capsules as part of the build.
One of the follow-up series that I already have lined up is the
support for capsule files through the config file. I suppose as part
of that series, I can put the single binman node for capsule
generation through config file in this dtsi, along with a subset of
the current set of nodes, say for generating signed capsules. The rest
of the nodes can be moved to the corresponding test directory, and the
capsules be generated using the binman command directly. We can
discuss as part of that review.

-sughosh

hi Simon,

On Sat, 12 Aug 2023 at 19:55, Simon Glass <sjg@chromium.org> wrote:
>
> Hi Sughosh,
>
> On Fri, 11 Aug 2023 at 23:58, Sughosh Ganu <sughosh.ganu@linaro.org> wrote:
> >
> > The EFI capsules can now be generated as part of u-boot build, through
>
> U-Boot

Will change

>
> > binman. Highlight these changes in the documentation.
> >
> > Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
> > Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
> > ---
> > Changes since V8:
> > * Remove mention of capsule generation through config file.
> >
> >  doc/develop/uefi/uefi.rst | 16 ++++++++++++++++
> >  1 file changed, 16 insertions(+)
> >
> > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> > index a7a41f2fac..1ab5e5e2d1 100644
> > --- a/doc/develop/uefi/uefi.rst
> > +++ b/doc/develop/uefi/uefi.rst
> > @@ -318,6 +318,9 @@ Run the following command
> >        --guid <image GUID> \
> >        <capsule_file_name>
> >
> > +Capsule with firmware version
> > +*****************************
> > +
> >  The UEFI specification does not define the firmware versioning mechanism.
> >  EDK II reference implementation inserts the FMP Payload Header right before
> >  the payload. It coutains the fw_version and lowest supported version,
> > @@ -345,6 +348,19 @@ add --fw-version option in mkeficapsule tool.
> >  If the --fw-version option is not set, FMP Payload Header is not inserted
> >  and fw_version is set as 0.
> >
> > +Capsule Generation through binman
> > +*********************************
> > +
> > +Support has also been added to generate capsules during u-boot build
>
> same

Will change

>
> > +through binman. This requires the platform's DTB to be populated with
> > +the capsule entry nodes for binman. The capsules then can be generated
> > +by specifying the capsule parameters as properties in the capsule
> > +entry node.
> > +
> > +Check the arch/sandbox/dts/sandbox_capsule.dtsi file for the sandbox
> > +platform as reference for how to generate capsules through binman as
> > +part of u-boot build.
>
> same
>
> Here you should add a link to the binman entry-type docs for efi-capsule, e.g.:
>
>    See etype_efi_capsule_ for documentation about the efi-capsule entry type.

Okay

-sughosh

>
> > +
> >  Performing the update
> >  *********************
> >
> > --
> > 2.34.1
> >
>
> Regards,
> SImon