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