1Introduction 2============ 3 4Virtualisation Accelerators 5--------------------------- 6 7QEMU's system emulation provides a virtual model of a machine (CPU, 8memory and emulated devices) to run a guest OS. It supports a number 9of hypervisors (known as accelerators) as well as a JIT known as the 10Tiny Code Generator (TCG) capable of emulating many CPUs. 11 12.. list-table:: Supported Accelerators 13 :header-rows: 1 14 15 * - Accelerator 16 - Host OS 17 - Host Architectures 18 * - KVM 19 - Linux 20 - Arm (64 bit only), MIPS, PPC, RISC-V, s390x, x86 21 * - Xen 22 - Linux (as dom0) 23 - Arm, x86 24 * - Intel HAXM (hax) 25 - Linux, Windows 26 - x86 27 * - Hypervisor Framework (hvf) 28 - MacOS 29 - x86 (64 bit only), Arm (64 bit only) 30 * - Windows Hypervisor Platform (whpx) 31 - Windows 32 - x86 33 * - NetBSD Virtual Machine Monitor (nvmm) 34 - NetBSD 35 - x86 36 * - Tiny Code Generator (tcg) 37 - Linux, other POSIX, Windows, MacOS 38 - Arm, x86, Loongarch64, MIPS, PPC, s390x, Sparc64 39 40Feature Overview 41---------------- 42 43System emulation provides a wide range of device models to emulate 44various hardware components you may want to add to your machine. This 45includes a wide number of VirtIO devices which are specifically tuned 46for efficient operation under virtualisation. Some of the device 47emulation can be offloaded from the main QEMU process using either 48vhost-user (for VirtIO) or :ref:`Multi-process QEMU`. If the platform 49supports it QEMU also supports directly passing devices through to 50guest VMs to eliminate the device emulation overhead. See 51:ref:`device-emulation` for more details. 52 53There is a full :ref:`featured block layer<Live Block Operations>` 54which allows for construction of complex storage topology which can be 55stacked across multiple layers supporting redirection, networking, 56snapshots and migration support. 57 58The flexible ``chardev`` system allows for handling IO from character 59like devices using stdio, files, unix sockets and TCP networking. 60 61QEMU provides a number of management interfaces including a line based 62:ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to 63dynamically add and remove devices as well as introspect the system 64state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well 65defined, versioned, machine usable API that presents a rich interface 66to other tools to create, control and manage Virtual Machines. This is 67the interface used by higher level tools interfaces such as `Virt 68Manager <https://virt-manager.org/>`_ using the `libvirt framework 69<https://libvirt.org>`_. 70 71For the common accelerators QEMU, supported debugging with its 72:ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug 73system software images. 74 75Running 76------- 77 78QEMU provides a rich and complex API which can be overwhelming to 79understand. While some architectures can boot something with just a 80disk image, those examples elide a lot of details with defaults that 81may not be optimal for modern systems. 82 83For a non-x86 system where we emulate a broad range of machine types, 84the command lines are generally more explicit in defining the machine 85and boot behaviour. You will find often find example command lines in 86the :ref:`system-targets-ref` section of the manual. 87 88While the project doesn't want to discourage users from using the 89command line to launch VMs, we do want to highlight that there are a 90number of projects dedicated to providing a more user friendly 91experience. Those built around the ``libvirt`` framework can make use 92of feature probing to build modern VM images tailored to run on the 93hardware you have. 94 95That said, the general form of a QEMU command line can be expressed 96as: 97 98.. parsed-literal:: 99 100 $ |qemu_system| [machine opts] \\ 101 [cpu opts] \\ 102 [accelerator opts] \\ 103 [device opts] \\ 104 [backend opts] \\ 105 [interface opts] \\ 106 [boot opts] 107 108Most options will generate some help information. So for example: 109 110.. parsed-literal:: 111 112 $ |qemu_system| -M help 113 114will list the machine types supported by that QEMU binary. ``help`` 115can also be passed as an argument to another option. For example: 116 117.. parsed-literal:: 118 119 $ |qemu_system| -device scsi-hd,help 120 121will list the arguments and their default values of additional options 122that can control the behaviour of the ``scsi-hd`` device. 123 124.. list-table:: Options Overview 125 :header-rows: 1 126 :widths: 10, 90 127 128 * - Options 129 - 130 * - Machine 131 - Define the machine type, amount of memory etc 132 * - CPU 133 - Type and number/topology of vCPUs. Most accelerators offer 134 a ``host`` cpu option which simply passes through your host CPU 135 configuration without filtering out any features. 136 * - Accelerator 137 - This will depend on the hypervisor you run. Note that the 138 default is TCG, which is purely emulated, so you must specify an 139 accelerator type to take advantage of hardware virtualization. 140 * - Devices 141 - Additional devices that are not defined by default with the 142 machine type. 143 * - Backends 144 - Backends are how QEMU deals with the guest's data, for example 145 how a block device is stored, how network devices see the 146 network or how a serial device is directed to the outside world. 147 * - Interfaces 148 - How the system is displayed, how it is managed and controlled or 149 debugged. 150 * - Boot 151 - How the system boots, via firmware or direct kernel boot. 152 153In the following example we first define a ``virt`` machine which is a 154general purpose platform for running Aarch64 guests. We enable 155virtualisation so we can use KVM inside the emulated guest. As the 156``virt`` machine comes with some built in pflash devices we give them 157names so we can override the defaults later. 158 159.. code:: 160 161 $ qemu-system-aarch64 \ 162 -machine type=virt,virtualization=on,pflash0=rom,pflash1=efivars \ 163 -m 4096 \ 164 165We then define the 4 vCPUs using the ``max`` option which gives us all 166the Arm features QEMU is capable of emulating. We enable a more 167emulation friendly implementation of Arm's pointer authentication 168algorithm. We explicitly specify TCG acceleration even though QEMU 169would default to it anyway. 170 171.. code:: 172 173 -cpu max,pauth-impdef=on \ 174 -smp 4 \ 175 -accel tcg \ 176 177As the ``virt`` platform doesn't have any default network or storage 178devices we need to define them. We give them ids so we can link them 179with the backend later on. 180 181.. code:: 182 183 -device virtio-net-pci,netdev=unet \ 184 -device virtio-scsi-pci \ 185 -device scsi-hd,drive=hd \ 186 187We connect the user-mode networking to our network device. As 188user-mode networking isn't directly accessible from the outside world 189we forward localhost port 2222 to the ssh port on the guest. 190 191.. code:: 192 193 -netdev user,id=unet,hostfwd=tcp::2222-:22 \ 194 195We connect the guest visible block device to an LVM partition we have 196set aside for our guest. 197 198.. code:: 199 200 -blockdev driver=raw,node-name=hd,file.driver=host_device,file.filename=/dev/lvm-disk/debian-bullseye-arm64 \ 201 202We then tell QEMU to multiplex the :ref:`QEMU monitor` with the serial 203port output (we can switch between the two using :ref:`keys in the 204character backend multiplexer`). As there is no default graphical 205device we disable the display as we can work entirely in the terminal. 206 207.. code:: 208 209 -serial mon:stdio \ 210 -display none \ 211 212Finally we override the default firmware to ensure we have some 213storage for EFI to persist its configuration. That firmware is 214responsible for finding the disk, booting grub and eventually running 215our system. 216 217.. code:: 218 219 -blockdev node-name=rom,driver=file,filename=(pwd)/pc-bios/edk2-aarch64-code.fd,read-only=true \ 220 -blockdev node-name=efivars,driver=file,filename=$HOME/images/qemu-arm64-efivars 221