ref-manual: Add documentation for kernel-fitimage
PATCH 1/1 ref-manual: Add documentation for kernel-fitimage
This documents kernel-fitimage.bbclass as well as the variables that are required to use the class to create a FIT image.
Signed-off-by Usama Arif <[email protected]>
Cc Richard Purdie <[email protected]>
--- documentation/ref-manual/ref-classes.xml | 76 ++++++++++- documentation/ref-manual/ref-variables.xml | 142 +++++++++++++++++++++ 2 files changed, 217 insertions(+), 1 deletion(-)
documentation/ref-manual/ref-classes.xml +75 -1
@@ -1880,8 +1880,82 @@ This check was removed for YP 2.3 release <para> The <filename>kernel-fitimage</filename> class provides support to - pack zImages. + 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. + However, <filename>kernel-fitimage</filename> currently only supports + limited usescases: just one kernel image, an optional RAM disk, and + any number of device tree. </para> + + <para> + To create a FIT image, it is required that + <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename> + is set to "kernel-fitimage" and + <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename> + is set to "fitImage". + </para> + + <para> + The options for the device tree compiler passed to mkimage -D feature + when creating the FIT image are specified using the + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename> + variable. + </para> + + <para> + Only a single kernel can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the kernel image in FIT is + mandatory. + The address where the kernel image is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>. + </para> + + <para> + Multiple device trees can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the device tree is optional. + The address where the device tree is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename> + for device tree overlays and by + <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename> + for device tree binaries. + </para> + + <para> + Only a single RAM disk can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the RAM disk in FIT is + optional. + The address where the RAM disk image is to be loaded by U-boot + is specified by + <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>. + The ramdisk is added to FIT image when + <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename> + is specified. + </para> + + <para> + The FIT image generated by <filename>kernel-fitimage</filename> class + is signed when the variables + <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>, + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>, + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + and + <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> + are set appropriately. + The default values used for + <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename> + and + <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename> + in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048" + respectively. + </para> + </section> <section id='ref-classes-kernel-grub'>
documentation/ref-manual/ref-variables.xml +142 -0
166 lines not on this page · raw message
Signature · 1 line
2.17.1
Quoted 264 lines · Usama Arif
This documents kernel-fitimage.bbclass as well as the variables that are required to use the class to create a FIT image.
Signed-off-by Usama Arif <[email protected]>Cc Richard Purdie <[email protected]>--- documentation/ref-manual/ref-classes.xml | 76 ++++++++++- documentation/ref-manual/ref-variables.xml | 142 +++++++++++++++++++++ 2 files changed, 217 insertions(+), 1 deletion(-)documentation/ref-manual/ref-classes.xml +75
-1@@ -1880,8 +1880,82 @@ This check was removed for YP 2.3 release <para> The <filename>kernel-fitimage</filename> class provides support to - pack zImages. + 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. + However, <filename>kernel-fitimage</filename> currently only supports + limited usescases: just one kernel image, an optional RAM disk, and + any number of device tree. </para> + + <para> + To create a FIT image, it is required that + <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename> + is set to "kernel-fitimage" and + <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename> + is set to "fitImage". + </para> + + <para> + The options for the device tree compiler passed to mkimage -D feature + when creating the FIT image are specified using the + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename> + variable. + </para> + + <para> + Only a single kernel can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the kernel image in FIT is + mandatory. + The address where the kernel image is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>. + </para> + + <para> + Multiple device trees can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the device tree is optional. + The address where the device tree is to be loaded by U-boot is + specified by + <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename> + for device tree overlays and by + <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename> + for device tree binaries. + </para> + + <para> + Only a single RAM disk can be added to the FIT image created by + <filename>kernel-fitimage</filename> and the RAM disk in FIT is + optional. + The address where the RAM disk image is to be loaded by U-boot + is specified by + <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename> + and the entrypoint by + <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>. + The ramdisk is added to FIT image when + <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename> + is specified. + </para> + + <para> + The FIT image generated by <filename>kernel-fitimage</filename> class + is signed when the variables + <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>, + <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>, + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + and + <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> + are set appropriately. + The default values used for + <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename> + and + <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename> + in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048" + respectively. + </para> + </section> <section id='ref-classes-kernel-grub'>documentation/ref-manual/ref-variables.xml +135
-0@@ -4991,6 +4991,30 @@ </glossdef> </glossentry> + <glossentry id='var-FIT_HASH_ALG'><glossterm>FIT_HASH_ALG</glossterm> + <info> + FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the hash algorithm used in creating the FIT Image. + For e.g. sha256. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FIT_SIGN_ALG'><glossterm>FIT_SIGN_ALG</glossterm> + <info> + FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the signature algorithm used in creating the FIT Image. + For e.g. rsa2048. + </para> + </glossdef> + </glossentry> + <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> <info> FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'."@@ -15960,6 +15984,38 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm> + <info> + UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the dtb image used by U-boot. + During FIT image creation, the + <filename>UBOOT_DTB_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the dtb sections of + Image Tree Source for the FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm> + <info> + UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the dtbo image used by U-boot. + During FIT image creation, the + <filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the dtbo sections of + Image Tree Source for the FIT image. + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> <info> UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."@@ -16045,6 +16101,51 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm> + <info> + UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature." + </info> + <glossdef> + <para role="glossdeffirst"> + Options for the device tree compiler passed to mkimage '-D' + feature while creating FIT image in + <filename>kernel-fitimage</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm> + <info> + UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the load address for the RAM disk image. + During FIT image creation, the + <filename>UBOOT_RD_LOADADDRESS</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + load address to be used in creating the Image Tree Source for + the FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm> + <info> + UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image." + </info> + <glossdef> + <para role="glossdeffirst"> + Specifies the entrypoint for the RAM disk image. + During FIT image creation, the + <filename>UBOOT_RD_ENTRYPOINT</filename> variable is used + in <filename>kernel-fitimage</filename> class to specify the + entrypoint to be used in creating the Image Tree Source for + the FIT image. + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> <info> UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."@@ -16063,6 +16164,47 @@ </glossdef> </glossentry> + <glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm> + <info> + UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image." + </info> + <glossdef> + <para role="glossdeffirst"> + Enable signing of FIT image. The default value is "0". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm> + <info> + UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image." + </info> + <glossdef> + <para role="glossdeffirst"> + Location of the directory containing the RSA key and + certificate used for signing FIT image. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm> + <info> + UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image" + </info> + <glossdef> + <para role="glossdeffirst"> + The name of keys used for signing U-boot FIT image stored in + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> + directory. For e.g. dev.key key and dev.crt certificate + stored in + <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
documentation/ref-manual/ref-variables.xml line 16210
Quoted 10 lines
documentation/ref-manual/ref-variables.xml +7
-0+ directory will have + <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> + set to "dev". + </para> + </glossdef> + </glossentry> + <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> <info> UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
Hi
This documentation assumes that the case for a single kernel and single RAM disk with no dtb is supported by kernel-fitimage.bbclass. https://lists.openembedded.org/g/openembedded-core/message/140810 adds support for this combination of usecase.
Thanks,
Usama