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