From 6f9d4614e976f3420f6dad1bee0aeac57446f2d4 Mon Sep 17 00:00:00 2001 From: Usama Arif Date: Wed, 29 Jul 2020 15:35:52 +0100 Subject: 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. (From yocto-docs rev: 3aeca3b342e5be92be562f6dea6b71390c31b636) Signed-off-by: Usama Arif Cc: Richard Purdie Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-classes.xml | 76 ++++++++++++++- documentation/ref-manual/ref-variables.xml | 142 +++++++++++++++++++++++++++++ 2 files changed, 217 insertions(+), 1 deletion(-) diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index ab12373ae0..1dcd5fdd03 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml @@ -1880,8 +1880,82 @@ This check was removed for YP 2.3 release The kernel-fitimage 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, kernel-fitimage currently only supports + limited usescases: just one kernel image, an optional RAM disk, and + any number of device tree. + + + To create a FIT image, it is required that + KERNEL_CLASSES + is set to "kernel-fitimage" and + KERNEL_IMAGETYPE + is set to "fitImage". + + + + The options for the device tree compiler passed to mkimage -D feature + when creating the FIT image are specified using the + UBOOT_MKIMAGE_DTCOPTS + variable. + + + + 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 + specified by + UBOOT_LOADADDRESS + and the entrypoint by + 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 + specified by + UBOOT_DTBO_LOADADDRESS + for device tree overlays and by + 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 + is specified by + UBOOT_RD_LOADADDRESS + and the entrypoint by + UBOOT_RD_ENTRYPOINT. + The ramdisk is added to FIT image when + INITRAMFS_IMAGE + is specified. + + + + The FIT image generated by kernel-fitimage class + is signed when the variables + UBOOT_SIGN_ENABLE, + UBOOT_MKIMAGE_DTCOPTS, + UBOOT_SIGN_KEYDIR + and + UBOOT_SIGN_KEYNAME + are set appropriately. + The default values used for + FIT_HASH_ALG + and + FIT_SIGN_ALG + in kernel-fitimage are "sha256" and "rsa2048" + respectively. + +
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 8cc7ef8fc9..a5064807e5 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -4991,6 +4991,30 @@ + FIT_HASH_ALG + + FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image." + + + + Specifies the hash algorithm used in creating the FIT Image. + For e.g. sha256. + + + + + FIT_SIGN_ALG + + FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image." + + + + Specifies the signature algorithm used in creating the FIT Image. + For e.g. rsa2048. + + + + FONT_EXTRA_RDEPENDS 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 @@ + UBOOT_DTB_LOADADDRESS + + UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb." + + + + Specifies the load address for the dtb image used by U-boot. + During FIT image creation, the + UBOOT_DTB_LOADADDRESS variable is used + in kernel-fitimage class to specify the + load address to be used in creating the dtb sections of + Image Tree Source for the FIT image. + + + + + UBOOT_DTBO_LOADADDRESS + + UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo." + + + + Specifies the load address for the dtbo image used by U-boot. + During FIT image creation, the + UBOOT_DTBO_LOADADDRESS variable is used + in kernel-fitimage class to specify the + load address to be used in creating the dtbo sections of + Image Tree Source for the FIT image. + + + + UBOOT_ENTRYPOINT UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." @@ -16045,6 +16101,51 @@ + UBOOT_MKIMAGE_DTCOPTS + + UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature." + + + + Options for the device tree compiler passed to mkimage '-D' + feature while creating FIT image in + kernel-fitimage class. + + + + + UBOOT_RD_LOADADDRESS + + UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image." + + + + Specifies the load address for the RAM disk image. + During FIT image creation, the + UBOOT_RD_LOADADDRESS variable is used + in kernel-fitimage class to specify the + load address to be used in creating the Image Tree Source for + the FIT image. + + + + + UBOOT_RD_ENTRYPOINT + + UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image." + + + + Specifies the entrypoint for the RAM disk image. + During FIT image creation, the + UBOOT_RD_ENTRYPOINT variable is used + in kernel-fitimage class to specify the + entrypoint to be used in creating the Image Tree Source for + the FIT image. + + + + UBOOT_SUFFIX UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." @@ -16063,6 +16164,47 @@ + UBOOT_SIGN_ENABLE + + UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image." + + + + Enable signing of FIT image. The default value is "0". + + + + + UBOOT_SIGN_KEYDIR + + UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image." + + + + Location of the directory containing the RSA key and + certificate used for signing FIT image. + + + + + UBOOT_SIGN_KEYNAME + + UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image" + + + + The name of keys used for signing U-boot FIT image stored in + UBOOT_SIGN_KEYDIR + directory. For e.g. dev.key key and dev.crt certificate + stored in + UBOOT_SIGN_KEYDIR + directory will have + UBOOT_SIGN_KEYNAME + set to "dev". + + + + UBOOT_TARGET UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." -- cgit v1.2.3-54-g00ecf