summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-12-29 10:26:15 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-01-11 17:23:10 +0000
commit1e51b7173aab728386b8ea1c78f17a53d065b36d (patch)
treeb073bb8219a8aec25f85c9009ac25fe9accb20ac
parent5068f2c960877f21aee76eb26322b7977acc0fc3 (diff)
downloadopenembedded-core-contrib-1e51b7173aab728386b8ea1c78f17a53d065b36d.tar.gz
openembedded-core-contrib-1e51b7173aab728386b8ea1c78f17a53d065b36d.tar.bz2
openembedded-core-contrib-1e51b7173aab728386b8ea1c78f17a53d065b36d.zip
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.xml73
-rw-r--r--documentation/ref-manual/ref-classes.xml21
-rw-r--r--documentation/ref-manual/ref-variables.xml50
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>