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