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