diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-12-29 10:26:15 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-01-11 17:23:10 +0000 |
commit | 1e51b7173aab728386b8ea1c78f17a53d065b36d (patch) | |
tree | b073bb8219a8aec25f85c9009ac25fe9accb20ac | |
parent | 5068f2c960877f21aee76eb26322b7977acc0fc3 (diff) | |
download | openembedded-core-contrib-1e51b7173aab728386b8ea1c78f17a53d065b36d.tar.gz |
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 <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 73 | ||||
-rw-r--r-- | documentation/ref-manual/ref-classes.xml | 21 | ||||
-rw-r--r-- | 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 @@ </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> 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 @@ </para> <para> - This means that each built kernel module is packaged separately and inter-module - dependencies are created by parsing the <filename>modinfo</filename> output. - If all modules are required, then installing the <filename>kernel-modules</filename> - package installs all packages with modules and various other kernel packages - such as <filename>kernel-vmlinux</filename>. + This means that each built kernel module is packaged separately and + inter-module dependencies are created by parsing the + <filename>modinfo</filename> output. + If all modules are required, then installing the + <filename>kernel-modules</filename> package installs all packages with + modules and various other kernel packages such as + <filename>kernel-vmlinux</filename>. + </para> + + <para> + The <filename>kernel</filename> 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 + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. </para> <para> 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 @@ <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm> <info> - 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." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - 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. </para> + + <para> + For information on creating an initramfs, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. + </para> </glossdef> </glossentry> @@ -5405,9 +5412,12 @@ variable to specify packages for installation. Instead, use the <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> - variable, which allows the initial RAM disk (initramfs) - recipe to use a fixed set of packages and not be - affected by <filename>IMAGE_INSTALL</filename>. + variable, which allows the initial RAM filesystem + (initramfs) recipe to use a fixed set of packages and + not be affected by <filename>IMAGE_INSTALL</filename>. + For information on creating an initramfs, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. </note> </para> @@ -6133,13 +6143,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm> <info> - 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." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> variable. @@ -6152,7 +6162,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, is "cpio.gz". The Linux kernel's initramfs mechanism, as opposed to the - initial RAM disk + initial RAM filesystem <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink> 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" <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> <info> - 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." </info> <glossdef> <para role="glossdeffirst"> @@ -6170,7 +6180,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Specifies the <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> 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" </para> <para> - Finally, for more information you can also see the + For more information, you can also see the <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link> variable, which allows the generated image to be bundled inside the kernel image. + Additionally, for information on creating an initramfs, see + the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. </para> </glossdef> </glossentry> <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> <info> - 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)." </info> <glossdef> <para role="glossdeffirst"> @@ -6231,8 +6245,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" is run through an extra pass (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>) 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 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link> kernel feature. @@ -6279,6 +6293,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" See the <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> file for additional information. + Also, for information on creating an initramfs, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. </para> </glossdef> </glossentry> @@ -9105,9 +9122,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" the <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link> image. - When working with an initial RAM disk (initramfs) + When working with an initial RAM filesystem (initramfs) image, use the <filename>PACKAGE_INSTALL</filename> variable. + For information on creating an initramfs, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" + section in the Yocto Project Development Manual. </para> </glossdef> </glossentry> |