diff options
Diffstat (limited to 'documentation/dev-manual/wic.rst')
-rw-r--r-- | documentation/dev-manual/wic.rst | 731 |
1 files changed, 731 insertions, 0 deletions
diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst new file mode 100644 index 0000000000..a3880f3a1c --- /dev/null +++ b/documentation/dev-manual/wic.rst | |||
@@ -0,0 +1,731 @@ | |||
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 :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 | |||
68 | Requirements | ||
69 | ============ | ||
70 | |||
71 | In order to use the Wic utility with the OpenEmbedded Build system, your | ||
72 | system 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 | |||
106 | Getting Help | ||
107 | ============ | ||
108 | |||
109 | You can get general help for the ``wic`` command by entering the ``wic`` | ||
110 | command by itself or by entering the command with a help argument as | ||
111 | follows:: | ||
112 | |||
113 | $ wic -h | ||
114 | $ wic --help | ||
115 | $ wic help | ||
116 | |||
117 | Currently, Wic supports seven commands: ``cp``, ``create``, ``help``, | ||
118 | ``list``, ``ls``, ``rm``, and ``write``. You can get help for all these | ||
119 | commands except "help" by using the following form:: | ||
120 | |||
121 | $ wic help command | ||
122 | |||
123 | For example, the following command returns help for the ``write`` | ||
124 | command:: | ||
125 | |||
126 | $ wic help write | ||
127 | |||
128 | Wic 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 | |||
133 | For example, the following returns overview help for Wic:: | ||
134 | |||
135 | $ wic help overview | ||
136 | |||
137 | There is one additional level of help for Wic. You can get help on | ||
138 | individual images through the ``list`` command. You can use the ``list`` | ||
139 | command 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 | |||
157 | Once you know the list of available | ||
158 | Wic images, you can use ``help`` with the command to get help on a | ||
159 | particular 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 | |||
167 | Operational Modes | ||
168 | ================= | ||
169 | |||
170 | You can use Wic in two different modes, depending on how much control | ||
171 | you need for specifying the OpenEmbedded build artifacts that are used | ||
172 | for 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 | |||
183 | Regardless of the mode you use, you need to have the build artifacts | ||
184 | ready and available. | ||
185 | |||
186 | Raw Mode | ||
187 | -------- | ||
188 | |||
189 | Running Wic in raw mode allows you to specify all the partitions through | ||
190 | the ``wic`` command line. The primary use for raw mode is if you have | ||
191 | built your kernel outside of the Yocto Project :term:`Build Directory`. | ||
192 | In other words, you can point to arbitrary kernel, root filesystem locations, | ||
193 | and so forth. Contrast this behavior with cooked mode where Wic looks in the | ||
194 | :term:`Build Directory` (e.g. ``tmp/deploy/images/``\ machine). | ||
195 | |||
196 | The 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 | |||
244 | Cooked Mode | ||
245 | ----------- | ||
246 | |||
247 | Running Wic in cooked mode leverages off artifacts in the | ||
248 | :term:`Build Directory`. In other words, you do not have to specify kernel or | ||
249 | root filesystem locations as part of the command. All you need to provide is | ||
250 | a kickstart file and the name of the image from which to use artifacts | ||
251 | by using the "-e" option. Wic looks in the :term:`Build Directory` (e.g. | ||
252 | ``tmp/deploy/images/``\ machine) for artifacts. | ||
253 | |||
254 | The 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 | |||
271 | Using an Existing Kickstart File | ||
272 | ================================ | ||
273 | |||
274 | If you do not want to create your own kickstart file, you can use an | ||
275 | existing file provided by the Wic installation. As shipped, kickstart | ||
276 | files can be found in the :ref:`overview-manual/development-environment:yocto project source repositories` in the | ||
277 | following two locations:: | ||
278 | |||
279 | poky/meta-yocto-bsp/wic | ||
280 | poky/scripts/lib/wic/canned-wks | ||
281 | |||
282 | Use 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 | |||
300 | When you use an existing file, you | ||
301 | do not have to use the ``.wks`` extension. Here is an example in Raw | ||
302 | Mode that uses the ``directdisk`` file:: | ||
303 | |||
304 | $ wic create directdisk -r rootfs_dir -b bootimg_dir \ | ||
305 | -k kernel_dir -n native_sysroot | ||
306 | |||
307 | Here 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 | |||
318 | Using the Wic Plugin Interface | ||
319 | ============================== | ||
320 | |||
321 | You can extend and specialize Wic functionality by using Wic plugins. | ||
322 | This 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 | |||
329 | Source plugins provide a mechanism to customize partition content during | ||
330 | the Wic image generation process. You can use source plugins to map | ||
331 | values that you specify using ``--source`` commands in kickstart files | ||
332 | (i.e. ``*.wks``) to a plugin implementation used to populate a given | ||
333 | partition. | ||
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 | |||
342 | Source plugins are subclasses defined in plugin files. As shipped, the | ||
343 | Yocto Project provides several plugin files. You can see the source | ||
344 | plugin files that ship with the Yocto Project | ||
345 | :yocto_git:`here </poky/tree/scripts/lib/wic/plugins/source>`. | ||
346 | Each of these plugin files contains source plugins that are designed to | ||
347 | populate a specific Wic image partition. | ||
348 | |||
349 | Source plugins are subclasses of the ``SourcePlugin`` class, which is | ||
350 | defined in the ``poky/scripts/lib/wic/pluginbase.py`` file. For example, | ||
351 | the ``BootimgEFIPlugin`` source plugin found in the ``bootimg-efi.py`` | ||
352 | file is a subclass of the ``SourcePlugin`` class, which is found in the | ||
353 | ``pluginbase.py`` file. | ||
354 | |||
355 | You can also implement source plugins in a layer outside of the Source | ||
356 | Repositories (external layer). To do so, be sure that your plugin files | ||
357 | are located in a directory whose path is | ||
358 | ``scripts/lib/wic/plugins/source/`` within your external layer. When the | ||
359 | plugin files are located there, the source plugins they contain are made | ||
360 | available to Wic. | ||
361 | |||
362 | When the Wic implementation needs to invoke a partition-specific | ||
363 | implementation, it looks for the plugin with the same name as the | ||
364 | ``--source`` parameter used in the kickstart file given to that | ||
365 | partition. For example, if the partition is set up using the following | ||
366 | command in a kickstart file:: | ||
367 | |||
368 | part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024 | ||
369 | |||
370 | The methods defined as class | ||
371 | members of the matching source plugin (i.e. ``bootimg-pcbios``) in the | ||
372 | ``bootimg-pcbios.py`` plugin file are used. | ||
373 | |||
374 | To be more concrete, here is the corresponding plugin definition from | ||
375 | the ``bootimg-pcbios.py`` file for the previous command along with an | ||
376 | example method called by the Wic implementation when it needs to prepare | ||
377 | a 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 | |||
404 | If a | ||
405 | subclass (plugin) itself does not implement a particular function, Wic | ||
406 | locates and uses the default version in the superclass. It is for this | ||
407 | reason that all source plugins are derived from the ``SourcePlugin`` | ||
408 | class. | ||
409 | |||
410 | The ``SourcePlugin`` class defined in the ``pluginbase.py`` file defines | ||
411 | a set of methods that source plugins can implement or override. Any | ||
412 | plugins (subclass of ``SourcePlugin``) that do not implement a | ||
413 | particular method inherit the implementation of the method from the | ||
414 | ``SourcePlugin`` class. For more information, see the ``SourcePlugin`` | ||
415 | class in the ``pluginbase.py`` file for details: | ||
416 | |||
417 | The 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 | |||
446 | You can extend the source plugin mechanism. To add more hooks, create | ||
447 | more source plugin methods within ``SourcePlugin`` and the corresponding | ||
448 | derived subclasses. The code that calls the plugin methods uses the | ||
449 | ``plugin.get_source_plugin_methods()`` function to find the method or | ||
450 | methods needed by the call. Retrieval of those methods is accomplished | ||
451 | by filling up a dict with keys that contain the method names of | ||
452 | interest. On success, these will be filled in with the actual methods. | ||
453 | See the Wic implementation for examples and details. | ||
454 | |||
455 | Wic Examples | ||
456 | ============ | ||
457 | |||
458 | This section provides several examples that show how to use the Wic | ||
459 | utility. All the examples assume the list of requirements in the | ||
460 | ":ref:`dev-manual/wic:requirements`" section have been met. The | ||
461 | examples assume the previously generated image is | ||
462 | ``core-image-minimal``. | ||
463 | |||
464 | Generate an Image using an Existing Kickstart File | ||
465 | -------------------------------------------------- | ||
466 | |||
467 | This example runs in Cooked Mode and uses the ``mkefidisk`` kickstart | ||
468 | file:: | ||
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 | |||
487 | The previous example shows the easiest way to create an image by running | ||
488 | in cooked mode and supplying a kickstart file and the "-e" option to | ||
489 | point to the existing build artifacts. Your ``local.conf`` file needs to | ||
490 | have the :term:`MACHINE` variable set | ||
491 | to the machine you are using, which is "qemux86" in this example. | ||
492 | |||
493 | Once the image builds, the output provides image location, artifact use, | ||
494 | and 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 | |||
501 | Continuing 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 | ||
503 | built 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 | |||
508 | or :: | ||
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 | |||
519 | Using a Modified Kickstart File | ||
520 | ------------------------------- | ||
521 | |||
522 | Because partitioned image creation is driven by the kickstart file, it | ||
523 | is easy to affect image creation by changing the parameters in the file. | ||
524 | This next example demonstrates that through modification of the | ||
525 | ``directdisk-gpt`` kickstart file. | ||
526 | |||
527 | As mentioned earlier, you can use the command ``wic list images`` to | ||
528 | show 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``). | ||
532 | Because available files reside in this directory, you can create and add | ||
533 | your own custom files to the directory. Subsequent use of the | ||
534 | ``wic list images`` command would then include your kickstart files. | ||
535 | |||
536 | In this example, the existing ``directdisk-gpt`` file already does most | ||
537 | of what is needed. However, for the hardware in this example, the image | ||
538 | will need to boot from ``sdb`` instead of ``sda``, which is what the | ||
539 | ``directdisk-gpt`` kickstart file uses. | ||
540 | |||
541 | The example begins by making a copy of the ``directdisk-gpt.wks`` file | ||
542 | in the ``scripts/lib/image/canned-wks`` directory and then by changing | ||
543 | the 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 | |||
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 | $ 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 | |||
585 | Continuing with the example, you can now directly ``dd`` the image to a | ||
586 | USB stick, or whatever media for which you built your image, and boot | ||
587 | the 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 | |||
595 | Using a Modified Kickstart File and Running in Raw Mode | ||
596 | ------------------------------------------------------- | ||
597 | |||
598 | This next example manually specifies each build artifact (runs in Raw | ||
599 | Mode) 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 | ||
601 | default 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 | |||
623 | For this example, | ||
624 | :term:`MACHINE` did not have to be | ||
625 | specified in the ``local.conf`` file since the artifact is manually | ||
626 | specified. | ||
627 | |||
628 | Using Wic to Manipulate an Image | ||
629 | -------------------------------- | ||
630 | |||
631 | Wic image manipulation allows you to shorten turnaround time during | ||
632 | image development. For example, you can use Wic to delete the kernel | ||
633 | partition of a Wic image and then insert a newly built kernel. This | ||
634 | saves you time from having to rebuild the entire image each time you | ||
635 | modify 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 | |||
642 | The following example examines the contents of the Wic image, deletes | ||
643 | the 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 | |||