blob: 88a63c18083812baa9ce3ce465f58738ac887788 [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
Andrew Geisslerc926e172021-05-07 16:11:35 -050058 environment script (i.e. :ref:`structure-core-script`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050059
Andrew Geissler95ac1b82021-03-31 14:34:31 -050060 $ cd poky
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061 $ source oe-init-build-env
62
63 - If you installed a cross-toolchain, you can run the script that
64 initializes the toolchain. For example, the following commands run
Andrew Geisslerc926e172021-05-07 16:11:35 -050065 the initialization script from the default ``poky_sdk`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050066
Andrew Geissler95ac1b82021-03-31 14:34:31 -050067 . poky_sdk/environment-setup-core2-64-poky-linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068
693. *Ensure the Artifacts are in Place:* You need to be sure you have a
70 pre-built kernel that will boot in QEMU. You also need the target
71 root filesystem for your target machine's architecture:
72
73 - If you have previously built an image for QEMU (e.g. ``qemux86``,
74 ``qemuarm``, and so forth), then the artifacts are in place in
75 your :term:`Build Directory`.
76
77 - If you have not built an image, you can go to the
Andrew Geissler09209ee2020-12-13 08:44:15 -060078 :yocto_dl:`machines/qemu </releases/yocto/yocto-&DISTRO;/machines/qemu/>` area and download a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050079 pre-built image that matches your architecture and can be run on
80 QEMU.
81
Andrew Geissler09209ee2020-12-13 08:44:15 -060082 See the ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083 section in the Yocto Project Application Development and the
84 Extensible Software Development Kit (eSDK) manual for information on
85 how to extract a root filesystem.
86
Andrew Geisslerc926e172021-05-07 16:11:35 -0500874. *Run QEMU:* The basic ``runqemu`` command syntax is as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088
89 $ runqemu [option ] [...]
90
91 Based on what you provide on the command
92 line, ``runqemu`` does a good job of figuring out what you are trying
93 to do. For example, by default, QEMU looks for the most recently
94 built image according to the timestamp when it needs to look for an
95 image. Minimally, through the use of options, you must provide either
96 a machine name, a virtual machine image (``*wic.vmdk``), or a kernel
97 image (``*.bin``).
98
99 Here are some additional examples to help illustrate further QEMU:
100
101 - This example starts QEMU with MACHINE set to "qemux86-64".
102 Assuming a standard
103 :term:`Build Directory`, ``runqemu``
104 automatically finds the ``bzImage-qemux86-64.bin`` image file and
105 the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4``
106 (assuming the current build created a ``core-image-minimal``
107 image).
108
109 .. note::
110
111 When more than one image with the same name exists, QEMU finds
112 and uses the most recently built image according to the
113 timestamp.
114
115 ::
116
117 $ runqemu qemux86-64
118
119 - This example produces the exact same results as the previous
120 example. This command, however, specifically provides the image
121 and root filesystem type.
122 ::
123
124 $ runqemu qemux86-64 core-image-minimal ext4
125
126 - This example specifies to boot an initial RAM disk image and to
127 enable audio in QEMU. For this case, ``runqemu`` set the internal
128 variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
129 an appropriate driver must be installed (see the previous
130 description for the ``audio`` option for more information).
131 ::
132
133 $ runqemu qemux86-64 ramfs audio
134
135 - This example does not provide enough information for QEMU to
136 launch. While the command does provide a root filesystem type, it
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500137 must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500138 ::
139
140 $ runqemu ext4
141
142 - This example specifies to boot a virtual machine image
143 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500144 determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500145 the root filesystem type to be "vmdk".
146 ::
147
148 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
149
150Switching Between Consoles
151==========================
152
153When booting or running QEMU, you can switch between supported consoles
154by using Ctrl+Alt+number. For example, Ctrl+Alt+3 switches you to the
155serial console as long as that console is enabled. Being able to switch
156consoles is helpful, for example, if the main QEMU console breaks for
157some reason.
158
159.. note::
160
161 Usually, "2" gets you to the main console and "3" gets you to the
162 serial console.
163
164Removing the Splash Screen
165==========================
166
167You can remove the splash screen when QEMU is booting by using Alt+left.
168Removing the splash screen allows you to see what is happening in the
169background.
170
171Disabling the Cursor Grab
172=========================
173
174The default QEMU integration captures the cursor within the main window.
175It does this since standard mouse devices only provide relative input
176and not absolute coordinates. You then have to break out of the grab
177using the "Ctrl+Alt" key combination. However, the Yocto Project's
178integration of QEMU enables the wacom USB touch pad driver by default to
179allow input of absolute coordinates. This default means that the mouse
180can enter and leave the main window without the grab taking effect
181leading to a better user experience.
182
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183Running Under a Network File System (NFS) Server
184================================================
185
186One method for running QEMU is to run it on an NFS server. This is
187useful when you need to access the same file system from both the build
188and the emulated system at the same time. It is also worth noting that
189the system does not need root privileges to run. It uses a user space
190NFS server to avoid that. Follow these steps to set up for running QEMU
191using an NFS server.
192
1931. *Extract a Root Filesystem:* Once you are able to run QEMU in your
194 environment, you can use the ``runqemu-extract-sdk`` script, which is
195 located in the ``scripts`` directory along with the ``runqemu``
196 script.
197
198 The ``runqemu-extract-sdk`` takes a root filesystem tarball and
199 extracts it into a location that you specify. Here is an example that
200 takes a file system and extracts it to a directory named
201 ``test-nfs``:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500202
203 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500204
205 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
206
2072. *Start QEMU:* Once you have extracted the file system, you can run
208 ``runqemu`` normally with the additional location of the file system.
209 You can then also make changes to the files within ``./test-nfs`` and
210 see those changes appear in the image in real time. Here is an
211 example using the ``qemux86`` image:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500212
213 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214
215 runqemu qemux86-64 ./test-nfs
216
217.. note::
218
219 Should you need to start, stop, or restart the NFS share, you can use
220 the following commands:
221
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700222 - To start the NFS share::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500224 runqemu-export-rootfs start file-system-location
225
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700226 - To stop the NFS share::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500227
228 runqemu-export-rootfs stop file-system-location
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500229
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700230 - To restart the NFS share::
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500231
232 runqemu-export-rootfs restart file-system-location
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500233
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234QEMU CPU Compatibility Under KVM
235================================
236
237By default, the QEMU build compiles for and targets 64-bit and x86 Intel
238Core2 Duo processors and 32-bit x86 Intel Pentium II processors. QEMU
239builds for and targets these CPU types because they display a broad
240range of CPU feature compatibility with many commonly used CPUs.
241
242Despite this broad range of compatibility, the CPUs could support a
243feature that your host CPU does not support. Although this situation is
244not a problem when QEMU uses software emulation of the feature, it can
245be a problem when QEMU is running with KVM enabled. Specifically,
246software compiled with a certain CPU feature crashes when run on a CPU
247under KVM that does not support that feature. To work around this
248problem, you can override QEMU's runtime CPU setting by changing the
249``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the
250:term:`Build Directory` ``deploy/image``
251directory. This setting specifies a ``-cpu`` option passed into QEMU in
252the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of
253available supported CPU types.
254
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500255QEMU Performance
256================
257
258Using QEMU to emulate your hardware can result in speed issues depending
259on the target and host architecture mix. For example, using the
260``qemux86`` image in the emulator on an Intel-based 32-bit (x86) host
261machine is fast because the target and host architectures match. On the
262other hand, using the ``qemuarm`` image on the same Intel-based host can
263be slower. But, you still achieve faithful emulation of ARM-specific
264issues.
265
266To speed things up, the QEMU images support using ``distcc`` to call a
267cross-compiler outside the emulated system. If you used ``runqemu`` to
268start QEMU, and the ``distccd`` application is present on the host
269system, any BitBake cross-compiling toolchain available from the build
270system is automatically used from within QEMU simply by calling
271``distcc``. You can accomplish this by defining the cross-compiler
272variable (e.g. ``export CC="distcc"``). Alternatively, if you are using
273a suitable SDK image or the appropriate stand-alone toolchain is
274present, the toolchain is also automatically used.
275
276.. note::
277
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700278 There are several mechanisms to connect to the system running
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279 on the QEMU emulator:
280
281 - QEMU provides a framebuffer interface that makes standard consoles
282 available.
283
284 - Generally, headless embedded devices have a serial port. If so,
285 you can configure the operating system of the running image to use
286 that port to run a console. The connection uses standard IP
287 networking.
288
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700289 - SSH servers are available in some QEMU images. The ``core-image-sato``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500290 QEMU image has a Dropbear secure shell (SSH) server that runs with
291 the root password disabled. The ``core-image-full-cmdline`` and
292 ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.
293 Including these SSH servers allow you to use standard ``ssh`` and
294 ``scp`` commands. The ``core-image-minimal`` QEMU image, however,
295 contains no SSH server.
296
297 - You can use a provided, user-space NFS server to boot the QEMU
298 session using a local copy of the root filesystem on the host. In
299 order to make this connection, you must extract a root filesystem
300 tarball by using the ``runqemu-extract-sdk`` command. After
301 running the command, you must then point the ``runqemu`` script to
302 the extracted directory instead of a root filesystem image file.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500303 See the
304 ":ref:`dev-manual/qemu:running under a network file system (nfs) server`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500305 section for more information.
306
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307QEMU Command-Line Syntax
308========================
309
Andrew Geisslerc926e172021-05-07 16:11:35 -0500310The basic ``runqemu`` command syntax is as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500311
312 $ runqemu [option ] [...]
313
314Based on what you provide on the command line, ``runqemu`` does a
315good job of figuring out what you are trying to do. For example, by
316default, QEMU looks for the most recently built image according to the
317timestamp when it needs to look for an image. Minimally, through the use
318of options, you must provide either a machine name, a virtual machine
319image (``*wic.vmdk``), or a kernel image (``*.bin``).
320
Andrew Geisslerc926e172021-05-07 16:11:35 -0500321Following is the command-line help output for the ``runqemu`` command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500322
323 $ runqemu --help
324
325 Usage: you can run this script with any valid combination
326 of the following environment variables (in any order):
327 KERNEL - the kernel image file to use
328 ROOTFS - the rootfs image file or nfsroot directory to use
329 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
330 Simplified QEMU command-line options can be passed with:
331 nographic - disable video console
332 serial - enable a serial console on /dev/ttyS0
333 slirp - enable user networking, no root privileges is required
334 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
335 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
336 publicvnc - enable a VNC server open to all hosts
337 audio - enable audio
338 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
339 tcpserial=<port> - specify tcp serial port number
340 biosdir=<dir> - specify custom bios dir
341 biosfilename=<filename> - specify bios filename
342 qemuparams=<xyz> - specify custom parameters to QEMU
343 bootparams=<xyz> - specify custom kernel parameters during boot
344 help, -h, --help: print this text
345
346 Examples:
347 runqemu
348 runqemu qemuarm
349 runqemu tmp/deploy/images/qemuarm
350 runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
351 runqemu qemux86-64 core-image-sato ext4
352 runqemu qemux86-64 wic-image-minimal wic
353 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
354 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
355 runqemu qemux86 qemuparams="-m 256"
356 runqemu qemux86 bootparams="psplash=false"
357 runqemu path/to/<image>-<machine>.wic
358 runqemu path/to/<image>-<machine>.wic.vmdk
359
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500360``runqemu`` Command-Line Options
361================================
362
363Following is a description of ``runqemu`` options you can provide on the
364command line:
365
366.. note::
367
368 If you do provide some "illegal" option combination or perhaps you do
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500369 not provide enough in the way of options, ``runqemu``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370 provides appropriate error messaging to help you correct the problem.
371
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500372- `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm",
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500373 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
374 "qemux86-64".
375
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500376- `VM`: The virtual machine image, which must be a ``.wic.vmdk``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377 file. Use this option when you want to boot a ``.wic.vmdk`` image.
378 The image filename you provide must contain one of the following
379 strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64",
380 "qemumips", "qemuppc", or "qemush4".
381
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500382- `ROOTFS`: A root filesystem that has one of the following filetype
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500383 extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If
384 the filename you provide for this option uses "nfs", it must provide
385 an explicit root filesystem path.
386
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500387- `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388 ``.bin`` file, ``runqemu`` detects it and assumes the file is a
389 kernel image.
390
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500391- `MACHINE`: The architecture of the QEMU machine, which must be one of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500392 the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
393 "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH
394 options are basically identical. If you do not provide a MACHINE
395 option, ``runqemu`` tries to determine it based on other options.
396
397- ``ramfs``: Indicates you are booting an initial RAM disk (initramfs)
398 image, which means the ``FSTYPE`` is ``cpio.gz``.
399
400- ``iso``: Indicates you are booting an ISO image, which means the
401 ``FSTYPE`` is ``.iso``.
402
403- ``nographic``: Disables the video console, which sets the console to
404 "ttys0". This option is useful when you have logged into a server and
405 you do not want to disable forwarding from the X Window System (X11)
406 to your workstation or laptop.
407
408- ``serial``: Enables a serial console on ``/dev/ttyS0``.
409
410- ``biosdir``: Establishes a custom directory for BIOS, VGA BIOS and
411 keymaps.
412
413- ``biosfilename``: Establishes a custom BIOS name.
414
415- ``qemuparams=\"xyz\"``: Specifies custom QEMU parameters. Use this
416 option to pass options other than the simple "kvm" and "serial"
417 options.
418
419- ``bootparams=\"xyz\"``: Specifies custom boot parameters for the
420 kernel.
421
422- ``audio``: Enables audio in QEMU. The MACHINE option must be either
423 "qemux86" or "qemux86-64" in order for audio to be enabled.
424 Additionally, the ``snd_intel8x0`` or ``snd_ens1370`` driver must be
425 installed in linux guest.
426
427- ``slirp``: Enables "slirp" networking, which is a different way of
428 networking that does not need root access but also is not as easy to
429 use or comprehensive as the default.
430
431- ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU
432 architectures. For KVM to work, all the following conditions must be
433 met:
434
435 - Your MACHINE must be either qemux86" or "qemux86-64".
436
437 - Your build host has to have the KVM modules installed, which are
438 ``/dev/kvm``.
439
440 - The build host ``/dev/kvm`` directory has to be both writable and
441 readable.
442
443- ``kvm-vhost``: Enables KVM with VHOST support when running "qemux86"
444 or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the
445 following conditions must be met:
446
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500447 - ``kvm`` option conditions defined above must be met.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500448
449 - Your build host has to have virtio net device, which are
450 ``/dev/vhost-net``.
451
452 - The build host ``/dev/vhost-net`` directory has to be either
453 readable or writable and "slirp-enabled".
454
455- ``publicvnc``: Enables a VNC server open to all hosts.