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