From 1e51b7173aab728386b8ea1c78f17a53d065b36d Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 29 Dec 2016 10:26:15 -0800 Subject: 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 73 ++++++++++++++++++++++ documentation/ref-manual/ref-classes.xml | 21 +++++-- documentation/ref-manual/ref-variables.xml | 50 ++++++++++----- 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 @@ +
+ 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. -- cgit 1.2.3-korg