blob: c6bb9e9776c2953428cf6e473e8109007e854787 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*******************************
4Using the Quick EMUlator (QEMU)
5*******************************
6
7The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
8Open Source project as part of the Yocto Project development "tool set".
9This chapter provides both procedures that show you how to use the Quick
10EMUlator (QEMU) and other QEMU information helpful for development
11purposes.
12
Andrew Geisslerc9f78652020-09-18 14:11:35 -050013Overview
14========
15
16Within the context of the Yocto Project, QEMU is an emulator and
17virtualization machine that allows you to run a complete image you have
18built using the Yocto Project as just another task on your build system.
19QEMU is useful for running and testing images and applications on
20supported Yocto Project architectures without having actual hardware.
21Among other things, the Yocto Project uses QEMU to run automated Quality
22Assurance (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
28This section provides a brief reference for the Yocto Project
29implementation of QEMU.
30
31For official information and documentation on QEMU in general, see the
32following references:
33
Andrew Geissler4c19ea12020-10-27 13:52:24 -050034- `QEMU Website <https://wiki.qemu.org/Main_Page>`__\ *:* The official
Andrew Geisslerc9f78652020-09-18 14:11:35 -050035 website for the QEMU Open Source project.
36
Andrew Geissler4c19ea12020-10-27 13:52:24 -050037- `Documentation <https://wiki.qemu.org/Manual>`__\ *:* The QEMU user
Andrew Geisslerc9f78652020-09-18 14:11:35 -050038 manual.
39
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040Running QEMU
41============
42
43To use QEMU, you need to have QEMU installed and initialized as well as
44have the proper artifacts (i.e. image files and root filesystems)
45available. Follow these general steps to run QEMU:
46
471. *Install QEMU:* QEMU is made available with the Yocto Project a
48 number of ways. One method is to install a Software Development Kit
Andrew Geissler09209ee2020-12-13 08:44:15 -060049 (SDK). See ":ref:`sdk-manual/intro:the qemu emulator`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050 Yocto Project Application Development and the Extensible Software
51 Development Kit (eSDK) manual for information on how to install QEMU.
52
532. *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
Andrew Geissler95ac1b82021-03-31 14:34:31 -050061 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062 $ 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
Andrew Geissler95ac1b82021-03-31 14:34:31 -050069 . poky_sdk/environment-setup-core2-64-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -050070
713. *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
Andrew Geissler09209ee2020-12-13 08:44:15 -060080 :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu/>` area and download a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050081 pre-built image that matches your architecture and can be run on
82 QEMU.
83
Andrew Geissler09209ee2020-12-13 08:44:15 -060084 See the ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085 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
894. *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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500140 must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141 ::
142
143 $ runqemu ext4
144
145 - This example specifies to boot a virtual machine image
146 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500147 determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148 the root filesystem type to be "vmdk".
149 ::
150
151 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
152
153Switching Between Consoles
154==========================
155
156When booting or running QEMU, you can switch between supported consoles
157by using Ctrl+Alt+number. For example, Ctrl+Alt+3 switches you to the
158serial console as long as that console is enabled. Being able to switch
159consoles is helpful, for example, if the main QEMU console breaks for
160some reason.
161
162.. note::
163
164 Usually, "2" gets you to the main console and "3" gets you to the
165 serial console.
166
167Removing the Splash Screen
168==========================
169
170You can remove the splash screen when QEMU is booting by using Alt+left.
171Removing the splash screen allows you to see what is happening in the
172background.
173
174Disabling the Cursor Grab
175=========================
176
177The default QEMU integration captures the cursor within the main window.
178It does this since standard mouse devices only provide relative input
179and not absolute coordinates. You then have to break out of the grab
180using the "Ctrl+Alt" key combination. However, the Yocto Project's
181integration of QEMU enables the wacom USB touch pad driver by default to
182allow input of absolute coordinates. This default means that the mouse
183can enter and leave the main window without the grab taking effect
184leading to a better user experience.
185
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500186Running Under a Network File System (NFS) Server
187================================================
188
189One method for running QEMU is to run it on an NFS server. This is
190useful when you need to access the same file system from both the build
191and the emulated system at the same time. It is also worth noting that
192the system does not need root privileges to run. It uses a user space
193NFS server to avoid that. Follow these steps to set up for running QEMU
194using an NFS server.
195
1961. *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``:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500205
206 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500207
208 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
209
2102. *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:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500215
216 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217
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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500225 - The following command starts the NFS share:
226 ::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500227
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500228 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234
235 - The following command restarts the NFS share:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500236 ::
237
238 runqemu-export-rootfs restart file-system-location
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500240QEMU CPU Compatibility Under KVM
241================================
242
243By default, the QEMU build compiles for and targets 64-bit and x86 Intel
244Core2 Duo processors and 32-bit x86 Intel Pentium II processors. QEMU
245builds for and targets these CPU types because they display a broad
246range of CPU feature compatibility with many commonly used CPUs.
247
248Despite this broad range of compatibility, the CPUs could support a
249feature that your host CPU does not support. Although this situation is
250not a problem when QEMU uses software emulation of the feature, it can
251be a problem when QEMU is running with KVM enabled. Specifically,
252software compiled with a certain CPU feature crashes when run on a CPU
253under KVM that does not support that feature. To work around this
254problem, 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``
257directory. This setting specifies a ``-cpu`` option passed into QEMU in
258the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of
259available supported CPU types.
260
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261QEMU Performance
262================
263
264Using QEMU to emulate your hardware can result in speed issues depending
265on the target and host architecture mix. For example, using the
266``qemux86`` image in the emulator on an Intel-based 32-bit (x86) host
267machine is fast because the target and host architectures match. On the
268other hand, using the ``qemuarm`` image on the same Intel-based host can
269be slower. But, you still achieve faithful emulation of ARM-specific
270issues.
271
272To speed things up, the QEMU images support using ``distcc`` to call a
273cross-compiler outside the emulated system. If you used ``runqemu`` to
274start QEMU, and the ``distccd`` application is present on the host
275system, any BitBake cross-compiling toolchain available from the build
276system is automatically used from within QEMU simply by calling
277``distcc``. You can accomplish this by defining the cross-compiler
278variable (e.g. ``export CC="distcc"``). Alternatively, if you are using
279a suitable SDK image or the appropriate stand-alone toolchain is
280present, 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500313QEMU Command-Line Syntax
314========================
315
316The basic ``runqemu`` command syntax is as follows:
317::
318
319 $ runqemu [option ] [...]
320
321Based on what you provide on the command line, ``runqemu`` does a
322good job of figuring out what you are trying to do. For example, by
323default, QEMU looks for the most recently built image according to the
324timestamp when it needs to look for an image. Minimally, through the use
325of options, you must provide either a machine name, a virtual machine
326image (``*wic.vmdk``), or a kernel image (``*.bin``).
327
328Following 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368``runqemu`` Command-Line Options
369================================
370
371Following is a description of ``runqemu`` options you can provide on the
372command line:
373
374.. note::
375
376 If you do provide some "illegal" option combination or perhaps you do
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500377 not provide enough in the way of options, ``runqemu``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500378 provides appropriate error messaging to help you correct the problem.
379
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500380- `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm",
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500381 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
382 "qemux86-64".
383
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500384- `VM`: The virtual machine image, which must be a ``.wic.vmdk``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500390- `ROOTFS`: A root filesystem that has one of the following filetype
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500391 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500395- `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500396 ``.bin`` file, ``runqemu`` detects it and assumes the file is a
397 kernel image.
398
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500399- `MACHINE`: The architecture of the QEMU machine, which must be one of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500400 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.