summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorUsama Arif <usama.arif@arm.com>2020-07-29 15:35:52 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-08-08 09:18:12 +0100
commit6f9d4614e976f3420f6dad1bee0aeac57446f2d4 (patch)
tree94ac3aa96f272872253244fbf264349bfd61306f /documentation/ref-manual
parent392c117e7ab05da10a374f695d5232e7527ab5de (diff)
downloadpoky-6f9d4614e976f3420f6dad1bee0aeac57446f2d4.tar.gz
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 <usama.arif@arm.com> Cc: Richard Purdie <richard.purdie@linuxfoundation.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-classes.xml76
-rw-r--r--documentation/ref-manual/ref-variables.xml142
2 files changed, 217 insertions, 1 deletions
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
1880 1880
1881 <para> 1881 <para>
1882 The <filename>kernel-fitimage</filename> class provides support to 1882 The <filename>kernel-fitimage</filename> class provides support to
1883 pack zImages. 1883 pack a kernel Image, device trees and a RAM disk into a single
1884 FIT image. In theory, a FIT image can support any number of kernels,
1885 RAM disks and device-trees.
1886 However, <filename>kernel-fitimage</filename> currently only supports
1887 limited usescases: just one kernel image, an optional RAM disk, and
1888 any number of device tree.
1884 </para> 1889 </para>
1890
1891 <para>
1892 To create a FIT image, it is required that
1893 <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename>
1894 is set to "kernel-fitimage" and
1895 <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename>
1896 is set to "fitImage".
1897 </para>
1898
1899 <para>
1900 The options for the device tree compiler passed to mkimage -D feature
1901 when creating the FIT image are specified using the
1902 <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>
1903 variable.
1904 </para>
1905
1906 <para>
1907 Only a single kernel can be added to the FIT image created by
1908 <filename>kernel-fitimage</filename> and the kernel image in FIT is
1909 mandatory.
1910 The address where the kernel image is to be loaded by U-boot is
1911 specified by
1912 <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename>
1913 and the entrypoint by
1914 <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>.
1915 </para>
1916
1917 <para>
1918 Multiple device trees can be added to the FIT image created by
1919 <filename>kernel-fitimage</filename> and the device tree is optional.
1920 The address where the device tree is to be loaded by U-boot is
1921 specified by
1922 <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename>
1923 for device tree overlays and by
1924 <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename>
1925 for device tree binaries.
1926 </para>
1927
1928 <para>
1929 Only a single RAM disk can be added to the FIT image created by
1930 <filename>kernel-fitimage</filename> and the RAM disk in FIT is
1931 optional.
1932 The address where the RAM disk image is to be loaded by U-boot
1933 is specified by
1934 <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename>
1935 and the entrypoint by
1936 <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>.
1937 The ramdisk is added to FIT image when
1938 <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename>
1939 is specified.
1940 </para>
1941
1942 <para>
1943 The FIT image generated by <filename>kernel-fitimage</filename> class
1944 is signed when the variables
1945 <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>,
1946 <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>,
1947 <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
1948 and
1949 <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename>
1950 are set appropriately.
1951 The default values used for
1952 <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename>
1953 and
1954 <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename>
1955 in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048"
1956 respectively.
1957 </para>
1958
1885</section> 1959</section>
1886 1960
1887<section id='ref-classes-kernel-grub'> 1961<section id='ref-classes-kernel-grub'>
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 @@
4991 </glossdef> 4991 </glossdef>
4992 </glossentry> 4992 </glossentry>
4993 4993
4994 <glossentry id='var-FIT_HASH_ALG'><glossterm>FIT_HASH_ALG</glossterm>
4995 <info>
4996 FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image."
4997 </info>
4998 <glossdef>
4999 <para role="glossdeffirst">
5000 Specifies the hash algorithm used in creating the FIT Image.
5001 For e.g. sha256.
5002 </para>
5003 </glossdef>
5004 </glossentry>
5005
5006 <glossentry id='var-FIT_SIGN_ALG'><glossterm>FIT_SIGN_ALG</glossterm>
5007 <info>
5008 FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image."
5009 </info>
5010 <glossdef>
5011 <para role="glossdeffirst">
5012 Specifies the signature algorithm used in creating the FIT Image.
5013 For e.g. rsa2048.
5014 </para>
5015 </glossdef>
5016 </glossentry>
5017
4994 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> 5018 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
4995 <info> 5019 <info>
4996 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'." 5020 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 @@
15960 </glossdef> 15984 </glossdef>
15961 </glossentry> 15985 </glossentry>
15962 15986
15987 <glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm>
15988 <info>
15989 UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb."
15990 </info>
15991 <glossdef>
15992 <para role="glossdeffirst">
15993 Specifies the load address for the dtb image used by U-boot.
15994 During FIT image creation, the
15995 <filename>UBOOT_DTB_LOADADDRESS</filename> variable is used
15996 in <filename>kernel-fitimage</filename> class to specify the
15997 load address to be used in creating the dtb sections of
15998 Image Tree Source for the FIT image.
15999 </para>
16000 </glossdef>
16001 </glossentry>
16002
16003 <glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm>
16004 <info>
16005 UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo."
16006 </info>
16007 <glossdef>
16008 <para role="glossdeffirst">
16009 Specifies the load address for the dtbo image used by U-boot.
16010 During FIT image creation, the
16011 <filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used
16012 in <filename>kernel-fitimage</filename> class to specify the
16013 load address to be used in creating the dtbo sections of
16014 Image Tree Source for the FIT image.
16015 </para>
16016 </glossdef>
16017 </glossentry>
16018
15963 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> 16019 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
15964 <info> 16020 <info>
15965 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." 16021 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
@@ -16045,6 +16101,51 @@
16045 </glossdef> 16101 </glossdef>
16046 </glossentry> 16102 </glossentry>
16047 16103
16104 <glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm>
16105 <info>
16106 UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature."
16107 </info>
16108 <glossdef>
16109 <para role="glossdeffirst">
16110 Options for the device tree compiler passed to mkimage '-D'
16111 feature while creating FIT image in
16112 <filename>kernel-fitimage</filename> class.
16113 </para>
16114 </glossdef>
16115 </glossentry>
16116
16117 <glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm>
16118 <info>
16119 UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image."
16120 </info>
16121 <glossdef>
16122 <para role="glossdeffirst">
16123 Specifies the load address for the RAM disk image.
16124 During FIT image creation, the
16125 <filename>UBOOT_RD_LOADADDRESS</filename> variable is used
16126 in <filename>kernel-fitimage</filename> class to specify the
16127 load address to be used in creating the Image Tree Source for
16128 the FIT image.
16129 </para>
16130 </glossdef>
16131 </glossentry>
16132
16133 <glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm>
16134 <info>
16135 UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image."
16136 </info>
16137 <glossdef>
16138 <para role="glossdeffirst">
16139 Specifies the entrypoint for the RAM disk image.
16140 During FIT image creation, the
16141 <filename>UBOOT_RD_ENTRYPOINT</filename> variable is used
16142 in <filename>kernel-fitimage</filename> class to specify the
16143 entrypoint to be used in creating the Image Tree Source for
16144 the FIT image.
16145 </para>
16146 </glossdef>
16147 </glossentry>
16148
16048 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> 16149 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16049 <info> 16150 <info>
16050 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." 16151 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
@@ -16063,6 +16164,47 @@
16063 </glossdef> 16164 </glossdef>
16064 </glossentry> 16165 </glossentry>
16065 16166
16167 <glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm>
16168 <info>
16169 UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image."
16170 </info>
16171 <glossdef>
16172 <para role="glossdeffirst">
16173 Enable signing of FIT image. The default value is "0".
16174 </para>
16175 </glossdef>
16176 </glossentry>
16177
16178 <glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm>
16179 <info>
16180 UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image."
16181 </info>
16182 <glossdef>
16183 <para role="glossdeffirst">
16184 Location of the directory containing the RSA key and
16185 certificate used for signing FIT image.
16186 </para>
16187 </glossdef>
16188 </glossentry>
16189
16190 <glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm>
16191 <info>
16192 UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image"
16193 </info>
16194 <glossdef>
16195 <para role="glossdeffirst">
16196 The name of keys used for signing U-boot FIT image stored in
16197 <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
16198 directory. For e.g. dev.key key and dev.crt certificate
16199 stored in
16200 <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
16201 directory will have
16202 <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename>
16203 set to "dev".
16204 </para>
16205 </glossdef>
16206 </glossentry>
16207
16066 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> 16208 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16067 <info> 16209 <info>
16068 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." 16210 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."