summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml132
1 files changed, 132 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 9063b70b3f..c9dc5550c8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5438,6 +5438,138 @@
5438 artifact is manually specified. 5438 artifact is manually specified.
5439 </para> 5439 </para>
5440 </section> 5440 </section>
5441
5442 <section id='using-wic-to-manipulate-an-image'>
5443 <title>Using Wic to Manipulate an Image</title>
5444
5445 <para>
5446 Wic image manipulation allows you to shorten turnaround
5447 time during image development.
5448 For example, you can use Wic to delete the kernel partition
5449 of a Wic image and then insert a newly built kernel.
5450 This saves you time from having to rebuild the entire image
5451 each time you modify the kernel.
5452 <note>
5453 In order to use Wic to manipulate a Wic image as in
5454 this example, your development machine must have the
5455 <filename>mtools</filename> package installed.
5456 </note>
5457 </para>
5458
5459 <para>
5460 The following example examines the contents of the Wic
5461 image, deletes the existing kernel, and then inserts a
5462 new kernel:
5463 <orderedlist>
5464 <listitem><para>
5465 <emphasis>List the Partitions:</emphasis>
5466 Use the <filename>wic ls</filename> command to list
5467 all the partitions in the Wic image:
5468 <literallayout class='monospaced'>
5469 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic
5470 Num Start End Size Fstype
5471 1 1048576 25041919 23993344 fat16
5472 2 25165824 72157183 46991360 ext4
5473 </literallayout>
5474 The previous output shows two partitions in the
5475 <filename>core-image-minimal-qemux86.wic</filename>
5476 image.
5477 </para></listitem>
5478 <listitem><para>
5479 <emphasis>Examine a Particular Partition:</emphasis>
5480 Use the <filename>wic ls</filename> command again
5481 but in a different form to examine a particular
5482 partition.
5483 <note>
5484 You can get command usage on any Wic command
5485 using the following form:
5486 <literallayout class='monospaced'>
5487 $ wic help <replaceable>command</replaceable>
5488 </literallayout>
5489 For example, the following command shows you
5490 the various ways to use the
5491 <filename>wic ls</filename> command:
5492 <literallayout class='monospaced'>
5493 $ wic help ls
5494 </literallayout>
5495 </note>
5496 The following command shows what is in Partition
5497 one:
5498 <literallayout class='monospaced'>
5499 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1
5500 Volume in drive : is boot
5501 Volume Serial Number is E894-1809
5502 Directory for ::/
5503
5504 libcom32 c32 186500 2017-10-09 16:06
5505 libutil c32 24148 2017-10-09 16:06
5506 syslinux cfg 220 2017-10-09 16:06
5507 vesamenu c32 27104 2017-10-09 16:06
5508 vmlinuz 6904608 2017-10-09 16:06
5509 5 files 7 142 580 bytes
5510 16 582 656 bytes free
5511 </literallayout>
5512 The previous output shows five files, with the
5513 <filename>vmlinuz</filename> being the kernel.
5514 <note>
5515 If you see the following error, you need to
5516 update or create a
5517 <filename>~/.mtoolsrc</filename> with the
5518 suggested statement and then run the Wic
5519 command again:
5520 <literallayout class='monospaced'>
5521 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0
5522 output: Total number of sectors (47824) not a multiple of sectors per track (32)!
5523 Add mtools_skip_check=1 to your .mtoolsrc file to skip this test
5524 </literallayout>
5525 </note>
5526 </para></listitem>
5527 <listitem><para>
5528 <emphasis>Remove the Old Kernel:</emphasis>
5529 Use the <filename>wic rm</filename> command to
5530 remove the <filename>vmlinuz</filename> file
5531 (kernel):
5532 <literallayout class='monospaced'>
5533 $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
5534 </literallayout>
5535 </para></listitem>
5536 <listitem><para>
5537 <emphasis>Add In the New Kernel:</emphasis>
5538 Use the <filename>wic cp</filename> command to
5539 add the updated kernel to the Wic image.
5540 Depending on how you built your kernel, it could
5541 be in different places.
5542 If you used <filename>devtool</filename> and
5543 an SDK to build your kernel, it resides in the
5544 <filename>tmp/work</filename> directory of the
5545 extensible SDK.
5546 If you used <filename>make</filename> to build the
5547 kernel, the kernel will be in the
5548 <filename>workspace/sources</filename> area.
5549 </para>
5550
5551 <para>The following example assumes
5552 <filename>devtool</filename> was used to build
5553 the kernel:
5554 <literallayout class='monospaced'>
5555 cp ~/poky_sdk/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+git999-r0/linux-yocto-4.12.12+git999/arch/x86/boot/bzImage \
5556 ~/poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz
5557 </literallayout>
5558 Once the new kernel is added back into the image,
5559 you can use the <filename>dd</filename>
5560 command or
5561 <link linkend='flashing-images-using-bmaptool'><filename>bmaptool</filename></link>
5562 to flash your wic image onto an SD card
5563 or USB stick and test your target.
5564 <note>
5565 Using <filename>bmaptool</filename> is
5566 generally 10 to 20 times faster than using
5567 <filename>dd</filename>.
5568 </note>
5569 </para></listitem>
5570 </orderedlist>
5571 </para>
5572 </section>
5441 </section> 5573 </section>
5442 </section> 5574 </section>
5443 5575