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 @@
+
+ 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
+ following variables:
+
+ 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.
+
+ 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 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
+ IMAGE_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.
+
+
+
+
Configuring the Kernel
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 @@
- This means that each built kernel module is packaged separately and inter-module
- dependencies are created by parsing the modinfo output.
- If all modules are required, then installing the kernel-modules
- package installs all packages with modules and various other kernel packages
- such as kernel-vmlinux.
+ This means that each built kernel module is packaged separately and
+ inter-module dependencies are created by parsing the
+ modinfo output.
+ If all modules are required, then installing the
+ kernel-modules package installs all packages with
+ modules and various other kernel packages such as
+ kernel-vmlinux.
+
+
+
+ The kernel 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
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.
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 @@
CONFIG_INITRAMFS_SOURCE
- 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."
- 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.
+
+
+ For information on creating an initramfs, see the
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.
+
@@ -5405,9 +5412,12 @@
variable to specify packages for installation.
Instead, use the
PACKAGE_INSTALL
- variable, which allows the initial RAM disk (initramfs)
- recipe to use a fixed set of packages and not be
- affected by IMAGE_INSTALL.
+ variable, which allows the initial RAM filesystem
+ (initramfs) recipe to use a fixed set of packages and
+ not be affected by IMAGE_INSTALL.
+ For information on creating an initramfs, see the
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.
@@ -6133,13 +6143,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
INITRAMFS_FSTYPES
- 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."
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
IMAGE_FSTYPES
variable.
@@ -6152,7 +6162,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Source Directory,
is "cpio.gz".
The Linux kernel's initramfs mechanism, as opposed to the
- initial RAM disk
+ initial RAM filesystem
initrd
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"
INITRAMFS_IMAGE
- 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."
@@ -6170,7 +6180,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Specifies the
PROVIDES
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"
- Finally, for more information you can also see the
+ For more information, you can also see the
INITRAMFS_IMAGE_BUNDLE
variable, which allows the generated image to be bundled
inside the kernel image.
+ Additionally, for information on creating an initramfs, see
+ the
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.
INITRAMFS_IMAGE_BUNDLE
- 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)."
@@ -6231,8 +6245,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
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).
+ that contains both the kernel image and the initial RAM
+ filesystem (initramfs) image.
This makes use of the
CONFIG_INITRAMFS_SOURCE
kernel feature.
@@ -6279,6 +6293,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
See the
local.conf.sample.extended
file for additional information.
+ Also, for information on creating an initramfs, see the
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.
@@ -9105,9 +9122,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
the
core-image-minimal-initramfs
image.
- When working with an initial RAM disk (initramfs)
+ When working with an initial RAM filesystem (initramfs)
image, use the PACKAGE_INSTALL
variable.
+ For information on creating an initramfs, see the
+ "Building an Initial RAM Filesystem (initramfs) Image"
+ section in the Yocto Project Development Manual.