mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-06-01 13:09:50 +00:00
Code Issues Projects Releases Wiki Activity

dev-manual: Updated the section on initramfs

Browse Source 
I did a rewrite of the section to get it into a procedural form.
Missing some technical information and needs a review but it is
the best that can be done at this time.  The code for initrd is
not settled.

(From yocto-docs rev: 0fdef8c5fed6ac510d1604a677e6546494b4c96b)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2017-07-07 13:38:20 -07:00
committed by Richard Purdie
parent aa1162685f
commit f49fa46e19
1 changed files with 127 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/dev-manual/dev-manual-common-tasks.xml
+127 -62
View File
@@ -6229,73 +6229,138 @@
<title>Building an Initial RAM Filesystem (initramfs) Image</title> <title>Building an Initial RAM Filesystem (initramfs) Image</title>
<para> <para>
initramfs is the successor of Initial RAM Disk (initrd). An initial RAM filesystem (initramfs) image provides a temporary
It is a "copy in and out" (cpio) archive of the initial file system root filesystem used for early system initialization (e.g.
that gets loaded into memory during the Linux startup process. loading of modules needed to locate and mount the "real" root
Because Linux uses the contents of the archive during filesystem).
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
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
variable in your <filename>local.conf</filename> file, and set the
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
variable in your <filename>machine.conf</filename> file:
<literallayout class='monospaced'>
INITRAMFS_IMAGE_BUNDLE = "1"
INITRAMFS_IMAGE = "<replaceable>image_recipe_name</replaceable>"
</literallayout>
Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
flag causes the initramfs created by the recipe and defined by
<filename>INITRAMFS_IMAGE</filename> 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> <note>
The preferred method is to use the The initramfs image is the successor of initial RAM disk
<filename>INITRAMFS_IMAGE</filename> variable rather than the (initrd).
<filename>INITRAMFS_TASK</filename> variable. It is a "copy in and out" (cpio) archive of the initial
Setting <filename>INITRAMFS_TASK</filename> is supported for filesystem that gets loaded into memory during the Linux
backward compatibility. startup process.
However, use of this variable has circular dependency Because Linux uses the contents of the archive during
problems. initialization, the initramfs image needs to contain all of the
See the device drivers and tools needed to mount the final root
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink> filesystem.
variable for additional information on these dependency
problems.
</note> </note>
</para> </para>
<para> <para>
The recipe that <filename>INITRAMFS_IMAGE</filename> Follow these steps to create an initramfs image:
points to must produce a <filename>.cpio.gz</filename>, <orderedlist>
<filename>.cpio.tar</filename>, <filename>.cpio.lz4</filename>, <listitem><para>
<filename>.cpio.lzma</filename>, or <emphasis>Create the initramfs Image Recipe:</emphasis>
<filename>.cpio.xz</filename> file. You can reference the
You can ensure you produce one of these <filename>.cpio.*</filename> <filename>core-image-minimal-initramfs.bb</filename>
files by setting the recipe found in the <filename>meta/recipes-core</filename>
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></ulink> directory of the
variable in your configuration file to one or more of the above <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
file types. as an example from which to work.
<note> </para></listitem>
If you add items to the initramfs image by way of its recipe, <listitem><para>
you should use <emphasis>Decide if You Need to Bundle the initramfs Image
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink> Into the Kernel Image:</emphasis>
rather than If you want the initramfs image that is built to be
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>. bundled in with the kernel image, set the
<filename>PACKAGE_INSTALL</filename> gives more direct control <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
of what is added to the image as compared to the defaults you variable to "1" in your <filename>local.conf</filename>
might not necessarily want that are set by the configuration file and set the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
or variable in the recipe that builds the kernel image.
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink> <note><title>Tip</title>
classes. It is recommended that you do bundle the initramfs
</note> image with the kernel image to avoid circular
dependencies between the kernel recipe and the
initramfs recipe should the initramfs image
include kernel modules.
</note>
Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
flag causes the initramfs image to be unpacked
into the <filename>${B}/usr/</filename> directory.
The unpacked initramfs image 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 the initramfs image to be built into
the kernel normally.
<note>
If you choose to not bundle the initramfs image with
the kernel image, you are essentially using an
<ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
Creating an initrd is handled primarily through the
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
<filename>INITRD_LIVE</filename>, and
<filename>INITRD_IMAGE_LIVE</filename> variables.
For more information, see the
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
file.
</note>
</para></listitem>
<!--
Some notes from Cal:
A non-bundled initramfs is essentially an initrd, which I am discovering
to be rather confusingly supported in OE at the moment.
Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
variables. INITRD_IMAGE* is the primary image target, which gets added to
INITRD*, which is a list of cpio filesystems. You can add more cpio
filesystems to the INITRD variable to add more to the initrd. For
instance, meta-intel adds intel-microcode via the following:
INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
Unfortunately you need the full path, and its up to you to sort out
dependencies as well. For instance, we have the following:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
which resolves to:
MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
another beast entirely, with current wic kickstart files not supporting
initrds, and only partial support in the source plugins. That being said,
I know the generic bootfs work Ed is working on will help immensely in this
aspect. He or Saul can provide more details here.
Anyhow, its rather fractured and confusing and could probably use a
rework honestly. I don't know how feasible it is to document all the
details and corner cases of this area.
-->
<listitem><para>
<emphasis>Optionally Add Items to the initramfs Image
Through the initramfs Image Recipe:</emphasis>
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.
</para></listitem>
<listitem><para>
<emphasis>Build the Kernel Image and the initramfs
Image:</emphasis>
Build your kernel image using BitBake.
Because the initramfs image recipe is a dependency of the
kernel image, the initramfs image is built as well and
bundled with the kernel image if you used the
<ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
variable described earlier.
</para></listitem>
</orderedlist>
</para> </para>
</section> </section>