docs/system/introduction.rst

   1 Introduction
   2 ============
   3
   4 Virtualisation Accelerators
   5 ---------------------------
   6
   7 QEMU's system emulation provides a virtual model of a machine (CPU,
   8 memory and emulated devices) to run a guest OS. It supports a number
   9 of hypervisors (known as accelerators) as well as a JIT known as the
  10 Tiny 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
  40 Feature Overview
  41 ----------------
  42
  43 System emulation provides a wide range of device models to emulate
  44 various hardware components you may want to add to your machine. This
  45 includes a wide number of VirtIO devices which are specifically tuned
  46 for efficient operation under virtualisation. Some of the device
  47 emulation can be offloaded from the main QEMU process using either
  48 vhost-user (for VirtIO) or :ref:`Multi-process QEMU`. If the platform
  49 supports it QEMU also supports directly passing devices through to
  50 guest VMs to eliminate the device emulation overhead. See
  51 :ref:`device-emulation` for more details.
  52
  53 There is a full :ref:`featured block layer<Live Block Operations>`
  54 which allows for construction of complex storage topology which can be
  55 stacked across multiple layers supporting redirection, networking,
  56 snapshots and migration support.
  57
  58 The flexible ``chardev`` system allows for handling IO from character
  59 like devices using stdio, files, unix sockets and TCP networking.
  60
  61 QEMU provides a number of management interfaces including a line based
  62 :ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to
  63 dynamically add and remove devices as well as introspect the system
  64 state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well
  65 defined, versioned, machine usable API that presents a rich interface
  66 to other tools to create, control and manage Virtual Machines. This is
  67 the interface used by higher level tools interfaces such as `Virt
  68 Manager <https://virt-manager.org/>`_ using the `libvirt framework
  69 <https://libvirt.org>`_.
  70
  71 For the common accelerators QEMU, supported debugging with its
  72 :ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug
  73 system software images.
  74
  75 Running
  76 -------
  77
  78 QEMU provides a rich and complex API which can be overwhelming to
  79 understand. While some architectures can boot something with just a
  80 disk image, those examples elide a lot of details with defaults that
  81 may not be optimal for modern systems.
  82
  83 For a non-x86 system where we emulate a broad range of machine types,
  84 the command lines are generally more explicit in defining the machine
  85 and boot behaviour. You will find often find example command lines in
  86 the :ref:`system-targets-ref` section of the manual.
  87
  88 While the project doesn't want to discourage users from using the
  89 command line to launch VMs, we do want to highlight that there are a
  90 number of projects dedicated to providing a more user friendly
  91 experience. Those built around the ``libvirt`` framework can make use
  92 of feature probing to build modern VM images tailored to run on the
  93 hardware you have.
  94
  95 That said, the general form of a QEMU command line can be expressed
  96 as:
  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
 108 Most options will generate some help information. So for example:
 109
 110 .. parsed-literal::
 111
 112    $ |qemu_system| -M help
 113
 114 will list the machine types supported by that QEMU binary. ``help``
 115 can also be passed as an argument to another option. For example:
 116
 117 .. parsed-literal::
 118
 119   $ |qemu_system| -device scsi-hd,help
 120
 121 will list the arguments and their default values of additional options
 122 that 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
 153 In the following example we first define a ``virt`` machine which is a
 154 general purpose platform for running Aarch64 guests. We enable
 155 virtualisation so we can use KVM inside the emulated guest. As the
 156 ``virt`` machine comes with some built in pflash devices we give them
 157 names 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
 165 We then define the 4 vCPUs using the ``max`` option which gives us all
 166 the Arm features QEMU is capable of emulating. We enable a more
 167 emulation friendly implementation of Arm's pointer authentication
 168 algorithm. We explicitly specify TCG acceleration even though QEMU
 169 would default to it anyway.
 170
 171 .. code::
 172
 173  -cpu max,pauth-impdef=on \
 174  -smp 4 \
 175  -accel tcg \
 176
 177 As the ``virt`` platform doesn't have any default network or storage
 178 devices we need to define them. We give them ids so we can link them
 179 with 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
 187 We connect the user-mode networking to our network device. As
 188 user-mode networking isn't directly accessible from the outside world
 189 we 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
 195 We connect the guest visible block device to an LVM partition we have
 196 set 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
 202 We then tell QEMU to multiplex the :ref:`QEMU monitor` with the serial
 203 port output (we can switch between the two using :ref:`keys in the
 204 character backend multiplexer`). As there is no default graphical
 205 device we disable the display as we can work entirely in the terminal.
 206
 207 .. code::
 208
 209  -serial mon:stdio \
 210  -display none \
 211
 212 Finally we override the default firmware to ensure we have some
 213 storage for EFI to persist its configuration. That firmware is
 214 responsible for finding the disk, booting grub and eventually running
 215 our 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