dev-manual: Moved "Building an Initial RAM Filesystem (initramfs) Image"

This section now belongs under the parent "building" section in the
common tasks chapter.

(From yocto-docs rev: dad6029b9b45fd6ec564894ba101991fd8a2162e)

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

1 files changed, 105 insertions, 139 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 14e30de039..63b758a569 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5420,6 +5420,108 @@
                 </itemizedlist>
             </para>
         </section>
+
+        <section id='building-an-initramfs-image'>
+            <title>Building an Initial RAM Filesystem (initramfs) Image</title>
+
+            <para>
+                An initial RAM filesystem (initramfs) image provides a temporary
+                root filesystem used for early system initialization (e.g.
+                loading of modules needed to locate and mount the "real" root
+                filesystem).
+                <note>
+                    The initramfs image is the successor of initial RAM disk
+                    (initrd).
+                    It is a "copy in and out" (cpio) archive of the initial
+                    filesystem that gets loaded into memory during the Linux
+                    startup process.
+                    Because Linux uses the contents of the archive during
+                    initialization, the initramfs image needs to contain all of the
+                    device drivers and tools needed to mount the final root
+                    filesystem.
+                </note>
+            </para>
+
+            <para>
+                Follow these steps to create an initramfs image:
+                <orderedlist>
+                    <listitem><para>
+                        <emphasis>Create the initramfs Image Recipe:</emphasis>
+                        You can reference the
+                        <filename>core-image-minimal-initramfs.bb</filename>
+                        recipe found in the <filename>meta/recipes-core</filename>
+                        directory of the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                        as an example from which to work.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Decide if You Need to Bundle the initramfs Image
+                        Into the Kernel Image:</emphasis>
+                        If you want the initramfs image that is built to be
+                        bundled in with the kernel image, set the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+                        variable to "1" in your <filename>local.conf</filename>
+                        configuration file and set the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+                        variable in the recipe that builds the kernel image.
+                        <note><title>Tip</title>
+                            It is recommended that you do bundle the initramfs
+                            image with the kernel image to avoid circular
+                            dependencies between the kernel recipe and the
+                            initramfs recipe should the initramfs image
+                            include kernel modules.
+                        </note>
+                        Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
+                        flag causes the initramfs image to be unpacked
+                        into the <filename>${B}/usr/</filename> directory.
+                        The unpacked initramfs image 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 the initramfs image to be built into
+                        the kernel normally.
+                        <note>
+                            If you choose to not bundle the initramfs image with
+                            the kernel image, you are essentially using an
+                            <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
+                            Creating an initrd is handled primarily through the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
+                            <filename>INITRD_LIVE</filename>, and
+                            <filename>INITRD_IMAGE_LIVE</filename> variables.
+                            For more information, see the
+                            <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
+                            file.
+                        </note>
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Optionally Add Items to the initramfs Image
+                        Through the initramfs Image Recipe:</emphasis>
+                        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.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build the Kernel Image and the initramfs
+                        Image:</emphasis>
+                        Build your kernel image using BitBake.
+                        Because the initramfs image recipe is a dependency of the
+                        kernel image, the initramfs image is built as well and
+                        bundled with the kernel image if you used the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+                        variable described earlier.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
     </section>
 
 
@@ -5427,6 +5529,9 @@
 
 
 
+
+
+
     <section id="platdev-working-with-libraries">
         <title>Working With Libraries</title>
 
@@ -7128,145 +7233,6 @@
         </section>
     </section>
 
-    <section id='building-an-initramfs-image'>
-        <title>Building an Initial RAM Filesystem (initramfs) Image</title>
-
-        <para>
-            An initial RAM filesystem (initramfs) image provides a temporary
-            root filesystem used for early system initialization (e.g.
-            loading of modules needed to locate and mount the "real" root
-            filesystem).
-            <note>
-                The initramfs image is the successor of initial RAM disk
-                (initrd).
-                It is a "copy in and out" (cpio) archive of the initial
-                filesystem that gets loaded into memory during the Linux
-                startup process.
-                Because Linux uses the contents of the archive during
-                initialization, the initramfs image needs to contain all of the
-                device drivers and tools needed to mount the final root
-                filesystem.
-            </note>
-        </para>
-
-        <para>
-            Follow these steps to create an initramfs image:
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Create the initramfs Image Recipe:</emphasis>
-                    You can reference the
-                    <filename>core-image-minimal-initramfs.bb</filename>
-                    recipe found in the <filename>meta/recipes-core</filename>
-                    directory of the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                    as an example from which to work.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Decide if You Need to Bundle the initramfs Image
-                    Into the Kernel Image:</emphasis>
-                    If you want the initramfs image that is built to be
-                    bundled in with the kernel image, set the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
-                    variable to "1" in your <filename>local.conf</filename>
-                    configuration file and set the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
-                    variable in the recipe that builds the kernel image.
-                    <note><title>Tip</title>
-                        It is recommended that you do bundle the initramfs
-                        image with the kernel image to avoid circular
-                        dependencies between the kernel recipe and the
-                        initramfs recipe should the initramfs image
-                        include kernel modules.
-                    </note>
-                    Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
-                    flag causes the initramfs image to be unpacked
-                    into the <filename>${B}/usr/</filename> directory.
-                    The unpacked initramfs image 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 the initramfs image to be built into
-                    the kernel normally.
-                    <note>
-                        If you choose to not bundle the initramfs image with
-                        the kernel image, you are essentially using an
-                        <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
-                        Creating an initrd is handled primarily through the
-                        <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
-                        <filename>INITRD_LIVE</filename>, and
-                        <filename>INITRD_IMAGE_LIVE</filename> variables.
-                        For more information, see the
-                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
-                        file.
-                    </note>
-                    </para></listitem>
-<!--
-Some notes from Cal:
-
-    A non-bundled initramfs is essentially an initrd, which I am discovering
-    to be rather confusingly supported in OE at the moment.
-
-    Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
-    variables. INITRD_IMAGE* is the primary image target, which gets added to
-    INITRD*, which is a list of cpio filesystems. You can add more cpio
-    filesystems to the INITRD variable to add more to the initrd. For
-    instance, meta-intel adds intel-microcode via the following:
-
-        INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
-
-    If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
-
-        INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
-
-    Unfortunately you need the full path, and its up to you to sort out
-    dependencies as well. For instance, we have the following:
-
-        MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
-
-    which resolves to:
-
-        MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
-
-    However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
-    another beast entirely, with current wic kickstart files not supporting
-    initrds, and only partial support in the source plugins. That being said,
-    I know the generic bootfs work Ed is working on will help immensely in this
-    aspect. He or Saul can provide more details here.
-
-    Anyhow, its rather fractured and confusing and could probably use a
-    rework honestly. I don't know how feasible it is to document all the
-    details and corner cases of this area.
--->
-                <listitem><para>
-                    <emphasis>Optionally Add Items to the initramfs Image
-                    Through the initramfs Image Recipe:</emphasis>
-                    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.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Build the Kernel Image and the initramfs
-                    Image:</emphasis>
-                    Build your kernel image using BitBake.
-                    Because the initramfs image recipe is a dependency of the
-                    kernel image, the initramfs image is built as well and
-                    bundled with the kernel image if you used the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
-                    variable described earlier.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
     <section id='flashing-images-using-bmaptool'>
         <title>Flashing Images Using <filename>bmaptool</filename></title>