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: 289dfbd5d24241e42446a043104eecd6dca76f13) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
d229fded3e
commit
ecaab75be6
|
@ -5475,6 +5475,79 @@
|
||||||
</section>
|
</section>
|
||||||
</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'>
|
<section id='configuring-the-kernel'>
|
||||||
<title>Configuring the Kernel</title>
|
<title>Configuring the Kernel</title>
|
||||||
|
|
||||||
|
|
|
@ -1873,11 +1873,22 @@
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This means that each built kernel module is packaged separately and inter-module
|
This means that each built kernel module is packaged separately and
|
||||||
dependencies are created by parsing the <filename>modinfo</filename> output.
|
inter-module dependencies are created by parsing the
|
||||||
If all modules are required, then installing the <filename>kernel-modules</filename>
|
<filename>modinfo</filename> output.
|
||||||
package installs all packages with modules and various other kernel packages
|
If all modules are required, then installing the
|
||||||
such as <filename>kernel-vmlinux</filename>.
|
<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>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
|
|
@ -2273,12 +2273,13 @@
|
||||||
|
|
||||||
<glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
|
<glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
|
||||||
<info>
|
<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>
|
</info>
|
||||||
<glossdef>
|
<glossdef>
|
||||||
<para role="glossdeffirst">
|
<para role="glossdeffirst">
|
||||||
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
|
<!-- <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
|
The OpenEmbedded build system receives and uses
|
||||||
this kernel Kconfig variable as an environment variable.
|
this kernel Kconfig variable as an environment variable.
|
||||||
By default, the variable is set to null ("").
|
By default, the variable is set to null ("").
|
||||||
|
@ -2304,6 +2305,12 @@
|
||||||
If you specify multiple directories and files, the
|
If you specify multiple directories and files, the
|
||||||
initramfs image will be the aggregate of all of them.
|
initramfs image will be the aggregate of all of them.
|
||||||
</para>
|
</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>
|
</glossdef>
|
||||||
</glossentry>
|
</glossentry>
|
||||||
|
|
||||||
|
@ -5405,9 +5412,12 @@
|
||||||
variable to specify packages for installation.
|
variable to specify packages for installation.
|
||||||
Instead, use the
|
Instead, use the
|
||||||
<link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
|
<link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
|
||||||
variable, which allows the initial RAM disk (initramfs)
|
variable, which allows the initial RAM filesystem
|
||||||
recipe to use a fixed set of packages and not be
|
(initramfs) recipe to use a fixed set of packages and
|
||||||
affected by <filename>IMAGE_INSTALL</filename>.
|
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>
|
</note>
|
||||||
</para>
|
</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>
|
<glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
|
||||||
<info>
|
<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>
|
</info>
|
||||||
<glossdef>
|
<glossdef>
|
||||||
<para role="glossdeffirst">
|
<para role="glossdeffirst">
|
||||||
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
|
<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
|
||||||
Defines the format for the output image of an initial
|
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
|
Supported formats are the same as those supported by the
|
||||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
|
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
|
||||||
variable.
|
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>,
|
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
|
||||||
is "cpio.gz".
|
is "cpio.gz".
|
||||||
The Linux kernel's initramfs mechanism, as opposed to the
|
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>
|
<ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
|
||||||
mechanism, expects an optionally compressed cpio
|
mechanism, expects an optionally compressed cpio
|
||||||
archive.
|
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>
|
<glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
|
||||||
<info>
|
<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>
|
</info>
|
||||||
<glossdef>
|
<glossdef>
|
||||||
<para role="glossdeffirst">
|
<para role="glossdeffirst">
|
||||||
|
@ -6170,7 +6180,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
||||||
Specifies the
|
Specifies the
|
||||||
<link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
|
<link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
|
||||||
name of an image recipe that is used to build an initial
|
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
|
An initramfs provides a temporary root filesystem used for
|
||||||
early system initialization (e.g. loading of modules
|
early system initialization (e.g. loading of modules
|
||||||
needed to locate and mount the "real" root filesystem).
|
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>
|
||||||
|
|
||||||
<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>
|
<link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
|
||||||
variable, which allows the generated image to be bundled
|
variable, which allows the generated image to be bundled
|
||||||
inside the kernel image.
|
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>
|
</para>
|
||||||
</glossdef>
|
</glossdef>
|
||||||
</glossentry>
|
</glossentry>
|
||||||
|
|
||||||
<glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
|
<glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
|
||||||
<info>
|
<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>
|
</info>
|
||||||
<glossdef>
|
<glossdef>
|
||||||
<para role="glossdeffirst">
|
<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
|
is run through an extra pass
|
||||||
(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
|
(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
|
||||||
during kernel compilation in order to build a single binary
|
during kernel compilation in order to build a single binary
|
||||||
that contains both the kernel image and the initial RAM disk
|
that contains both the kernel image and the initial RAM
|
||||||
(initramfs).
|
filesystem (initramfs) image.
|
||||||
This makes use of the
|
This makes use of the
|
||||||
<link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
|
<link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
|
||||||
kernel feature.
|
kernel feature.
|
||||||
|
@ -6279,6 +6293,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
||||||
See the
|
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>
|
<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.
|
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>
|
</para>
|
||||||
</glossdef>
|
</glossdef>
|
||||||
</glossentry>
|
</glossentry>
|
||||||
|
@ -9105,9 +9122,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
||||||
the
|
the
|
||||||
<link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
|
<link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
|
||||||
image.
|
image.
|
||||||
When working with an initial RAM disk (initramfs)
|
When working with an initial RAM filesystem (initramfs)
|
||||||
image, use the <filename>PACKAGE_INSTALL</filename>
|
image, use the <filename>PACKAGE_INSTALL</filename>
|
||||||
variable.
|
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>
|
</para>
|
||||||
</glossdef>
|
</glossdef>
|
||||||
</glossentry>
|
</glossentry>
|
||||||
|
|
Loading…
Reference in New Issue