sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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:
Scott Rifenbark 2016-12-29 10:26:15 -08:00 committed by Richard Purdie
parent d229fded3e
commit ecaab75be6
3 changed files with 124 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -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>

21
documentation/ref-manual/ref-classes.xml
View File

@ -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>

50
documentation/ref-manual/ref-variables.xml
View File

@ -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>