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/&DISTRO_REL_LATEST_TAG;/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 the 284 root password disabled. The ``core-image-full-cmdline`` QEMU image has 285 OpenSSH instead of Dropbear. Including these SSH servers allow you to use 286 standard ``ssh`` and ``scp`` commands. The ``core-image-minimal`` QEMU 287 image, however, contains no SSH server. 288 289 - You can use a provided, user-space NFS server to boot the QEMU 290 session using a local copy of the root filesystem on the host. In 291 order to make this connection, you must extract a root filesystem 292 tarball by using the ``runqemu-extract-sdk`` command. After 293 running the command, you must then point the ``runqemu`` script to 294 the extracted directory instead of a root filesystem image file. 295 See the 296 ":ref:`dev-manual/qemu:running under a network file system (nfs) server`" 297 section for more information. 298 299QEMU Command-Line Syntax 300======================== 301 302The basic ``runqemu`` command syntax is as follows:: 303 304 $ runqemu [option ] [...] 305 306Based on what you provide on the command line, ``runqemu`` does a 307good job of figuring out what you are trying to do. For example, by 308default, QEMU looks for the most recently built image according to the 309timestamp when it needs to look for an image. Minimally, through the use 310of options, you must provide either a machine name, a virtual machine 311image (``*wic.vmdk``), or a kernel image (``*.bin``). 312 313Here is the command-line help output for the ``runqemu`` command:: 314 315 $ runqemu --help 316 317 Usage: you can run this script with any valid combination 318 of the following environment variables (in any order): 319 KERNEL - the kernel image file to use 320 ROOTFS - the rootfs image file or nfsroot directory to use 321 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified) 322 Simplified QEMU command-line options can be passed with: 323 nographic - disable video console 324 serial - enable a serial console on /dev/ttyS0 325 slirp - enable user networking, no root privileges required 326 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required) 327 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required) 328 publicvnc - enable a VNC server open to all hosts 329 audio - enable audio 330 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI 331 tcpserial=<port> - specify tcp serial port number 332 biosdir=<dir> - specify custom bios dir 333 biosfilename=<filename> - specify bios filename 334 qemuparams=<xyz> - specify custom parameters to QEMU 335 bootparams=<xyz> - specify custom kernel parameters during boot 336 help, -h, --help: print this text 337 338 Examples: 339 runqemu 340 runqemu qemuarm 341 runqemu tmp/deploy/images/qemuarm 342 runqemu tmp/deploy/images/qemux86/<qemuboot.conf> 343 runqemu qemux86-64 core-image-sato ext4 344 runqemu qemux86-64 wic-image-minimal wic 345 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial 346 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... 347 runqemu qemux86 qemuparams="-m 256" 348 runqemu qemux86 bootparams="psplash=false" 349 runqemu path/to/<image>-<machine>.wic 350 runqemu path/to/<image>-<machine>.wic.vmdk 351 352``runqemu`` Command-Line Options 353================================ 354 355Here is a description of ``runqemu`` options you can provide on the 356command line: 357 358.. note:: 359 360 If you do provide some "illegal" option combination or perhaps you do 361 not provide enough in the way of options, ``runqemu`` 362 provides appropriate error messaging to help you correct the problem. 363 364- `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm", 365 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or 366 "qemux86-64". 367 368- `VM`: The virtual machine image, which must be a ``.wic.vmdk`` 369 file. Use this option when you want to boot a ``.wic.vmdk`` image. 370 371- `ROOTFS`: A root filesystem that has one of the following filetype 372 extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If 373 the filename you provide for this option uses "nfs", it must provide 374 an explicit root filesystem path. 375 376- `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a 377 ``.bin`` file, ``runqemu`` detects it and assumes the file is a 378 kernel image. 379 380- `MACHINE`: The architecture of the QEMU machine, which must be one of 381 the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64", 382 "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH 383 options are basically identical. If you do not provide a MACHINE 384 option, ``runqemu`` tries to determine it based on other options. 385 386- ``ramfs``: Indicates you are booting an :term:`Initramfs` 387 image, which means the ``FSTYPE`` is ``cpio.gz``. 388 389- ``iso``: Indicates you are booting an ISO image, which means the 390 ``FSTYPE`` is ``.iso``. 391 392- ``nographic``: Disables the video console, which sets the console to 393 "ttys0". This option is useful when you have logged into a server and 394 you do not want to disable forwarding from the X Window System (X11) 395 to your workstation or laptop. 396 397- ``serial``: Enables a serial console on ``/dev/ttyS0``. 398 399- ``biosdir``: Establishes a custom directory for BIOS, VGA BIOS and 400 keymaps. 401 402- ``biosfilename``: Establishes a custom BIOS name. 403 404- ``qemuparams=\"xyz\"``: Specifies custom QEMU parameters. Use this 405 option to pass options other than the simple "kvm" and "serial" 406 options. 407 408- ``bootparams=\"xyz\"``: Specifies custom boot parameters for the 409 kernel. 410 411- ``audio``: Enables audio in QEMU. The MACHINE option must be either 412 "qemux86" or "qemux86-64" in order for audio to be enabled. 413 Additionally, the ``snd_intel8x0`` or ``snd_ens1370`` driver must be 414 installed in linux guest. 415 416- ``slirp``: Enables "slirp" networking, which is a different way of 417 networking that does not need root access but also is not as easy to 418 use or comprehensive as the default. 419 420 Using ``slirp`` by default will forward the guest machine's 421 22 and 23 TCP ports to host machine's 2222 and 2323 ports 422 (or the next free ports). Specific forwarding rules can be configured 423 by setting ``QB_SLIRP_OPT`` as environment variable or in ``qemuboot.conf`` 424 in the :term:`Build Directory` ``deploy/image`` directory. 425 Examples:: 426 427 QB_SLIRP_OPT="-netdev user,id=net0,hostfwd=tcp::8080-:80" 428 429 QB_SLIRP_OPT="-netdev user,id=net0,hostfwd=tcp::8080-:80,hostfwd=tcp::2222-:22" 430 431 The first example forwards TCP port 80 from the emulated system to 432 port 8080 (or the next free port) on the host system, 433 allowing access to an http server running in QEMU from 434 ``http://<host ip>:8080/``. 435 436 The second example does the same, but also forwards TCP port 22 on the 437 guest system to 2222 (or the next free port) on the host system, 438 allowing ssh access to the emulated system using 439 ``ssh -P 2222 <user>@<host ip>``. 440 441 Keep in mind that proper configuration of firewall software is required. 442 443- ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU 444 architectures. For KVM to work, all the following conditions must be 445 met: 446 447 - Your MACHINE must be either qemux86" or "qemux86-64". 448 449 - Your build host has to have the KVM modules installed, which are 450 ``/dev/kvm``. 451 452 - The build host ``/dev/kvm`` directory has to be both writable and 453 readable. 454 455- ``kvm-vhost``: Enables KVM with VHOST support when running "qemux86" 456 or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the 457 following conditions must be met: 458 459 - ``kvm`` option conditions defined above must be met. 460 461 - Your build host has to have virtio net device, which are 462 ``/dev/vhost-net``. 463 464 - The build host ``/dev/vhost-net`` directory has to be either 465 readable or writable and "slirp-enabled". 466 467- ``publicvnc``: Enables a VNC server open to all hosts. 468