dev-manual, ref-manual: Created new section on initramfs

Fixes [YOCTO #7096]

We did not document how to create an initramfs image to be included
with a kernel build.  Various variables sort of inferred the
knowledge.  I created a new section in the "Common Tasks" section
of the dev-manual that describes how to create an initramfs image.

Also, I updated the kernel.bbclass reference section to point back
to the new "how-to" section.

Finally, I also created a bunch of cross-reference links from various
related variables back to the new "how-to" section.

(From yocto-docs rev: a14e550494641c46ac2518632cbf251e07d459fd)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 124 insertions, 20 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 603ca1ff8e..f3f2a4b026 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5475,6 +5475,79 @@
         </section>
     </section>
 
+    <section id='building-an-initramfs-image'>
+        <title>Building an Initial RAM Filesystem (initramfs) Image</title>
+
+        <para>
+            initramfs is the successor of Initial RAM Disk (initrd).
+            It is a "copy in and out" (cpio) archive of the initial file system
+            that gets loaded into memory during the Linux startup process.
+            Because Linux uses the contents of the archive during
+            initialization, the initramfs needs to contain all of the device
+            drivers and tools needed to mount the final root filesystem.
+        </para>
+
+        <para>
+            To build an initramfs image and bundle it into the kernel, set the
+            following variables:
+            <literallayout class='monospaced'>
+     INITRAMFS_IMAGE_BUNDLE = "1"
+     INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
+            </literallayout>
+            Setting the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+            flag causes the initramfs created by the recipe
+            and defined by
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+            to be unpacked into the <filename>${B}/usr/</filename> directory.
+            The unpacked initramfs is then passed to the kernel's
+            <filename>Makefile</filename> using the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
+            variable, allowing initramfs to be built in to the kernel
+            normally.
+            <note>
+                The preferred method is to use the
+                <filename>INITRAMFS_IMAGE</filename> variable rather than the
+                <filename>INITRAMFS_TASK</filename> variable.
+                Setting <filename>INITRAMFS_TASK</filename> is supported for
+                backward compatibility.
+                However, use of this variable has circular dependency
+                problems.
+                See the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+                variable for additional information on these dependency
+                problems.
+            </note>
+        </para>
+
+        <para>
+            The recipe that <filename>INITRAMFS_IMAGE</filename>
+            points to must produce a <filename>.cpio.gz</filename>,
+            <filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>,
+            <filename>.cpio.lzma</filename>, or
+            <filename>.cpio.xz</filename> file.
+            You can ensure you produce one of these <filename>.cpio.*</filename>
+            files by setting the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
+            variable in your configuration file to one or more of the above
+            file types.
+            <note>
+                If you add items to the initramfs image by way of its recipe,
+                you should use
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
+                rather than
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
+                <filename>PACKAGE_INSTALL</filename> gives more direct control
+                of what is added to the image as compared to the defaults you
+                might not necessarily want that are set by the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
+                classes.
+            </note>
+        </para>
+    </section>
+
     <section id='configuring-the-kernel'>
         <title>Configuring the Kernel</title>
 
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 2344a0406a..f7b1126d7c 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -1873,11 +1873,22 @@
     </para>
 
     <para>
-        This means that each built kernel module is packaged separately and inter-module
-        dependencies are created by parsing the <filename>modinfo</filename> output.
-        If all modules are required, then installing the <filename>kernel-modules</filename>
-        package installs all packages with modules and various other kernel packages
-        such as <filename>kernel-vmlinux</filename>.
+        This means that each built kernel module is packaged separately and
+        inter-module dependencies are created by parsing the
+        <filename>modinfo</filename> output.
+        If all modules are required, then installing the
+        <filename>kernel-modules</filename> package installs all packages with
+        modules and various other kernel packages such as
+        <filename>kernel-vmlinux</filename>.
+    </para>
+
+    <para>
+        The <filename>kernel</filename> class contains logic that allows
+        you to embed an initial RAM filesystem (initramfs) image when
+        you build the kernel image.
+        For information on how to build an initramfs, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+        section in the Yocto Project Development Manual.
     </para>
 
     <para>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 0f6535cea1..a696ee4e66 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2273,12 +2273,13 @@
 
         <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
             <info>
-                CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM disk (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."
+                CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM filesystem (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    Identifies the initial RAM disk (initramfs) source files.
+                    Identifies the initial RAM filesystem (initramfs) source
+                    files.
                     The OpenEmbedded build system receives and uses
                     this kernel Kconfig variable as an environment variable.
                     By default, the variable is set to null ("").
@@ -2304,6 +2305,12 @@
                     If you specify multiple directories and files, the
                     initramfs image will be the aggregate of all of them.
                 </para>
+
+                <para>
+                    For information on creating an initramfs, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
             </glossdef>
         </glossentry>
 
@@ -5405,9 +5412,12 @@
                         variable to specify packages for installation.
                         Instead, use the
                         <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
-                        variable, which allows the initial RAM disk (initramfs)
-                        recipe to use a fixed set of packages and not be
-                        affected by <filename>IMAGE_INSTALL</filename>.
+                        variable, which allows the initial RAM filesystem
+                        (initramfs) recipe to use a fixed set of packages and
+                        not be affected by <filename>IMAGE_INSTALL</filename>.
+                        For information on creating an initramfs, see the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+                        section in the Yocto Project Development Manual.
                     </note>
                 </para>
 
@@ -6133,13 +6143,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
 
         <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
             <info>
-                INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM disk (initramfs), which is used during boot."
+                INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
                     Defines the format for the output image of an initial
-                    RAM disk (initramfs), which is used during boot.
+                    RAM filesystem (initramfs), which is used during boot.
                     Supported formats are the same as those supported by the
                     <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
                     variable.
@@ -6152,7 +6162,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
                     is "cpio.gz".
                     The Linux kernel's initramfs mechanism, as opposed to the
-                    initial RAM disk
+                    initial RAM filesystem
                     <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
                     mechanism, expects an optionally compressed cpio
                     archive.
@@ -6162,7 +6172,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
 
         <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
             <info>
-                INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM disk (initramfs) image."
+                INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
@@ -6170,7 +6180,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     Specifies the
                     <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
                     name of an image recipe that is used to build an initial
-                    RAM disk (initramfs) image.
+                    RAM filesystem (initramfs) image.
                     An initramfs provides a temporary root filesystem used for
                     early system initialization (e.g. loading of modules
                     needed to locate and mount the "real" root filesystem).
@@ -6211,17 +6221,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    Finally, for more information you can also see the
+                    For more information, you can also see the
                     <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
                     variable, which allows the generated image to be bundled
                     inside the kernel image.
+                    Additionally, for information on creating an initramfs, see
+                    the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+                    section in the Yocto Project Development Manual.
                 </para>
             </glossdef>
         </glossentry>
 
         <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
             <info>
-                INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)."
+                INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM filesystem (initramfs)."
             </info>
             <glossdef>
                 <para role="glossdeffirst">
@@ -6231,8 +6245,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     is run through an extra pass
                     (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
                     during kernel compilation in order to build a single binary
-                    that contains both the kernel image and the initial RAM disk
-                    (initramfs).
+                    that contains both the kernel image and the initial RAM
+                    filesystem (initramfs) image.
                     This makes use of the
                     <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
                     kernel feature.
@@ -6279,6 +6293,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     See the
                     <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
                     file for additional information.
+                    Also, for information on creating an initramfs, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+                    section in the Yocto Project Development Manual.
                 </para>
             </glossdef>
         </glossentry>
@@ -9105,9 +9122,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     the
                     <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
                     image.
-                    When working with an initial RAM disk (initramfs)
+                    When working with an initial RAM filesystem (initramfs)
                     image, use the <filename>PACKAGE_INSTALL</filename>
                     variable.
+                    For information on creating an initramfs, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+                    section in the Yocto Project Development Manual.
                 </para>
             </glossdef>
         </glossentry>