summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-16 14:40:54 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:35 +0100
commit16e730e638b9261036fea382cddf045f445cd365 (patch)
treefd3896893d913e570dbcc2da32f0ddd386dba962 /documentation/dev-manual
parent5c5a8e3d348adb979be10baca0d814cf0dfb8cb8 (diff)
downloadpoky-16e730e638b9261036fea382cddf045f445cd365.tar.gz
dev-manual: Moved "Building an Initial RAM Filesystem (initramfs) Image"
This section now belongs under the parent "building" section in the common tasks chapter. (From yocto-docs rev: dad6029b9b45fd6ec564894ba101991fd8a2162e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml244
1 files changed, 105 insertions, 139 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 14e30de039..63b758a569 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5420,6 +5420,108 @@
5420 </itemizedlist> 5420 </itemizedlist>
5421 </para> 5421 </para>
5422 </section> 5422 </section>
5423
5424 <section id='building-an-initramfs-image'>
5425 <title>Building an Initial RAM Filesystem (initramfs) Image</title>
5426
5427 <para>
5428 An initial RAM filesystem (initramfs) image provides a temporary
5429 root filesystem used for early system initialization (e.g.
5430 loading of modules needed to locate and mount the "real" root
5431 filesystem).
5432 <note>
5433 The initramfs image is the successor of initial RAM disk
5434 (initrd).
5435 It is a "copy in and out" (cpio) archive of the initial
5436 filesystem that gets loaded into memory during the Linux
5437 startup process.
5438 Because Linux uses the contents of the archive during
5439 initialization, the initramfs image needs to contain all of the
5440 device drivers and tools needed to mount the final root
5441 filesystem.
5442 </note>
5443 </para>
5444
5445 <para>
5446 Follow these steps to create an initramfs image:
5447 <orderedlist>
5448 <listitem><para>
5449 <emphasis>Create the initramfs Image Recipe:</emphasis>
5450 You can reference the
5451 <filename>core-image-minimal-initramfs.bb</filename>
5452 recipe found in the <filename>meta/recipes-core</filename>
5453 directory of the
5454 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
5455 as an example from which to work.
5456 </para></listitem>
5457 <listitem><para>
5458 <emphasis>Decide if You Need to Bundle the initramfs Image
5459 Into the Kernel Image:</emphasis>
5460 If you want the initramfs image that is built to be
5461 bundled in with the kernel image, set the
5462 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
5463 variable to "1" in your <filename>local.conf</filename>
5464 configuration file and set the
5465 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
5466 variable in the recipe that builds the kernel image.
5467 <note><title>Tip</title>
5468 It is recommended that you do bundle the initramfs
5469 image with the kernel image to avoid circular
5470 dependencies between the kernel recipe and the
5471 initramfs recipe should the initramfs image
5472 include kernel modules.
5473 </note>
5474 Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
5475 flag causes the initramfs image to be unpacked
5476 into the <filename>${B}/usr/</filename> directory.
5477 The unpacked initramfs image is then passed to the kernel's
5478 <filename>Makefile</filename> using the
5479 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
5480 variable, allowing the initramfs image to be built into
5481 the kernel normally.
5482 <note>
5483 If you choose to not bundle the initramfs image with
5484 the kernel image, you are essentially using an
5485 <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
5486 Creating an initrd is handled primarily through the
5487 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
5488 <filename>INITRD_LIVE</filename>, and
5489 <filename>INITRD_IMAGE_LIVE</filename> variables.
5490 For more information, see the
5491 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
5492 file.
5493 </note>
5494 </para></listitem>
5495 <listitem><para>
5496 <emphasis>Optionally Add Items to the initramfs Image
5497 Through the initramfs Image Recipe:</emphasis>
5498 If you add items to the initramfs image by way of its
5499 recipe, you should use
5500 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
5501 rather than
5502 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
5503 <filename>PACKAGE_INSTALL</filename> gives more direct
5504 control of what is added to the image as compared to
5505 the defaults you might not necessarily want that are
5506 set by the
5507 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
5508 or
5509 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
5510 classes.
5511 </para></listitem>
5512 <listitem><para>
5513 <emphasis>Build the Kernel Image and the initramfs
5514 Image:</emphasis>
5515 Build your kernel image using BitBake.
5516 Because the initramfs image recipe is a dependency of the
5517 kernel image, the initramfs image is built as well and
5518 bundled with the kernel image if you used the
5519 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
5520 variable described earlier.
5521 </para></listitem>
5522 </orderedlist>
5523 </para>
5524 </section>
5423 </section> 5525 </section>
5424 5526
5425 5527
@@ -5427,6 +5529,9 @@
5427 5529
5428 5530
5429 5531
5532
5533
5534
5430 <section id="platdev-working-with-libraries"> 5535 <section id="platdev-working-with-libraries">
5431 <title>Working With Libraries</title> 5536 <title>Working With Libraries</title>
5432 5537
@@ -7128,145 +7233,6 @@
7128 </section> 7233 </section>
7129 </section> 7234 </section>
7130 7235
7131 <section id='building-an-initramfs-image'>
7132 <title>Building an Initial RAM Filesystem (initramfs) Image</title>
7133
7134 <para>
7135 An initial RAM filesystem (initramfs) image provides a temporary
7136 root filesystem used for early system initialization (e.g.
7137 loading of modules needed to locate and mount the "real" root
7138 filesystem).
7139 <note>
7140 The initramfs image is the successor of initial RAM disk
7141 (initrd).
7142 It is a "copy in and out" (cpio) archive of the initial
7143 filesystem that gets loaded into memory during the Linux
7144 startup process.
7145 Because Linux uses the contents of the archive during
7146 initialization, the initramfs image needs to contain all of the
7147 device drivers and tools needed to mount the final root
7148 filesystem.
7149 </note>
7150 </para>
7151
7152 <para>
7153 Follow these steps to create an initramfs image:
7154 <orderedlist>
7155 <listitem><para>
7156 <emphasis>Create the initramfs Image Recipe:</emphasis>
7157 You can reference the
7158 <filename>core-image-minimal-initramfs.bb</filename>
7159 recipe found in the <filename>meta/recipes-core</filename>
7160 directory of the
7161 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
7162 as an example from which to work.
7163 </para></listitem>
7164 <listitem><para>
7165 <emphasis>Decide if You Need to Bundle the initramfs Image
7166 Into the Kernel Image:</emphasis>
7167 If you want the initramfs image that is built to be
7168 bundled in with the kernel image, set the
7169 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
7170 variable to "1" in your <filename>local.conf</filename>
7171 configuration file and set the
7172 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
7173 variable in the recipe that builds the kernel image.
7174 <note><title>Tip</title>
7175 It is recommended that you do bundle the initramfs
7176 image with the kernel image to avoid circular
7177 dependencies between the kernel recipe and the
7178 initramfs recipe should the initramfs image
7179 include kernel modules.
7180 </note>
7181 Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
7182 flag causes the initramfs image to be unpacked
7183 into the <filename>${B}/usr/</filename> directory.
7184 The unpacked initramfs image is then passed to the kernel's
7185 <filename>Makefile</filename> using the
7186 <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
7187 variable, allowing the initramfs image to be built into
7188 the kernel normally.
7189 <note>
7190 If you choose to not bundle the initramfs image with
7191 the kernel image, you are essentially using an
7192 <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
7193 Creating an initrd is handled primarily through the
7194 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
7195 <filename>INITRD_LIVE</filename>, and
7196 <filename>INITRD_IMAGE_LIVE</filename> variables.
7197 For more information, see the
7198 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
7199 file.
7200 </note>
7201 </para></listitem>
7202<!--
7203Some notes from Cal:
7204
7205 A non-bundled initramfs is essentially an initrd, which I am discovering
7206 to be rather confusingly supported in OE at the moment.
7207
7208 Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
7209 variables. INITRD_IMAGE* is the primary image target, which gets added to
7210 INITRD*, which is a list of cpio filesystems. You can add more cpio
7211 filesystems to the INITRD variable to add more to the initrd. For
7212 instance, meta-intel adds intel-microcode via the following:
7213
7214 INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
7215
7216 If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
7217
7218 INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
7219
7220 Unfortunately you need the full path, and its up to you to sort out
7221 dependencies as well. For instance, we have the following:
7222
7223 MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
7224
7225 which resolves to:
7226
7227 MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
7228
7229 However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
7230 another beast entirely, with current wic kickstart files not supporting
7231 initrds, and only partial support in the source plugins. That being said,
7232 I know the generic bootfs work Ed is working on will help immensely in this
7233 aspect. He or Saul can provide more details here.
7234
7235 Anyhow, its rather fractured and confusing and could probably use a
7236 rework honestly. I don't know how feasible it is to document all the
7237 details and corner cases of this area.
7238-->
7239 <listitem><para>
7240 <emphasis>Optionally Add Items to the initramfs Image
7241 Through the initramfs Image Recipe:</emphasis>
7242 If you add items to the initramfs image by way of its
7243 recipe, you should use
7244 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
7245 rather than
7246 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
7247 <filename>PACKAGE_INSTALL</filename> gives more direct
7248 control of what is added to the image as compared to
7249 the defaults you might not necessarily want that are
7250 set by the
7251 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
7252 or
7253 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
7254 classes.
7255 </para></listitem>
7256 <listitem><para>
7257 <emphasis>Build the Kernel Image and the initramfs
7258 Image:</emphasis>
7259 Build your kernel image using BitBake.
7260 Because the initramfs image recipe is a dependency of the
7261 kernel image, the initramfs image is built as well and
7262 bundled with the kernel image if you used the
7263 <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
7264 variable described earlier.
7265 </para></listitem>
7266 </orderedlist>
7267 </para>
7268 </section>
7269
7270 <section id='flashing-images-using-bmaptool'> 7236 <section id='flashing-images-using-bmaptool'>
7271 <title>Flashing Images Using <filename>bmaptool</filename></title> 7237 <title>Flashing Images Using <filename>bmaptool</filename></title>
7272 7238