sphinx: import docs

The Yocto Project docs was migrated from Docbook to Sphinx in YP
 3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to'
 the docs in 3.2, we agreed to backport sphinx docs onto 3.1.

This first patch brings all changes done in 3.2 until:
7f64574f7 README: include detailed information about sphinx

There are other changes after this commit, but they will be
 selectively backported in individual patches.

This patch was generated with the following command:

git cherry-pick -n \
 $(git log --reverse --oneline \
 ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \
| cut -f1 -d' ')

The following commits were applies in the dunfell docs, but not in
master, so they were first reverted (and squashed into this change). A
commit will reintroduce the content from these patches in the Sphinx
files in a followup patch.

069c27574 Documenation: Prepared for the 3.1.1 release
bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit
17cc71a8f Documenation: Prepared for the 3.1.2 release
1a69e2c02 Documenation: Prepared for the 3.1.3 release
8910ac1c7 Documenation: Prepared for the 3.1.4 release

(From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 82 insertions, 1 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index f9bbddd724..1dcd5fdd03 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -1,6 +1,7 @@
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
 
 <chapter id='ref-classes'>
 <title>Classes</title>
@@ -1742,6 +1743,12 @@ This check was removed for YP 2.3 release
                 </note>
                 </para></listitem>
 -->
+            <listitem><para><emphasis><filename>unlisted-pkg-lics:</filename></emphasis>
+                Checks that all declared licenses applying for a package are also
+                declared on the recipe level (i.e. any license in
+                <filename>LICENSE_*</filename> should appear in
+                <link linkend='var-LICENSE'><filename>LICENSE</filename></link>).
+                </para></listitem>
             <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
                 Checks for dynamic library load paths (rpaths) in the binaries that
                 by default on a standard system are searched by the linker (e.g.
@@ -1873,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'>