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