diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f040c402c4..6cdf2a41ca 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -6229,73 +6229,138 @@
Building an Initial RAM Filesystem (initramfs) Image
- 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.
-
-
-
- To build an initramfs image and bundle it into the kernel, set the
- INITRAMFS_IMAGE_BUNDLE
- variable in your local.conf file, and set the
- INITRAMFS_IMAGE
- variable in your machine.conf file:
-
- INITRAMFS_IMAGE_BUNDLE = "1"
- INITRAMFS_IMAGE = "image_recipe_name"
-
- Setting the INITRAMFS_IMAGE_BUNDLE
- flag causes the initramfs created by the recipe and defined by
- INITRAMFS_IMAGE to be unpacked into the
- ${B}/usr/ directory.
- The unpacked initramfs is then passed to the kernel's
- Makefile using the
- CONFIG_INITRAMFS_SOURCE
- variable, allowing initramfs to be built in to the kernel
- normally.
+ 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).
- The preferred method is to use the
- INITRAMFS_IMAGE variable rather than the
- INITRAMFS_TASK variable.
- Setting INITRAMFS_TASK is supported for
- backward compatibility.
- However, use of this variable has circular dependency
- problems.
- See the
- INITRAMFS_IMAGE_BUNDLE
- variable for additional information on these dependency
- problems.
+ 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.
- The recipe that INITRAMFS_IMAGE
- points to must produce a .cpio.gz,
- .cpio.tar, .cpio.lz4,
- .cpio.lzma, or
- .cpio.xz file.
- You can ensure you produce one of these .cpio.*
- files by setting the
- INITRAMFS_FSTYPES
- variable in your configuration file to one or more of the above
- file types.
-
- If you add items to the initramfs image by way of its recipe,
- you should use
- PACKAGE_INSTALL
- rather than
- IMAGE_INSTALL.
- PACKAGE_INSTALL 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
- image
- or
- core-image
- classes.
-
+ Follow these steps to create an initramfs image:
+
+
+ Create the initramfs Image Recipe:
+ You can reference the
+ core-image-minimal-initramfs.bb
+ recipe found in the meta/recipes-core
+ directory of the
+ Source Directory
+ as an example from which to work.
+
+
+ Decide if You Need to Bundle the initramfs Image
+ Into the Kernel Image:
+ If you want the initramfs image that is built to be
+ bundled in with the kernel image, set the
+ INITRAMFS_IMAGE_BUNDLE
+ variable to "1" in your local.conf
+ configuration file and set the
+ INITRAMFS_IMAGE
+ variable in the recipe that builds the kernel image.
+ Tip
+ 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.
+
+ Setting the INITRAMFS_IMAGE_BUNDLE
+ flag causes the initramfs image to be unpacked
+ into the ${B}/usr/ directory.
+ The unpacked initramfs image is then passed to the kernel's
+ Makefile using the
+ CONFIG_INITRAMFS_SOURCE
+ variable, allowing the initramfs image to be built into
+ the kernel normally.
+
+ If you choose to not bundle the initramfs image with
+ the kernel image, you are essentially using an
+ Initial RAM Disk (initrd).
+ Creating an initrd is handled primarily through the
+ INITRD_IMAGE,
+ INITRD_LIVE, and
+ INITRD_IMAGE_LIVE variables.
+ For more information, see the
+ image-live.bbclass
+ file.
+
+
+
+
+ Optionally Add Items to the initramfs Image
+ Through the initramfs Image Recipe:
+ If you add items to the initramfs image by way of its
+ recipe, you should use
+ PACKAGE_INSTALL
+ rather than
+ IMAGE_INSTALL.
+ PACKAGE_INSTALL 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
+ image
+ or
+ core-image
+ classes.
+
+
+ Build the Kernel Image and the initramfs
+ Image:
+ 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
+ INITRAMFS_IMAGE_BUNDLE
+ variable described earlier.
+
+