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 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 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 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 $ 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 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 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 874. *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 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 137 must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option. 138 :: 139 140 $ runqemu ext4 141 142 - This example specifies to boot a virtual machine image 143 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` 144 determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and 145 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 183Running 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``: 202 203 .. code-block:: none 204 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: 212 213 .. code-block:: none 214 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 222 - To start the NFS share:: 223 224 runqemu-export-rootfs start file-system-location 225 226 - To stop the NFS share:: 227 228 runqemu-export-rootfs stop file-system-location 229 230 - To restart the NFS share:: 231 232 runqemu-export-rootfs restart file-system-location 233 234QEMU 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 255QEMU 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 278 There are several mechanisms to connect to the system running 279 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 289 - SSH servers are available in some QEMU images. The ``core-image-sato`` 290 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. 303 See the 304 ":ref:`dev-manual/qemu:running under a network file system (nfs) server`" 305 section for more information. 306 307QEMU Command-Line Syntax 308======================== 309 310The basic ``runqemu`` command syntax is as follows:: 311 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 321Following is the command-line help output for the ``runqemu`` command:: 322 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 360``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 369 not provide enough in the way of options, ``runqemu`` 370 provides appropriate error messaging to help you correct the problem. 371 372- `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm", 373 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or 374 "qemux86-64". 375 376- `VM`: The virtual machine image, which must be a ``.wic.vmdk`` 377 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 382- `ROOTFS`: A root filesystem that has one of the following filetype 383 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 387- `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a 388 ``.bin`` file, ``runqemu`` detects it and assumes the file is a 389 kernel image. 390 391- `MACHINE`: The architecture of the QEMU machine, which must be one of 392 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 447 - ``kvm`` option conditions defined above must be met. 448 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. 456