1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Creating Partitioned Images Using Wic 4************************************* 5 6Creating an image for a particular hardware target using the 7OpenEmbedded build system does not necessarily mean you can boot that 8image as is on your device. Physical devices accept and boot images in 9various ways depending on the specifics of the device. Usually, 10information about the hardware can tell you what image format the device 11requires. Should your device require multiple partitions on an SD card, 12flash, or an HDD, you can use the OpenEmbedded Image Creator, Wic, to 13create the properly partitioned image. 14 15The ``wic`` command generates partitioned images from existing 16OpenEmbedded build artifacts. Image generation is driven by partitioning 17commands contained in an OpenEmbedded kickstart file (``.wks``) 18specified either directly on the command line or as one of a selection 19of canned kickstart files as shown with the ``wic list images`` command 20in the 21":ref:`dev-manual/wic:generate an image using an existing kickstart file`" 22section. When you apply the command to a given set of build artifacts, the 23result is an image or set of images that can be directly written onto media and 24used on a particular system. 25 26.. note:: 27 28 For a kickstart file reference, see the 29 ":ref:`ref-manual/kickstart:openembedded kickstart (\`\`.wks\`\`) reference`" 30 Chapter in the Yocto Project Reference Manual. 31 32The ``wic`` command and the infrastructure it is based on is by 33definition incomplete. The purpose of the command is to allow the 34generation of customized images, and as such, was designed to be 35completely extensible through a plugin interface. See the 36":ref:`dev-manual/wic:using the wic plugin interface`" section 37for information on these plugins. 38 39This section provides some background information on Wic, describes what 40you need to have in place to run the tool, provides instruction on how 41to use the Wic utility, provides information on using the Wic plugins 42interface, and provides several examples that show how to use Wic. 43 44Background 45========== 46 47This section provides some background on the Wic utility. While none of 48this information is required to use Wic, you might find it interesting. 49 50- The name "Wic" is derived from OpenEmbedded Image Creator (oeic). The 51 "oe" diphthong in "oeic" was promoted to the letter "w", because 52 "oeic" is both difficult to remember and to pronounce. 53 54- Wic is loosely based on the Meego Image Creator (``mic``) framework. 55 The Wic implementation has been heavily modified to make direct use 56 of OpenEmbedded build artifacts instead of package installation and 57 configuration, which are already incorporated within the OpenEmbedded 58 artifacts. 59 60- Wic is a completely independent standalone utility that initially 61 provides easier-to-use and more flexible replacements for an existing 62 functionality in OE-Core's :ref:`ref-classes-image-live` 63 class. The difference between Wic and those examples is that with Wic 64 the functionality of those scripts is implemented by a 65 general-purpose partitioning language, which is based on Redhat 66 kickstart syntax. 67 68Requirements 69============ 70 71In order to use the Wic utility with the OpenEmbedded Build system, your 72system needs to meet the following requirements: 73 74- The Linux distribution on your development host must support the 75 Yocto Project. See the ":ref:`system-requirements-supported-distros`" 76 section in the Yocto Project Reference Manual for the list of 77 distributions that support the Yocto Project. 78 79- The standard system utilities, such as ``cp``, must be installed on 80 your development host system. 81 82- You must have sourced the build environment setup script (i.e. 83 :ref:`structure-core-script`) found in the :term:`Build Directory`. 84 85- You need to have the build artifacts already available, which 86 typically means that you must have already created an image using the 87 OpenEmbedded build system (e.g. ``core-image-minimal``). While it 88 might seem redundant to generate an image in order to create an image 89 using Wic, the current version of Wic requires the artifacts in the 90 form generated by the OpenEmbedded build system. 91 92- You must build several native tools, which are built to run on the 93 build system:: 94 95 $ bitbake wic-tools 96 97- Include "wic" as part of the 98 :term:`IMAGE_FSTYPES` 99 variable. 100 101- Include the name of the :ref:`wic kickstart file <openembedded-kickstart-wks-reference>` 102 as part of the :term:`WKS_FILE` variable. If multiple candidate files can 103 be provided by different layers, specify all the possible names through the 104 :term:`WKS_FILES` variable instead. 105 106Getting Help 107============ 108 109You can get general help for the ``wic`` command by entering the ``wic`` 110command by itself or by entering the command with a help argument as 111follows:: 112 113 $ wic -h 114 $ wic --help 115 $ wic help 116 117Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, 118``list``, ``ls``, ``rm``, and ``write``. You can get help for all these 119commands except "help" by using the following form:: 120 121 $ wic help command 122 123For example, the following command returns help for the ``write`` 124command:: 125 126 $ wic help write 127 128Wic supports help for three topics: ``overview``, ``plugins``, and 129``kickstart``. You can get help for any topic using the following form:: 130 131 $ wic help topic 132 133For example, the following returns overview help for Wic:: 134 135 $ wic help overview 136 137There is one additional level of help for Wic. You can get help on 138individual images through the ``list`` command. You can use the ``list`` 139command to return the available Wic images as follows:: 140 141 $ wic list images 142 genericx86 Create an EFI disk image for genericx86* 143 beaglebone-yocto Create SD card image for Beaglebone 144 qemuriscv Create qcow2 image for RISC-V QEMU machines 145 mkefidisk Create an EFI disk image 146 qemuloongarch Create qcow2 image for LoongArch QEMU machines 147 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin 148 directdisk Create a 'pcbios' direct disk image 149 efi-bootdisk 150 mkhybridiso Create a hybrid ISO image 151 directdisk-gpt Create a 'pcbios' direct disk image 152 systemd-bootdisk Create an EFI disk image with systemd-boot 153 sdimage-bootpart Create SD card image with a boot partition 154 qemux86-directdisk Create a qemu machine 'pcbios' direct disk image 155 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config 156 157Once you know the list of available 158Wic images, you can use ``help`` with the command to get help on a 159particular image. For example, the following command returns help on the 160"beaglebone-yocto" image:: 161 162 $ wic list beaglebone-yocto help 163 164 Creates a partitioned SD card image for Beaglebone. 165 Boot files are located in the first vfat partition. 166 167Operational Modes 168================= 169 170You can use Wic in two different modes, depending on how much control 171you need for specifying the OpenEmbedded build artifacts that are used 172for creating the image: Raw and Cooked: 173 174- *Raw Mode:* You explicitly specify build artifacts through Wic 175 command-line arguments. 176 177- *Cooked Mode:* The current 178 :term:`MACHINE` setting and image 179 name are used to automatically locate and provide the build 180 artifacts. You just supply a kickstart file and the name of the image 181 from which to use artifacts. 182 183Regardless of the mode you use, you need to have the build artifacts 184ready and available. 185 186Raw Mode 187-------- 188 189Running Wic in raw mode allows you to specify all the partitions through 190the ``wic`` command line. The primary use for raw mode is if you have 191built your kernel outside of the Yocto Project :term:`Build Directory`. 192In other words, you can point to arbitrary kernel, root filesystem locations, 193and so forth. Contrast this behavior with cooked mode where Wic looks in the 194:term:`Build Directory` (e.g. ``tmp/deploy/images/``\ machine). 195 196The general form of the ``wic`` command in raw mode is:: 197 198 $ wic create wks_file options ... 199 200 Where: 201 202 wks_file: 203 An OpenEmbedded kickstart file. You can provide 204 your own custom file or use a file from a set of 205 existing files as described by further options. 206 207 optional arguments: 208 -h, --help show this help message and exit 209 -o OUTDIR, --outdir OUTDIR 210 name of directory to create image in 211 -e IMAGE_NAME, --image-name IMAGE_NAME 212 name of the image to use the artifacts from e.g. core- 213 image-sato 214 -r ROOTFS_DIR, --rootfs-dir ROOTFS_DIR 215 path to the /rootfs dir to use as the .wks rootfs 216 source 217 -b BOOTIMG_DIR, --bootimg-dir BOOTIMG_DIR 218 path to the dir containing the boot artifacts (e.g. 219 /EFI or /syslinux dirs) to use as the .wks bootimg 220 source 221 -k KERNEL_DIR, --kernel-dir KERNEL_DIR 222 path to the dir containing the kernel to use in the 223 .wks bootimg 224 -n NATIVE_SYSROOT, --native-sysroot NATIVE_SYSROOT 225 path to the native sysroot containing the tools to use 226 to build the image 227 -s, --skip-build-check 228 skip the build check 229 -f, --build-rootfs build rootfs 230 -c {gzip,bzip2,xz}, --compress-with {gzip,bzip2,xz} 231 compress image with specified compressor 232 -m, --bmap generate .bmap 233 --no-fstab-update Do not change fstab file. 234 -v VARS_DIR, --vars VARS_DIR 235 directory with <image>.env files that store bitbake 236 variables 237 -D, --debug output debug information 238 239.. note:: 240 241 You do not need root privileges to run Wic. In fact, you should not 242 run as root when using the utility. 243 244Cooked Mode 245----------- 246 247Running Wic in cooked mode leverages off artifacts in the 248:term:`Build Directory`. In other words, you do not have to specify kernel or 249root filesystem locations as part of the command. All you need to provide is 250a kickstart file and the name of the image from which to use artifacts 251by using the "-e" option. Wic looks in the :term:`Build Directory` (e.g. 252``tmp/deploy/images/``\ machine) for artifacts. 253 254The general form of the ``wic`` command using Cooked Mode is as follows:: 255 256 $ wic create wks_file -e IMAGE_NAME 257 258 Where: 259 260 wks_file: 261 An OpenEmbedded kickstart file. You can provide 262 your own custom file or use a file from a set of 263 existing files provided with the Yocto Project 264 release. 265 266 required argument: 267 -e IMAGE_NAME, --image-name IMAGE_NAME 268 name of the image to use the artifacts from e.g. core- 269 image-sato 270 271Using an Existing Kickstart File 272================================ 273 274If you do not want to create your own kickstart file, you can use an 275existing file provided by the Wic installation. As shipped, kickstart 276files can be found in the :ref:`overview-manual/development-environment:yocto project source repositories` in the 277following two locations:: 278 279 poky/meta-yocto-bsp/wic 280 poky/scripts/lib/wic/canned-wks 281 282Use the following command to list the available kickstart files:: 283 284 $ wic list images 285 genericx86 Create an EFI disk image for genericx86* 286 beaglebone-yocto Create SD card image for Beaglebone 287 qemuriscv Create qcow2 image for RISC-V QEMU machines 288 mkefidisk Create an EFI disk image 289 qemuloongarch Create qcow2 image for LoongArch QEMU machines 290 directdisk-multi-rootfs Create multi rootfs image using rootfs plugin 291 directdisk Create a 'pcbios' direct disk image 292 efi-bootdisk 293 mkhybridiso Create a hybrid ISO image 294 directdisk-gpt Create a 'pcbios' direct disk image 295 systemd-bootdisk Create an EFI disk image with systemd-boot 296 sdimage-bootpart Create SD card image with a boot partition 297 qemux86-directdisk Create a qemu machine 'pcbios' direct disk image 298 directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config 299 300When you use an existing file, you 301do not have to use the ``.wks`` extension. Here is an example in Raw 302Mode that uses the ``directdisk`` file:: 303 304 $ wic create directdisk -r rootfs_dir -b bootimg_dir \ 305 -k kernel_dir -n native_sysroot 306 307Here are the actual partition language commands used in the 308``genericx86.wks`` file to generate an image:: 309 310 # short-description: Create an EFI disk image for genericx86* 311 # long-description: Creates a partitioned EFI disk image for genericx86* machines 312 part /boot --source bootimg-efi --sourceparams="loader=grub-efi" --ondisk sda --label msdos --active --align 1024 313 part / --source rootfs --ondisk sda --fstype=ext4 --label platform --align 1024 --use-uuid 314 part swap --ondisk sda --size 44 --label swap1 --fstype=swap 315 316 bootloader --ptable gpt --timeout=5 --append="rootfstype=ext4 console=ttyS0,115200 console=tty0" 317 318Using the Wic Plugin Interface 319============================== 320 321You can extend and specialize Wic functionality by using Wic plugins. 322This section explains the Wic plugin interface. 323 324.. note:: 325 326 Wic plugins consist of "source" and "imager" plugins. Imager plugins 327 are beyond the scope of this section. 328 329Source plugins provide a mechanism to customize partition content during 330the Wic image generation process. You can use source plugins to map 331values that you specify using ``--source`` commands in kickstart files 332(i.e. ``*.wks``) to a plugin implementation used to populate a given 333partition. 334 335.. note:: 336 337 If you use plugins that have build-time dependencies (e.g. native 338 tools, bootloaders, and so forth) when building a Wic image, you need 339 to specify those dependencies using the :term:`WKS_FILE_DEPENDS` 340 variable. 341 342Source plugins are subclasses defined in plugin files. As shipped, the 343Yocto Project provides several plugin files. You can see the source 344plugin files that ship with the Yocto Project 345:yocto_git:`here </poky/tree/scripts/lib/wic/plugins/source>`. 346Each of these plugin files contains source plugins that are designed to 347populate a specific Wic image partition. 348 349Source plugins are subclasses of the ``SourcePlugin`` class, which is 350defined in the ``poky/scripts/lib/wic/pluginbase.py`` file. For example, 351the ``BootimgEFIPlugin`` source plugin found in the ``bootimg-efi.py`` 352file is a subclass of the ``SourcePlugin`` class, which is found in the 353``pluginbase.py`` file. 354 355You can also implement source plugins in a layer outside of the Source 356Repositories (external layer). To do so, be sure that your plugin files 357are located in a directory whose path is 358``scripts/lib/wic/plugins/source/`` within your external layer. When the 359plugin files are located there, the source plugins they contain are made 360available to Wic. 361 362When the Wic implementation needs to invoke a partition-specific 363implementation, it looks for the plugin with the same name as the 364``--source`` parameter used in the kickstart file given to that 365partition. For example, if the partition is set up using the following 366command in a kickstart file:: 367 368 part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 369 370The methods defined as class 371members of the matching source plugin (i.e. ``bootimg-pcbios``) in the 372``bootimg-pcbios.py`` plugin file are used. 373 374To be more concrete, here is the corresponding plugin definition from 375the ``bootimg-pcbios.py`` file for the previous command along with an 376example method called by the Wic implementation when it needs to prepare 377a partition using an implementation-specific function:: 378 379 . 380 . 381 . 382 class BootimgPcbiosPlugin(SourcePlugin): 383 """ 384 Create MBR boot partition and install syslinux on it. 385 """ 386 387 name = 'bootimg-pcbios' 388 . 389 . 390 . 391 @classmethod 392 def do_prepare_partition(cls, part, source_params, creator, cr_workdir, 393 oe_builddir, bootimg_dir, kernel_dir, 394 rootfs_dir, native_sysroot): 395 """ 396 Called to do the actual content population for a partition i.e. it 397 'prepares' the partition to be incorporated into the image. 398 In this case, prepare content for legacy bios boot partition. 399 """ 400 . 401 . 402 . 403 404If a 405subclass (plugin) itself does not implement a particular function, Wic 406locates and uses the default version in the superclass. It is for this 407reason that all source plugins are derived from the ``SourcePlugin`` 408class. 409 410The ``SourcePlugin`` class defined in the ``pluginbase.py`` file defines 411a set of methods that source plugins can implement or override. Any 412plugins (subclass of ``SourcePlugin``) that do not implement a 413particular method inherit the implementation of the method from the 414``SourcePlugin`` class. For more information, see the ``SourcePlugin`` 415class in the ``pluginbase.py`` file for details: 416 417The following list describes the methods implemented in the 418``SourcePlugin`` class: 419 420- ``do_prepare_partition()``: Called to populate a partition with 421 actual content. In other words, the method prepares the final 422 partition image that is incorporated into the disk image. 423 424- ``do_configure_partition()``: Called before 425 ``do_prepare_partition()`` to create custom configuration files for a 426 partition (e.g. syslinux or grub configuration files). 427 428- ``do_install_disk()``: Called after all partitions have been 429 prepared and assembled into a disk image. This method provides a hook 430 to allow finalization of a disk image (e.g. writing an MBR). 431 432- ``do_stage_partition()``: Special content-staging hook called 433 before ``do_prepare_partition()``. This method is normally empty. 434 435 Typically, a partition just uses the passed-in parameters (e.g. the 436 unmodified value of ``bootimg_dir``). However, in some cases, things 437 might need to be more tailored. As an example, certain files might 438 additionally need to be taken from ``bootimg_dir + /boot``. This hook 439 allows those files to be staged in a customized fashion. 440 441 .. note:: 442 443 ``get_bitbake_var()`` allows you to access non-standard variables that 444 you might want to use for this behavior. 445 446You can extend the source plugin mechanism. To add more hooks, create 447more source plugin methods within ``SourcePlugin`` and the corresponding 448derived subclasses. The code that calls the plugin methods uses the 449``plugin.get_source_plugin_methods()`` function to find the method or 450methods needed by the call. Retrieval of those methods is accomplished 451by filling up a dict with keys that contain the method names of 452interest. On success, these will be filled in with the actual methods. 453See the Wic implementation for examples and details. 454 455Wic Examples 456============ 457 458This section provides several examples that show how to use the Wic 459utility. All the examples assume the list of requirements in the 460":ref:`dev-manual/wic:requirements`" section have been met. The 461examples assume the previously generated image is 462``core-image-minimal``. 463 464Generate an Image using an Existing Kickstart File 465-------------------------------------------------- 466 467This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart 468file:: 469 470 $ wic create mkefidisk -e core-image-minimal 471 INFO: Building wic-tools... 472 . 473 . 474 . 475 INFO: The new image(s) can be found here: 476 ./mkefidisk-201804191017-sda.direct 477 478 The following build artifacts were used to create the image(s): 479 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs 480 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share 481 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 482 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native 483 484 INFO: The image(s) were created using OE kickstart file: 485 /home/stephano/yocto/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks 486 487The previous example shows the easiest way to create an image by running 488in cooked mode and supplying a kickstart file and the "-e" option to 489point to the existing build artifacts. Your ``local.conf`` file needs to 490have the :term:`MACHINE` variable set 491to the machine you are using, which is "qemux86" in this example. 492 493Once the image builds, the output provides image location, artifact use, 494and kickstart file information. 495 496.. note:: 497 498 You should always verify the details provided in the output to make 499 sure that the image was indeed created exactly as expected. 500 501Continuing with the example, you can now write the image from the 502:term:`Build Directory` onto a USB stick, or whatever media for which you 503built your image, and boot from the media. You can write the image by using 504``bmaptool`` or ``dd``:: 505 506 $ oe-run-native bmaptool-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sdX 507 508or :: 509 510 $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sdX 511 512.. note:: 513 514 For more information on how to use the ``bmaptool`` 515 to flash a device with an image, see the 516 ":ref:`dev-manual/bmaptool:flashing images using \`\`bmaptool\`\``" 517 section. 518 519Using a Modified Kickstart File 520------------------------------- 521 522Because partitioned image creation is driven by the kickstart file, it 523is easy to affect image creation by changing the parameters in the file. 524This next example demonstrates that through modification of the 525``directdisk-gpt`` kickstart file. 526 527As mentioned earlier, you can use the command ``wic list images`` to 528show the list of existing kickstart files. The directory in which the 529``directdisk-gpt.wks`` file resides is 530``scripts/lib/image/canned-wks/``, which is located in the 531:term:`Source Directory` (e.g. ``poky``). 532Because available files reside in this directory, you can create and add 533your own custom files to the directory. Subsequent use of the 534``wic list images`` command would then include your kickstart files. 535 536In this example, the existing ``directdisk-gpt`` file already does most 537of what is needed. However, for the hardware in this example, the image 538will need to boot from ``sdb`` instead of ``sda``, which is what the 539``directdisk-gpt`` kickstart file uses. 540 541The example begins by making a copy of the ``directdisk-gpt.wks`` file 542in the ``scripts/lib/image/canned-wks`` directory and then by changing 543the lines that specify the target disk from which to boot:: 544 545 $ cp /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \ 546 /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks 547 548Next, the example modifies the ``directdisksdb-gpt.wks`` file and 549changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The 550example changes the following two lines and leaves the remaining lines 551untouched:: 552 553 part /boot --source bootimg-pcbios --ondisk sdb --label boot --active --align 1024 554 part / --source rootfs --ondisk sdb --fstype=ext4 --label platform --align 1024 --use-uuid 555 556Once the lines are changed, the 557example generates the ``directdisksdb-gpt`` image. The command points 558the process at the ``core-image-minimal`` artifacts for the Next Unit of 559Computing (nuc) :term:`MACHINE` the 560``local.conf``:: 561 562 $ wic create directdisksdb-gpt -e core-image-minimal 563 INFO: Building wic-tools... 564 . 565 . 566 . 567 Initialising tasks: 100% |#######################################| Time: 0:00:01 568 NOTE: Executing SetScene Tasks 569 NOTE: Executing RunQueue Tasks 570 NOTE: Tasks Summary: Attempted 1161 tasks of which 1157 didn't need to be rerun and all succeeded. 571 INFO: Creating image(s)... 572 573 INFO: The new image(s) can be found here: 574 ./directdisksdb-gpt-201710090938-sdb.direct 575 576 The following build artifacts were used to create the image(s): 577 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs 578 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share 579 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 580 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native 581 582 INFO: The image(s) were created using OE kickstart file: 583 /home/stephano/yocto/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks 584 585Continuing with the example, you can now directly ``dd`` the image to a 586USB stick, or whatever media for which you built your image, and boot 587the resulting media:: 588 589 $ sudo dd if=directdisksdb-gpt-201710090938-sdb.direct of=/dev/sdb 590 140966+0 records in 591 140966+0 records out 592 72174592 bytes (72 MB, 69 MiB) copied, 78.0282 s, 925 kB/s 593 $ sudo eject /dev/sdb 594 595Using a Modified Kickstart File and Running in Raw Mode 596------------------------------------------------------- 597 598This next example manually specifies each build artifact (runs in Raw 599Mode) and uses a modified kickstart file. The example also uses the 600``-o`` option to cause Wic to create the output somewhere other than the 601default output directory, which is the current directory:: 602 603 $ wic create test.wks -o /home/stephano/testwic \ 604 --rootfs-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \ 605 --bootimg-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \ 606 --kernel-dir /home/stephano/yocto/build/tmp/deploy/images/qemux86 \ 607 --native-sysroot /home/stephano/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native 608 609 INFO: Creating image(s)... 610 611 INFO: The new image(s) can be found here: 612 /home/stephano/testwic/test-201710091445-sdb.direct 613 614 The following build artifacts were used to create the image(s): 615 ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs 616 BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share 617 KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86 618 NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native 619 620 INFO: The image(s) were created using OE kickstart file: 621 test.wks 622 623For this example, 624:term:`MACHINE` did not have to be 625specified in the ``local.conf`` file since the artifact is manually 626specified. 627 628Using Wic to Manipulate an Image 629-------------------------------- 630 631Wic image manipulation allows you to shorten turnaround time during 632image development. For example, you can use Wic to delete the kernel 633partition of a Wic image and then insert a newly built kernel. This 634saves you time from having to rebuild the entire image each time you 635modify the kernel. 636 637.. note:: 638 639 In order to use Wic to manipulate a Wic image as in this example, 640 your development machine must have the ``mtools`` package installed. 641 642The following example examines the contents of the Wic image, deletes 643the existing kernel, and then inserts a new kernel: 644 645#. *List the Partitions:* Use the ``wic ls`` command to list all the 646 partitions in the Wic image:: 647 648 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic 649 Num Start End Size Fstype 650 1 1048576 25041919 23993344 fat16 651 2 25165824 72157183 46991360 ext4 652 653 The previous output shows two partitions in the 654 ``core-image-minimal-qemux86.wic`` image. 655 656#. *Examine a Particular Partition:* Use the ``wic ls`` command again 657 but in a different form to examine a particular partition. 658 659 .. note:: 660 661 You can get command usage on any Wic command using the following 662 form:: 663 664 $ wic help command 665 666 667 For example, the following command shows you the various ways to 668 use the 669 wic ls 670 command:: 671 672 $ wic help ls 673 674 675 The following command shows what is in partition one:: 676 677 $ wic ls tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1 678 Volume in drive : is boot 679 Volume Serial Number is E894-1809 680 Directory for ::/ 681 682 libcom32 c32 186500 2017-10-09 16:06 683 libutil c32 24148 2017-10-09 16:06 684 syslinux cfg 220 2017-10-09 16:06 685 vesamenu c32 27104 2017-10-09 16:06 686 vmlinuz 6904608 2017-10-09 16:06 687 5 files 7 142 580 bytes 688 16 582 656 bytes free 689 690 The previous output shows five files, with the 691 ``vmlinuz`` being the kernel. 692 693 .. note:: 694 695 If you see the following error, you need to update or create a 696 ``~/.mtoolsrc`` file and be sure to have the line "mtools_skip_check=1" 697 in the file. Then, run the Wic command again:: 698 699 ERROR: _exec_cmd: /usr/bin/mdir -i /tmp/wic-parttfokuwra ::/ returned '1' instead of 0 700 output: Total number of sectors (47824) not a multiple of sectors per track (32)! 701 Add mtools_skip_check=1 to your .mtoolsrc file to skip this test 702 703 704#. *Remove the Old Kernel:* Use the ``wic rm`` command to remove the 705 ``vmlinuz`` file (kernel):: 706 707 $ wic rm tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz 708 709#. *Add In the New Kernel:* Use the ``wic cp`` command to add the 710 updated kernel to the Wic image. Depending on how you built your 711 kernel, it could be in different places. If you used ``devtool`` and 712 an SDK to build your kernel, it resides in the ``tmp/work`` directory 713 of the extensible SDK. If you used ``make`` to build the kernel, the 714 kernel will be in the ``workspace/sources`` area. 715 716 The following example assumes ``devtool`` was used to build the 717 kernel:: 718 719 $ wic 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 \ 720 poky/build/tmp/deploy/images/qemux86/core-image-minimal-qemux86.wic:1/vmlinuz 721 722 Once the new kernel is added back into the image, you can use the 723 ``dd`` command or :ref:`bmaptool 724 <dev-manual/bmaptool:flashing images using \`\`bmaptool\`\`>` 725 to flash your wic image onto an SD card or USB stick and test your 726 target. 727 728 .. note:: 729 730 Using ``bmaptool`` is generally 10 to 20 times faster than using ``dd``. 731 732