diff options
Diffstat (limited to 'documentation/dev-manual/qemu.rst')
-rw-r--r-- | documentation/dev-manual/qemu.rst | 463 |
1 files changed, 463 insertions, 0 deletions
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst new file mode 100644 index 0000000000..4e58fc1b67 --- /dev/null +++ b/documentation/dev-manual/qemu.rst | |||
@@ -0,0 +1,463 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ******************************* | ||
4 | Using the Quick EMUlator (QEMU) | ||
5 | ******************************* | ||
6 | |||
7 | The Yocto Project uses an implementation of the Quick EMUlator (QEMU) | ||
8 | Open Source project as part of the Yocto Project development "tool set". | ||
9 | This chapter provides both procedures that show you how to use the Quick | ||
10 | EMUlator (QEMU) and other QEMU information helpful for development | ||
11 | purposes. | ||
12 | |||
13 | Overview | ||
14 | ======== | ||
15 | |||
16 | Within the context of the Yocto Project, QEMU is an emulator and | ||
17 | virtualization machine that allows you to run a complete image you have | ||
18 | built using the Yocto Project as just another task on your build system. | ||
19 | QEMU is useful for running and testing images and applications on | ||
20 | supported Yocto Project architectures without having actual hardware. | ||
21 | Among other things, the Yocto Project uses QEMU to run automated Quality | ||
22 | Assurance (QA) tests on final images shipped with each release. | ||
23 | |||
24 | .. note:: | ||
25 | |||
26 | This implementation is not the same as QEMU in general. | ||
27 | |||
28 | This section provides a brief reference for the Yocto Project | ||
29 | implementation of QEMU. | ||
30 | |||
31 | For official information and documentation on QEMU in general, see the | ||
32 | following references: | ||
33 | |||
34 | - `QEMU Website <https://wiki.qemu.org/Main_Page>`__\ *:* The official | ||
35 | website for the QEMU Open Source project. | ||
36 | |||
37 | - `Documentation <https://wiki.qemu.org/Manual>`__\ *:* The QEMU user | ||
38 | manual. | ||
39 | |||
40 | Running QEMU | ||
41 | ============ | ||
42 | |||
43 | To use QEMU, you need to have QEMU installed and initialized as well as | ||
44 | have the proper artifacts (i.e. image files and root filesystems) | ||
45 | available. Follow these general steps to run QEMU: | ||
46 | |||
47 | 1. *Install QEMU:* QEMU is made available with the Yocto Project a | ||
48 | number of ways. One method is to install a Software Development Kit | ||
49 | (SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the | ||
50 | Yocto Project Application Development and the Extensible Software | ||
51 | Development Kit (eSDK) manual for information on how to install QEMU. | ||
52 | |||
53 | 2. *Setting Up the Environment:* How you set up the QEMU environment | ||
54 | depends on how you installed QEMU: | ||
55 | |||
56 | - If you cloned the ``poky`` repository or you downloaded and | ||
57 | unpacked a Yocto Project release tarball, you can source the build | ||
58 | environment script (i.e. :ref:`structure-core-script`): | ||
59 | :: | ||
60 | |||
61 | $ cd ~/poky | ||
62 | $ source oe-init-build-env | ||
63 | |||
64 | - If you installed a cross-toolchain, you can run the script that | ||
65 | initializes the toolchain. For example, the following commands run | ||
66 | the initialization script from the default ``poky_sdk`` directory: | ||
67 | :: | ||
68 | |||
69 | . ~/poky_sdk/environment-setup-core2-64-poky-linux | ||
70 | |||
71 | 3. *Ensure the Artifacts are in Place:* You need to be sure you have a | ||
72 | pre-built kernel that will boot in QEMU. You also need the target | ||
73 | root filesystem for your target machine's architecture: | ||
74 | |||
75 | - If you have previously built an image for QEMU (e.g. ``qemux86``, | ||
76 | ``qemuarm``, and so forth), then the artifacts are in place in | ||
77 | your :term:`Build Directory`. | ||
78 | |||
79 | - If you have not built an image, you can go to the | ||
80 | :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu/>` area and download a | ||
81 | pre-built image that matches your architecture and can be run on | ||
82 | QEMU. | ||
83 | |||
84 | See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`" | ||
85 | section in the Yocto Project Application Development and the | ||
86 | Extensible Software Development Kit (eSDK) manual for information on | ||
87 | how to extract a root filesystem. | ||
88 | |||
89 | 4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: | ||
90 | :: | ||
91 | |||
92 | $ runqemu [option ] [...] | ||
93 | |||
94 | Based on what you provide on the command | ||
95 | line, ``runqemu`` does a good job of figuring out what you are trying | ||
96 | to do. For example, by default, QEMU looks for the most recently | ||
97 | built image according to the timestamp when it needs to look for an | ||
98 | image. Minimally, through the use of options, you must provide either | ||
99 | a machine name, a virtual machine image (``*wic.vmdk``), or a kernel | ||
100 | image (``*.bin``). | ||
101 | |||
102 | Here are some additional examples to help illustrate further QEMU: | ||
103 | |||
104 | - This example starts QEMU with MACHINE set to "qemux86-64". | ||
105 | Assuming a standard | ||
106 | :term:`Build Directory`, ``runqemu`` | ||
107 | automatically finds the ``bzImage-qemux86-64.bin`` image file and | ||
108 | the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4`` | ||
109 | (assuming the current build created a ``core-image-minimal`` | ||
110 | image). | ||
111 | |||
112 | .. note:: | ||
113 | |||
114 | When more than one image with the same name exists, QEMU finds | ||
115 | and uses the most recently built image according to the | ||
116 | timestamp. | ||
117 | |||
118 | :: | ||
119 | |||
120 | $ runqemu qemux86-64 | ||
121 | |||
122 | - This example produces the exact same results as the previous | ||
123 | example. This command, however, specifically provides the image | ||
124 | and root filesystem type. | ||
125 | :: | ||
126 | |||
127 | $ runqemu qemux86-64 core-image-minimal ext4 | ||
128 | |||
129 | - This example specifies to boot an initial RAM disk image and to | ||
130 | enable audio in QEMU. For this case, ``runqemu`` set the internal | ||
131 | variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, | ||
132 | an appropriate driver must be installed (see the previous | ||
133 | description for the ``audio`` option for more information). | ||
134 | :: | ||
135 | |||
136 | $ runqemu qemux86-64 ramfs audio | ||
137 | |||
138 | - This example does not provide enough information for QEMU to | ||
139 | launch. While the command does provide a root filesystem type, it | ||
140 | must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option. | ||
141 | :: | ||
142 | |||
143 | $ runqemu ext4 | ||
144 | |||
145 | - This example specifies to boot a virtual machine image | ||
146 | (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` | ||
147 | determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and | ||
148 | the root filesystem type to be "vmdk". | ||
149 | :: | ||
150 | |||
151 | $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk | ||
152 | |||
153 | Switching Between Consoles | ||
154 | ========================== | ||
155 | |||
156 | When booting or running QEMU, you can switch between supported consoles | ||
157 | by using Ctrl+Alt+number. For example, Ctrl+Alt+3 switches you to the | ||
158 | serial console as long as that console is enabled. Being able to switch | ||
159 | consoles is helpful, for example, if the main QEMU console breaks for | ||
160 | some reason. | ||
161 | |||
162 | .. note:: | ||
163 | |||
164 | Usually, "2" gets you to the main console and "3" gets you to the | ||
165 | serial console. | ||
166 | |||
167 | Removing the Splash Screen | ||
168 | ========================== | ||
169 | |||
170 | You can remove the splash screen when QEMU is booting by using Alt+left. | ||
171 | Removing the splash screen allows you to see what is happening in the | ||
172 | background. | ||
173 | |||
174 | Disabling the Cursor Grab | ||
175 | ========================= | ||
176 | |||
177 | The default QEMU integration captures the cursor within the main window. | ||
178 | It does this since standard mouse devices only provide relative input | ||
179 | and not absolute coordinates. You then have to break out of the grab | ||
180 | using the "Ctrl+Alt" key combination. However, the Yocto Project's | ||
181 | integration of QEMU enables the wacom USB touch pad driver by default to | ||
182 | allow input of absolute coordinates. This default means that the mouse | ||
183 | can enter and leave the main window without the grab taking effect | ||
184 | leading to a better user experience. | ||
185 | |||
186 | Running Under a Network File System (NFS) Server | ||
187 | ================================================ | ||
188 | |||
189 | One method for running QEMU is to run it on an NFS server. This is | ||
190 | useful when you need to access the same file system from both the build | ||
191 | and the emulated system at the same time. It is also worth noting that | ||
192 | the system does not need root privileges to run. It uses a user space | ||
193 | NFS server to avoid that. Follow these steps to set up for running QEMU | ||
194 | using an NFS server. | ||
195 | |||
196 | 1. *Extract a Root Filesystem:* Once you are able to run QEMU in your | ||
197 | environment, you can use the ``runqemu-extract-sdk`` script, which is | ||
198 | located in the ``scripts`` directory along with the ``runqemu`` | ||
199 | script. | ||
200 | |||
201 | The ``runqemu-extract-sdk`` takes a root filesystem tarball and | ||
202 | extracts it into a location that you specify. Here is an example that | ||
203 | takes a file system and extracts it to a directory named | ||
204 | ``test-nfs``: | ||
205 | |||
206 | .. code-block:: none | ||
207 | |||
208 | runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs | ||
209 | |||
210 | 2. *Start QEMU:* Once you have extracted the file system, you can run | ||
211 | ``runqemu`` normally with the additional location of the file system. | ||
212 | You can then also make changes to the files within ``./test-nfs`` and | ||
213 | see those changes appear in the image in real time. Here is an | ||
214 | example using the ``qemux86`` image: | ||
215 | |||
216 | .. code-block:: none | ||
217 | |||
218 | runqemu qemux86-64 ./test-nfs | ||
219 | |||
220 | .. note:: | ||
221 | |||
222 | Should you need to start, stop, or restart the NFS share, you can use | ||
223 | the following commands: | ||
224 | |||
225 | - The following command starts the NFS share: | ||
226 | :: | ||
227 | |||
228 | runqemu-export-rootfs start file-system-location | ||
229 | |||
230 | - The following command stops the NFS share: | ||
231 | :: | ||
232 | |||
233 | runqemu-export-rootfs stop file-system-location | ||
234 | |||
235 | - The following command restarts the NFS share: | ||
236 | :: | ||
237 | |||
238 | runqemu-export-rootfs restart file-system-location | ||
239 | |||
240 | QEMU CPU Compatibility Under KVM | ||
241 | ================================ | ||
242 | |||
243 | By default, the QEMU build compiles for and targets 64-bit and x86 Intel | ||
244 | Core2 Duo processors and 32-bit x86 Intel Pentium II processors. QEMU | ||
245 | builds for and targets these CPU types because they display a broad | ||
246 | range of CPU feature compatibility with many commonly used CPUs. | ||
247 | |||
248 | Despite this broad range of compatibility, the CPUs could support a | ||
249 | feature that your host CPU does not support. Although this situation is | ||
250 | not a problem when QEMU uses software emulation of the feature, it can | ||
251 | be a problem when QEMU is running with KVM enabled. Specifically, | ||
252 | software compiled with a certain CPU feature crashes when run on a CPU | ||
253 | under KVM that does not support that feature. To work around this | ||
254 | problem, you can override QEMU's runtime CPU setting by changing the | ||
255 | ``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the | ||
256 | :term:`Build Directory` ``deploy/image`` | ||
257 | directory. This setting specifies a ``-cpu`` option passed into QEMU in | ||
258 | the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of | ||
259 | available supported CPU types. | ||
260 | |||
261 | QEMU Performance | ||
262 | ================ | ||
263 | |||
264 | Using QEMU to emulate your hardware can result in speed issues depending | ||
265 | on the target and host architecture mix. For example, using the | ||
266 | ``qemux86`` image in the emulator on an Intel-based 32-bit (x86) host | ||
267 | machine is fast because the target and host architectures match. On the | ||
268 | other hand, using the ``qemuarm`` image on the same Intel-based host can | ||
269 | be slower. But, you still achieve faithful emulation of ARM-specific | ||
270 | issues. | ||
271 | |||
272 | To speed things up, the QEMU images support using ``distcc`` to call a | ||
273 | cross-compiler outside the emulated system. If you used ``runqemu`` to | ||
274 | start QEMU, and the ``distccd`` application is present on the host | ||
275 | system, any BitBake cross-compiling toolchain available from the build | ||
276 | system is automatically used from within QEMU simply by calling | ||
277 | ``distcc``. You can accomplish this by defining the cross-compiler | ||
278 | variable (e.g. ``export CC="distcc"``). Alternatively, if you are using | ||
279 | a suitable SDK image or the appropriate stand-alone toolchain is | ||
280 | present, the toolchain is also automatically used. | ||
281 | |||
282 | .. note:: | ||
283 | |||
284 | Several mechanisms exist that let you connect to the system running | ||
285 | on the QEMU emulator: | ||
286 | |||
287 | - QEMU provides a framebuffer interface that makes standard consoles | ||
288 | available. | ||
289 | |||
290 | - Generally, headless embedded devices have a serial port. If so, | ||
291 | you can configure the operating system of the running image to use | ||
292 | that port to run a console. The connection uses standard IP | ||
293 | networking. | ||
294 | |||
295 | - SSH servers exist in some QEMU images. The ``core-image-sato`` | ||
296 | QEMU image has a Dropbear secure shell (SSH) server that runs with | ||
297 | the root password disabled. The ``core-image-full-cmdline`` and | ||
298 | ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear. | ||
299 | Including these SSH servers allow you to use standard ``ssh`` and | ||
300 | ``scp`` commands. The ``core-image-minimal`` QEMU image, however, | ||
301 | contains no SSH server. | ||
302 | |||
303 | - You can use a provided, user-space NFS server to boot the QEMU | ||
304 | session using a local copy of the root filesystem on the host. In | ||
305 | order to make this connection, you must extract a root filesystem | ||
306 | tarball by using the ``runqemu-extract-sdk`` command. After | ||
307 | running the command, you must then point the ``runqemu`` script to | ||
308 | the extracted directory instead of a root filesystem image file. | ||
309 | See the "`Running Under a Network File System (NFS) | ||
310 | Server <#qemu-running-under-a-network-file-system-nfs-server>`__" | ||
311 | section for more information. | ||
312 | |||
313 | QEMU Command-Line Syntax | ||
314 | ======================== | ||
315 | |||
316 | The basic ``runqemu`` command syntax is as follows: | ||
317 | :: | ||
318 | |||
319 | $ runqemu [option ] [...] | ||
320 | |||
321 | Based on what you provide on the command line, ``runqemu`` does a | ||
322 | good job of figuring out what you are trying to do. For example, by | ||
323 | default, QEMU looks for the most recently built image according to the | ||
324 | timestamp when it needs to look for an image. Minimally, through the use | ||
325 | of options, you must provide either a machine name, a virtual machine | ||
326 | image (``*wic.vmdk``), or a kernel image (``*.bin``). | ||
327 | |||
328 | Following is the command-line help output for the ``runqemu`` command: | ||
329 | :: | ||
330 | |||
331 | $ runqemu --help | ||
332 | |||
333 | Usage: you can run this script with any valid combination | ||
334 | of the following environment variables (in any order): | ||
335 | KERNEL - the kernel image file to use | ||
336 | ROOTFS - the rootfs image file or nfsroot directory to use | ||
337 | MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified) | ||
338 | Simplified QEMU command-line options can be passed with: | ||
339 | nographic - disable video console | ||
340 | serial - enable a serial console on /dev/ttyS0 | ||
341 | slirp - enable user networking, no root privileges is required | ||
342 | kvm - enable KVM when running x86/x86_64 (VT-capable CPU required) | ||
343 | kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required) | ||
344 | publicvnc - enable a VNC server open to all hosts | ||
345 | audio - enable audio | ||
346 | [*/]ovmf* - OVMF firmware file or base name for booting with UEFI | ||
347 | tcpserial=<port> - specify tcp serial port number | ||
348 | biosdir=<dir> - specify custom bios dir | ||
349 | biosfilename=<filename> - specify bios filename | ||
350 | qemuparams=<xyz> - specify custom parameters to QEMU | ||
351 | bootparams=<xyz> - specify custom kernel parameters during boot | ||
352 | help, -h, --help: print this text | ||
353 | |||
354 | Examples: | ||
355 | runqemu | ||
356 | runqemu qemuarm | ||
357 | runqemu tmp/deploy/images/qemuarm | ||
358 | runqemu tmp/deploy/images/qemux86/<qemuboot.conf> | ||
359 | runqemu qemux86-64 core-image-sato ext4 | ||
360 | runqemu qemux86-64 wic-image-minimal wic | ||
361 | runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial | ||
362 | runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... | ||
363 | runqemu qemux86 qemuparams="-m 256" | ||
364 | runqemu qemux86 bootparams="psplash=false" | ||
365 | runqemu path/to/<image>-<machine>.wic | ||
366 | runqemu path/to/<image>-<machine>.wic.vmdk | ||
367 | |||
368 | ``runqemu`` Command-Line Options | ||
369 | ================================ | ||
370 | |||
371 | Following is a description of ``runqemu`` options you can provide on the | ||
372 | command line: | ||
373 | |||
374 | .. note:: | ||
375 | |||
376 | If you do provide some "illegal" option combination or perhaps you do | ||
377 | not provide enough in the way of options, ``runqemu`` | ||
378 | provides appropriate error messaging to help you correct the problem. | ||
379 | |||
380 | - `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm", | ||
381 | "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or | ||
382 | "qemux86-64". | ||
383 | |||
384 | - `VM`: The virtual machine image, which must be a ``.wic.vmdk`` | ||
385 | file. Use this option when you want to boot a ``.wic.vmdk`` image. | ||
386 | The image filename you provide must contain one of the following | ||
387 | strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64", | ||
388 | "qemumips", "qemuppc", or "qemush4". | ||
389 | |||
390 | - `ROOTFS`: A root filesystem that has one of the following filetype | ||
391 | extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If | ||
392 | the filename you provide for this option uses "nfs", it must provide | ||
393 | an explicit root filesystem path. | ||
394 | |||
395 | - `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a | ||
396 | ``.bin`` file, ``runqemu`` detects it and assumes the file is a | ||
397 | kernel image. | ||
398 | |||
399 | - `MACHINE`: The architecture of the QEMU machine, which must be one of | ||
400 | the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64", | ||
401 | "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH | ||
402 | options are basically identical. If you do not provide a MACHINE | ||
403 | option, ``runqemu`` tries to determine it based on other options. | ||
404 | |||
405 | - ``ramfs``: Indicates you are booting an initial RAM disk (initramfs) | ||
406 | image, which means the ``FSTYPE`` is ``cpio.gz``. | ||
407 | |||
408 | - ``iso``: Indicates you are booting an ISO image, which means the | ||
409 | ``FSTYPE`` is ``.iso``. | ||
410 | |||
411 | - ``nographic``: Disables the video console, which sets the console to | ||
412 | "ttys0". This option is useful when you have logged into a server and | ||
413 | you do not want to disable forwarding from the X Window System (X11) | ||
414 | to your workstation or laptop. | ||
415 | |||
416 | - ``serial``: Enables a serial console on ``/dev/ttyS0``. | ||
417 | |||
418 | - ``biosdir``: Establishes a custom directory for BIOS, VGA BIOS and | ||
419 | keymaps. | ||
420 | |||
421 | - ``biosfilename``: Establishes a custom BIOS name. | ||
422 | |||
423 | - ``qemuparams=\"xyz\"``: Specifies custom QEMU parameters. Use this | ||
424 | option to pass options other than the simple "kvm" and "serial" | ||
425 | options. | ||
426 | |||
427 | - ``bootparams=\"xyz\"``: Specifies custom boot parameters for the | ||
428 | kernel. | ||
429 | |||
430 | - ``audio``: Enables audio in QEMU. The MACHINE option must be either | ||
431 | "qemux86" or "qemux86-64" in order for audio to be enabled. | ||
432 | Additionally, the ``snd_intel8x0`` or ``snd_ens1370`` driver must be | ||
433 | installed in linux guest. | ||
434 | |||
435 | - ``slirp``: Enables "slirp" networking, which is a different way of | ||
436 | networking that does not need root access but also is not as easy to | ||
437 | use or comprehensive as the default. | ||
438 | |||
439 | - ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU | ||
440 | architectures. For KVM to work, all the following conditions must be | ||
441 | met: | ||
442 | |||
443 | - Your MACHINE must be either qemux86" or "qemux86-64". | ||
444 | |||
445 | - Your build host has to have the KVM modules installed, which are | ||
446 | ``/dev/kvm``. | ||
447 | |||
448 | - The build host ``/dev/kvm`` directory has to be both writable and | ||
449 | readable. | ||
450 | |||
451 | - ``kvm-vhost``: Enables KVM with VHOST support when running "qemux86" | ||
452 | or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the | ||
453 | following conditions must be met: | ||
454 | |||
455 | - `kvm <#kvm-cond>`__ option conditions must be met. | ||
456 | |||
457 | - Your build host has to have virtio net device, which are | ||
458 | ``/dev/vhost-net``. | ||
459 | |||
460 | - The build host ``/dev/vhost-net`` directory has to be either | ||
461 | readable or writable and "slirp-enabled". | ||
462 | |||
463 | - ``publicvnc``: Enables a VNC server open to all hosts. | ||