[4/5] variables: Add documentation for new kernel-fitimage vars

Submitted by Paul Eggleton on Dec. 22, 2020, 1:06 a.m. | Patch ID: 179044

Details

Message ID 2a491bf195731319b9fa3bca15b95f7ce8342af5.1608598606.git.paul.eggleton@linux.microsoft.com
State New
Headers show

Commit Message

Paul Eggleton Dec. 22, 2020, 1:06 a.m.
From: Paul Eggleton <paul.eggleton@microsoft.com>

Add documentation for FIT_DESC, FIT_SIGN_INDIVIDUAL, UBOOT_MKIMAGE,
UBOOT_MKIMAGE_SIGN and UBOOT_MKIMAGE_SIGN_ARGS.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/variables.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

Patch hide | download patch | download mbox

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 8f7f86e..607ebfe 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -2538,6 +2538,14 @@  system and gives an overview of their function and contents.
       For guidance on how to create your own file permissions settings
       table file, examine the existing ``fs-perms.txt``.
 
+   :term:`FIT_DESC`
+      Specifies the description string encoded into a fitImage. The default
+      value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
+      class as follows:
+      ::
+
+         FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
+
    :term:`FIT_GENERATE_KEYS`
       Decides whether to generate the keys for signing fitImage if they
       don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``.
@@ -2568,6 +2576,13 @@  system and gives an overview of their function and contents.
       Size of private key in number of bits used in fitImage. The default
       value is "2048".
 
+   :term:`FIT_SIGN_INDIVIDUAL`
+      If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
+      class will sign the kernel, dtb and ramdisk images individually in addition
+      to signing the fitImage itself. This could be useful if you are
+      intending to verify signatures in another context than booting via
+      U-Boot.
+
    :term:`FONT_EXTRA_RDEPENDS`
       When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
       this variable specifies the runtime dependencies for font packages.
@@ -8441,12 +8456,30 @@  system and gives an overview of their function and contents.
       Specifies the target called in the ``Makefile``. The default target
       is "all".
 
+   :term:`UBOOT_MKIMAGE`
+      Specifies the name of the mkimage command as used by the
+      :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble
+      the FIT image. This can be used to substitute an alternative command, wrapper
+      script or function if desired. The default is "uboot-mkimage".
+
    :term:`UBOOT_MKIMAGE_DTCOPTS`
       Options for the device tree compiler passed to mkimage '-D'
       feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class.
       If ``UBOOT_MKIMAGE_DTCOPTS`` is not set then kernel-fitimage will not
       pass the ``-D`` option to mkimage.
 
+   :term:`UBOOT_MKIMAGE_SIGN`
+      Specifies the name of the mkimage command as used by the
+      :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign
+      the FIT image after it has been assembled (if enabled). This can be used
+      to substitute an alternative command, wrapper script or function if
+      desired. The default is "${:term:`UBOOT_MKIMAGE`}".
+
+   :term:`UBOOT_MKIMAGE_SIGN_ARGS`
+      Optionally specifies additional arguments for the
+      :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the
+      mkimage command when signing the FIT image.
+
    :term:`UBOOT_RD_ENTRYPOINT`
       Specifies the entrypoint for the RAM disk image.
       During FIT image creation, the

Comments

Quentin Schulz Dec. 22, 2020, 9:39 a.m.
Hi Paul,

On Mon, Dec 21, 2020 at 05:06:03PM -0800, Paul Eggleton wrote:
> From: Paul Eggleton <paul.eggleton@microsoft.com>
> 
> Add documentation for FIT_DESC, FIT_SIGN_INDIVIDUAL, UBOOT_MKIMAGE,
> UBOOT_MKIMAGE_SIGN and UBOOT_MKIMAGE_SIGN_ARGS.
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> ---
>  documentation/ref-manual/variables.rst | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 8f7f86e..607ebfe 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -2538,6 +2538,14 @@ system and gives an overview of their function and contents.
>        For guidance on how to create your own file permissions settings
>        table file, examine the existing ``fs-perms.txt``.
>  
> +   :term:`FIT_DESC`
> +      Specifies the description string encoded into a fitImage. The default
> +      value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
> +      class as follows:
> +      ::

The two lines above have the same outcome as:

class as follows::

IIRC. I don't remember if a patch was sent by Robert recently nor if it
was merged (does not seem so?) but we strive for consistency on this one
by having all :\n:: migrated to :: at the end of a paragraph.

c.f.: https://lists.yoctoproject.org/g/docs/message/557

Thanks,
Quentin
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#779): https://lists.yoctoproject.org/g/docs/message/779
Mute This Topic: https://lists.yoctoproject.org/mt/79140086/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Nicolas Dechesne Dec. 22, 2020, 11:40 a.m.
On Tue, Dec 22, 2020 at 10:39 AM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> Hi Paul,
>
> On Mon, Dec 21, 2020 at 05:06:03PM -0800, Paul Eggleton wrote:
> > From: Paul Eggleton <paul.eggleton@microsoft.com>
> >
> > Add documentation for FIT_DESC, FIT_SIGN_INDIVIDUAL, UBOOT_MKIMAGE,
> > UBOOT_MKIMAGE_SIGN and UBOOT_MKIMAGE_SIGN_ARGS.
> >
> > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > ---
> >  documentation/ref-manual/variables.rst | 33 +++++++++++++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> >
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index 8f7f86e..607ebfe 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -2538,6 +2538,14 @@ system and gives an overview of their function and contents.
> >        For guidance on how to create your own file permissions settings
> >        table file, examine the existing ``fs-perms.txt``.
> >
> > +   :term:`FIT_DESC`
> > +      Specifies the description string encoded into a fitImage. The default
> > +      value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
> > +      class as follows:
> > +      ::
>
> The two lines above have the same outcome as:
>
> class as follows::
>
> IIRC. I don't remember if a patch was sent by Robert recently nor if it
> was merged (does not seem so?) but we strive for consistency on this one
> by having all :\n:: migrated to :: at the end of a paragraph.
>
> c.f.: https://lists.yoctoproject.org/g/docs/message/557

We agreed to do it, I haven't seen any updates/response on that
thread. So as of now, it's not done..
As such, I don't think it's blocking for new patches.

>
> Thanks,
> Quentin
>
> 
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#789): https://lists.yoctoproject.org/g/docs/message/789
Mute This Topic: https://lists.yoctoproject.org/mt/79140086/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Robert P. J. Day Dec. 22, 2020, 11:42 a.m.
On Tue, 22 Dec 2020, Nicolas Dechesne wrote:

> On Tue, Dec 22, 2020 at 10:39 AM Quentin Schulz
> <quentin.schulz@streamunlimited.com> wrote:
> >
> > Hi Paul,
> >
> > On Mon, Dec 21, 2020 at 05:06:03PM -0800, Paul Eggleton wrote:
> > > From: Paul Eggleton <paul.eggleton@microsoft.com>
> > >
> > > Add documentation for FIT_DESC, FIT_SIGN_INDIVIDUAL, UBOOT_MKIMAGE,
> > > UBOOT_MKIMAGE_SIGN and UBOOT_MKIMAGE_SIGN_ARGS.
> > >
> > > Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
> > > ---
> > >  documentation/ref-manual/variables.rst | 33 +++++++++++++++++++++++++++++++++
> > >  1 file changed, 33 insertions(+)
> > >
> > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > > index 8f7f86e..607ebfe 100644
> > > --- a/documentation/ref-manual/variables.rst
> > > +++ b/documentation/ref-manual/variables.rst
> > > @@ -2538,6 +2538,14 @@ system and gives an overview of their function and contents.
> > >        For guidance on how to create your own file permissions settings
> > >        table file, examine the existing ``fs-perms.txt``.
> > >
> > > +   :term:`FIT_DESC`
> > > +      Specifies the description string encoded into a fitImage. The default
> > > +      value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
> > > +      class as follows:
> > > +      ::
> >
> > The two lines above have the same outcome as:
> >
> > class as follows::
> >
> > IIRC. I don't remember if a patch was sent by Robert recently nor if it
> > was merged (does not seem so?) but we strive for consistency on this one
> > by having all :\n:: migrated to :: at the end of a paragraph.
> >
> > c.f.: https://lists.yoctoproject.org/g/docs/message/557
>
> We agreed to do it, I haven't seen any updates/response on that
> thread. So as of now, it's not done..
> As such, I don't think it's blocking for new patches.

  apologies ... i've been swamped with my current contract. here's
hoping i get some free time over the holidays.

rday
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#790): https://lists.yoctoproject.org/g/docs/message/790
Mute This Topic: https://lists.yoctoproject.org/mt/79140086/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-