[PATCH 0/5] fitimage-related changes

[PATCH 0/5] fitimage-related changes

[Paul Eggleton]

Doc changes corresponding to patches for kernel-fitimage class that were
recently merged to master, as well as some related tweaks.


The following changes since commit b268b1b190861cb203fa642e57794acb402280a7:

  releases: conf: add link to 3.2.1, update to include 3.2.1 (2020-12-15 10:59:41 -0800)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib paule/fitimage-docs
  http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/fitimage-docs

Paul Eggleton (5):
  classes: minor corrections to kernel-fitimage section
  variables: clarify KERNEL_ALT_IMAGETYPE reference
  variables: explicitly state that UBOOT_MKIMAGE_DTCOPTS is optional
  variables: Add documentation for new kernel-fitimage vars
  ref-manual: use consistent capitalisation of U-Boot

 documentation/ref-manual/classes.rst       | 16 +++++-----
 documentation/ref-manual/migration-1.7.rst |  2 +-
 documentation/ref-manual/variables.rst     | 48 ++++++++++++++++++++++++++----
 3 files changed, 51 insertions(+), 15 deletions(-)

-- 
1.8.3.1

[PATCH 1/5] classes: minor corrections to kernel-fitimage section

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Minor syntax and formatting corrections.

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

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 5a30ce3..08ced7f 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1374,18 +1374,18 @@ generation.
 ``kernel-fitimage.bbclass``
 ===========================
 
-The ``kernel-fitimage`` class provides support to pack a kernel Image,
+The ``kernel-fitimage`` class provides support to pack a kernel image,
 device trees and a RAM disk into a single FIT image. In theory, a FIT
-image can support any number of kernels, RAM disks and device-trees.
+image can support any number of kernels, RAM disks and device trees.
 However, ``kernel-fitimage`` currently only supports
 limited usescases: just one kernel image, an optional RAM disk, and
-any number of device tree.
+any number of device trees.
 
 To create a FIT image, it is required that :term:`KERNEL_CLASSES`
-is set to "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
+is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
 is set to "fitImage".
 
-The options for the device tree compiler passed to mkimage -D feature
+The options for the device tree compiler passed to ``mkimage -D``
 when creating the FIT image are specified using the
 :term:`UBOOT_MKIMAGE_DTCOPTS` variable.
 
-- 
1.8.3.1

[PATCH 2/5] variables: clarify KERNEL_ALT_IMAGETYPE reference

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Make it clear that KERNEL_ALT_IMAGETYPE is intended to allow building an
additional image type.

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

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 8c6cc46..4508bb1 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3983,8 +3983,9 @@ system and gives an overview of their function and contents.
       when building the kernel and is passed to ``make`` as the target to
       build.
 
-      If you want to build an alternate kernel image type, use the
-      :term:`KERNEL_ALT_IMAGETYPE` variable.
+      If you want to build an alternate kernel image type in addition to that
+      specified by ``KERNEL_IMAGETYPE``, use the :term:`KERNEL_ALT_IMAGETYPE`
+      variable.
 
    :term:`KERNEL_MODULE_AUTOLOAD`
       Lists kernel modules that need to be auto-loaded during boot.
-- 
1.8.3.1

[PATCH 3/5] variables: explicitly state that UBOOT_MKIMAGE_DTCOPTS is optional

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

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

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4508bb1..8f7f86e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8444,6 +8444,8 @@ system and gives an overview of their function and contents.
    :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_RD_ENTRYPOINT`
       Specifies the entrypoint for the RAM disk image.
-- 
1.8.3.1

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

[Paul Eggleton]

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:
+      ::
+
+         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
-- 
1.8.3.1

[PATCH 5/5] ref-manual: use consistent capitalisation of U-Boot

[Paul Eggleton]

From: Paul Eggleton <paul.eggleton@microsoft.com>

Change all instances of U-boot to U-Boot.

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
---
 documentation/ref-manual/classes.rst       | 6 +++---
 documentation/ref-manual/migration-1.7.rst | 2 +-
 documentation/ref-manual/variables.rst     | 8 ++++----
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 08ced7f..d049ca7 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1391,19 +1391,19 @@ when creating the FIT image are specified using the
 
 Only a single kernel can be added to the FIT image created by
 ``kernel-fitimage`` and the kernel image in FIT is mandatory. The
-address where the kernel image is to be loaded by U-boot is
+address where the kernel image is to be loaded by U-Boot is
 specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
 :term:`UBOOT_ENTRYPOINT`.
 
 Multiple device trees can be added to the FIT image created by
 ``kernel-fitimage`` and the device tree is optional.
-The address where the device tree is to be loaded by U-boot is
+The address where the device tree is to be loaded by U-Boot is
 specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
 and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
 
 Only a single RAM disk can be added to the FIT image created by
 ``kernel-fitimage`` and the RAM disk in FIT is optional.
-The address where the RAM disk image is to be loaded by U-boot
+The address where the RAM disk image is to be loaded by U-Boot
 is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
 :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
 :term:`INITRAMFS_IMAGE` is specified.
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst
index 19275b3..54544e4 100644
--- a/documentation/ref-manual/migration-1.7.rst
+++ b/documentation/ref-manual/migration-1.7.rst
@@ -190,7 +190,7 @@ Removed Recipes
 
 The following recipes have been removed:
 
--  ``x-load``: This recipe has been superseded by U-boot SPL for all
+-  ``x-load``: This recipe has been superseded by U-Boot SPL for all
    Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which
    contains a maintained recipe, should be used instead.
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 607ebfe..330f7dd 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -8405,21 +8405,21 @@ system and gives an overview of their function and contents.
       In this example, "sd" is selected as the configuration of the possible four for the
       ``UBOOT_MACHINE``. The "sd" configuration defines
       "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the
-      "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image.
+      "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-Boot image.
 
       For more information on how the ``UBOOT_CONFIG`` is handled, see the
       :ref:`uboot-config <ref-classes-uboot-config>`
       class.
 
    :term:`UBOOT_DTB_LOADADDRESS`
-      Specifies the load address for the dtb image used by U-boot. During FIT
+      Specifies the load address for the dtb image used by U-Boot. During FIT
       image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in
       :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify
       the load address to be used in
       creating the dtb sections of Image Tree Source for the FIT image.
 
    :term:`UBOOT_DTBO_LOADADDRESS`
-      Specifies the load address for the dtbo image used by U-boot.  During FIT
+      Specifies the load address for the dtbo image used by U-Boot.  During FIT
       image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in
       :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in
       creating the dtbo sections of Image Tree Source for the FIT image.
@@ -8504,7 +8504,7 @@ system and gives an overview of their function and contents.
       certificate used for signing FIT image.
 
    :term:`UBOOT_SIGN_KEYNAME`
-      The name of keys used for signing U-boot FIT image stored in
+      The name of keys used for signing U-Boot FIT image stored in
       :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt
       certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have
       :term:`UBOOT_SIGN_KEYNAME` set to "dev".
-- 
1.8.3.1

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

[Quentin Schulz]

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

Re: [docs] [PATCH 0/5] fitimage-related changes

[Quentin Schulz]

Hi Paul,

On Mon, Dec 21, 2020 at 05:05:59PM -0800, Paul Eggleton wrote:
> Doc changes corresponding to patches for kernel-fitimage class that were
> recently merged to master, as well as some related tweaks.
> 
> 
> The following changes since commit b268b1b190861cb203fa642e57794acb402280a7:
> 
>   releases: conf: add link to 3.2.1, update to include 3.2.1 (2020-12-15 10:59:41 -0800)
> 
> are available in the git repository at:
> 
>   git://git.yoctoproject.org/poky-contrib paule/fitimage-docs
>   http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/fitimage-docs
> 
> Paul Eggleton (5):
>   classes: minor corrections to kernel-fitimage section
>   variables: clarify KERNEL_ALT_IMAGETYPE reference
>   variables: explicitly state that UBOOT_MKIMAGE_DTCOPTS is optional
>   variables: Add documentation for new kernel-fitimage vars

Except for the small :\n:: issue in this one ^:

Reviewed-by: Quentin Schulz <quentin.schulz@streamunlimited.com>

Thanks!
Quentin

Re: [docs] [PATCH 0/5] fitimage-related changes

[Richard Purdie]

On Tue, 2020-12-22 at 10:41 +0100, Quentin Schulz wrote:
> Hi Paul,
> 
> On Mon, Dec 21, 2020 at 05:05:59PM -0800, Paul Eggleton wrote:
> > Doc changes corresponding to patches for kernel-fitimage class that
> > were
> > recently merged to master, as well as some related tweaks.
> > 
> > 
> > The following changes since commit
> > b268b1b190861cb203fa642e57794acb402280a7:
> > 
> >   releases: conf: add link to 3.2.1, update to include 3.2.1 (2020-
> > 12-15 10:59:41 -0800)
> > 
> > are available in the git repository at:
> > 
> >   git://git.yoctoproject.org/poky-contrib paule/fitimage-docs
> >   
> > http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/fitimage-docs
> > 
> > Paul Eggleton (5):
> >   classes: minor corrections to kernel-fitimage section
> >   variables: clarify KERNEL_ALT_IMAGETYPE reference
> >   variables: explicitly state that UBOOT_MKIMAGE_DTCOPTS is
> > optional
> >   variables: Add documentation for new kernel-fitimage vars
> 
> Except for the small :\n:: issue in this one ^:

I tweaked that as I queued the patches on master-next...

Cheers,

Richard

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

[Nicolas Dechesne]

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

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

[Robert P. J. Day]

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