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: 289dfbd5d24241e42446a043104eecd6dca76f13)

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

1 files changed, 73 insertions, 0 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>