QEMU DocumentationContents:
1 About QEMU 1 1.1 Supported build platforms . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2
Deprecated features . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 2 1.3 Removed features . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 7 1.4 License . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
2 System Emulation 19 2.1 Quick Start . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19 2.2 Invocation . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 19 2.3 Device
Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 72 2.4 Keys in the graphical
frontends . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 84 2.5 Keys in the character backend multiplexer .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
2.6 QEMU Monitor . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 85 2.7 Disk Images . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 93 2.8 QEMU virtio-net standby (net_failover) . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
2.9 Direct Linux Boot . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 107 2.10 Generic Loader .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 107 2.11 Guest Loader . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 109 2.12 QEMU Barrier Client . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 110 2.13 VNC
security . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 110 2.14 TLS setup for network
services . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 113 2.15 Providing secret data to QEMU . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
2.16 Client authorization . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 119 2.17 GDB usage . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 123 2.18 Managed start up options . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 125 2.19 Managing device boot order with bootindex properties .
. . . . . . . . . . . . . . . . . . . . . . . . 125 2.20 Virtual
CPU hotplug . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 126 2.21 Persistent reservation
managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 129 2.22 QEMU System Emulator Targets . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 2.23
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 223 2.24 Multi-process
QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 226
3 User Mode Emulation 229 3.1 QEMU User space emulator . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
229
4 Tools 233 4.1 QEMU disk image utility . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 233
i
4.2 QEMU Storage Daemon . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 245 4.3 QEMU Disk Network
Block Device Server . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 248 4.4 QEMU persistent reservation helper . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 4.5
QEMU SystemTap trace tool . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 253 4.6 QEMU 9p virtfs proxy
filesystem helper . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 255 4.7 QEMU virtio-fs shared file system daemon . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
5 System Emulation Management and Interoperability 261 5.1 Barrier
client protocol . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 261 5.2 Dirty Bitmaps and
Incremental Backup . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 267 5.3 D-Bus . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
291 5.4 D-Bus VMState . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 292 5.5 Live Block
Device Operations . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 293 5.6 Persistent reservation helper
protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 310 5.7 QEMU Guest Agent . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 311 5.8 QEMU
Guest Agent Protocol Reference . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 313 5.9 QEMU QMP Reference Manual . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
344 5.10 QEMU Storage Daemon QMP Reference Manual . . . . . . . . .
. . . . . . . . . . . . . . . . . . 723 5.11 Vhost-user Protocol .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 906 5.12 Vhost-user-gpu Protocol . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930
5.13 Vhost-vdpa Protocol . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 935
6 System Emulation Guest Hardware Specifications 937 6.1 POWER9
XIVE interrupt controller . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 937 6.2 XIVE for sPAPR (pseries
machines) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . 940 6.3 NUMA mechanics for sPAPR (pseries machines) . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 944 6.4 How the
pseries Linux guest calculates NUMA distances . . . . . . . . . . .
. . . . . . . . . . . . . 946 6.5 pseries NUMA mechanics . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 946 6.6 Legacy (5.1 and older) pseries NUMA mechanics . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 949 6.7 QEMU and ACPI
BIOS Generic Event Device interface . . . . . . . . . . . . . . . .
. . . . . . . . 950 6.8 QEMU TPM Device . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951 6.9
APEI tables generating and CPER record . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 958
7 Developer Information 961 7.1 Code of Conduct . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 961 7.2 Conflict Resolution Policy . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 962 7.3 The QEMU
build system architecture . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 963 7.4 QEMU Coding Style . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 969 7.5 QEMU and Kconfig . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 980 7.6 Testing in
QEMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 984 7.7 Fuzzing . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 1001 7.8 Control-Flow Integrity (CFI) . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 1006 7.9 Load
and Store APIs . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 1008 7.10 The memory API . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 1017 7.11 Migration . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1047 7.12 Atomic operations in QEMU . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 1060 7.13 QEMU and
the stable process . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 1066 7.14 CI . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . 1067 7.15 QTest Device Emulation Testing Framework . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070 7.16
Decodetree Specification . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1102 7.17 Secure Coding
Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 1106 7.18 Translator Internals . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 1108 7.19 TCG Instruction Counting . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110 7.20
Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 1111
ii
7.21 Multi-threaded TCG . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 1119 7.22 QEMU TCG
Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 1124 7.23 Bitwise operations . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 1139 7.24 Qemu UI subsystem . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 1146 7.25
Reset in QEMU: the Resettable interface . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 1149 7.26 Booting from real
channel-attached devices on s390x . . . . . . . . . . . . . . . . .
. . . . . . . . . 1153 7.27 Modelling a clock tree in QEMU . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1155 7.28 The QEMU Object Model (QOM) . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 1162 7.29 Qemu modules .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 1198 7.30 block-coroutine-wrapper . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 1199 7.31 Multi-process QEMU . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 1200 7.32 eBPF RSS
virtio-net support . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 1212 7.33 VFIO device Migration . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 1215 7.34 How to use the QAPI code generator . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 1217 7.35 How
to write QMP commands using the QAPI framework . . . . . . . . . .
. . . . . . . . . . . . . 1246
Index 1257
CHAPTER 1
About QEMU
QEMU is a generic and open source machine emulator and
virtualizer.
QEMU can be used in several different ways. The most common is for
“system emulation”, where it provides a virtual model of an entire
machine (CPU, memory and emulated devices) to run a guest OS. In
this mode the CPU may be fully emulated, or it may work with a
hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to allow
the guest to run directly on the host CPU.
The second supported way to use QEMU is “user mode emulation”,
where QEMU can launch processes compiled for one CPU on another
CPU. In this mode the CPU is always emulated.
QEMU also provides a number of standalone commandline utilities,
such as the qemu-img disk image utility that allows you to create,
convert and modify disk images.
1.1 Supported build platforms
QEMU aims to support building and executing on multiple host OS
platforms. This appendix outlines which platforms are the major
build targets. These platforms are used as the basis for deciding
upon the minimum required versions of 3rd party software QEMU
depends on. The supported platforms are the targets for automated
testing performed by the project when patches are submitted for
review, and tested before and after merge.
If a platform is not listed here, it does not imply that QEMU won’t
work. If an unlisted platform has comparable software versions to a
listed platform, there is every expectation that it will work. Bug
reports are welcome for problems encountered on unlisted platforms
unless they are clearly older vintage than what is described
here.
Note that when considering software versions shipped in distros as
support targets, QEMU considers only the version number, and
assumes the features in that distro match the upstream release with
the same version. In other words, if a distro backports extra
features to the software in their distro, QEMU upstream code will
not add explicit support for those backports, unless the feature is
auto-detectable in a manner that works for the upstream releases
too.
The Repology site is a useful resource to identify currently
shipped versions of software in various operating systems, though
it does not cover all distros listed below.
1.1.1 Linux OS, macOS, FreeBSD, NetBSD, OpenBSD
The project aims to support the most recent major version at all
times. Support for the previous major version will be dropped 2
years after the new major version is released or when the vendor
itself drops support, whichever comes first. In this context,
third-party efforts to extend the lifetime of a distro are not
considered, even when they are endorsed by the vendor (eg. Debian
LTS).
For the purposes of identifying supported software versions
available on Linux, the project will look at CentOS, Debian,
Fedora, openSUSE, RHEL, SLES and Ubuntu LTS. Other distros will be
assumed to ship similar software versions.
For FreeBSD and OpenBSD, decisions will be made based on the
contents of the respective ports repository, while NetBSD will use
the pkgsrc repository.
For macOS, HomeBrew will be used, although MacPorts is expected to
carry similar versions.
1.1.2 Windows
The project supports building with current versions of the MinGW
toolchain, hosted on Linux (Debian/Fedora).
The version of the Windows API that’s currently targeted is Vista /
Server 2008.
1.2 Deprecated features
In general features are intended to be supported indefinitely once
introduced into QEMU. In the event that a feature needs to be
removed, it will be listed in this section. The feature will remain
functional for the release in which it was deprecated and one
further release. After these two releases, the feature is liable to
be removed. Deprecated features may also generate warnings on the
console when QEMU starts up, or if activated via a monitor command,
however, this is not a mandatory requirement.
Prior to the 2.10.0 release there was no official policy on how
long features would be deprecated prior to their removal, nor any
documented list of which features were deprecated. Thus any
features deprecated prior to 2.10.0 will be treated as if they were
first deprecated in the 2.10.0 release.
What follows is a list of all features currently marked as
deprecated.
1.2.1 System emulator command line arguments
QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
The -audiodev argument is now the preferred way to specify audio
backend settings instead of environment vari- ables. To ease
migration to the new format, the -audiodev-help option can be used
to convert the current values of the environment variables to
-audiodev options.
Creating sound card devices and vnc without audiodev= property
(since 4.2)
When not using the deprecated legacy audio config, each sound card
should specify an audiodev= property. Addi- tionally, when using
vnc, you should specify an audiodev= property if you plan to
transmit audio through the VNC protocol.
2 Chapter 1. About QEMU
Creating sound card devices using -soundhw (since 5.1)
Sound card devices should be created using -device instead. The
names are the same for most devices. The ex- ceptions are hda which
needs two devices (-device intel-hda -device hda-duplex) and pcspk
which can be activated using -machine
pcspk-audiodev=<name>.
-chardev backend aliases tty and parport (since 6.0)
tty and parport are aliases that will be removed. Instead, the
actual backend names serial and parallel should be used.
Short-form boolean options (since 6.0)
Boolean options such as share=on/share=off could be written in
short form as share and noshare. This is now deprecated and will
cause a warning.
delay option for socket character devices (since 6.0)
The replacement for the nodelay short-form boolean option is
nodelay=on rather than delay=off.
--enable-fips (since 6.0)
This option restricts usage of certain cryptographic algorithms
when the host is operating in FIPS mode.
If FIPS compliance is required, QEMU should be built with the
libgcrypt library enabled as a cryptography provider.
Neither the nettle library, or the built-in cryptography provider
are supported on FIPS enabled hosts.
-writeconfig (since 6.0)
The -writeconfig option is not able to serialize the entire
contents of the QEMU command line. It is thus considered a failed
experiment and deprecated, with no current replacement.
Userspace local APIC with KVM (x86, since 6.0)
Using -M kernel-irqchip=off with x86 machine types that include a
local APIC is deprecated. The split setting is supported, as is
using -M kernel-irqchip=off with the ISA PC machine type.
hexadecimal sizes with scaling multipliers (since 6.0)
Input parameters that take a size value should only use a size
suffix (such as ‘k’ or ‘M’) when the base is written in decimal,
and not when the value is hexadecimal. That is, ‘0x20M’ is
deprecated, and should be written either as ‘32M’ or as
‘0x2000000’.
-spice password=string (since 6.0)
This option is insecure because the SPICE password remains visible
in the process listing. This is replaced by the new password-secret
option which lets the password be securely provided on the command
line using a secret object instance.
1.2. Deprecated features 3
QEMU Documentation, Release 6.1.0
opened property of rng-* objects (since 6.0.0)
The only effect of specifying opened=on in the command line or QMP
object-add is that the device is opened immediately, possibly
before all other options have been processed. This will either have
no effect (if opened was the last option) or cause errors. The
property is therefore useless and should not be specified.
loaded property of secret and secret_keyring objects (since
6.0.0)
The only effect of specifying loaded=on in the command line or QMP
object-add is that the secret is loaded immediately, possibly
before all other options have been processed. This will either have
no effect (if loaded was the last option) or cause options to be
effectively ignored as if they were not given. The property is
therefore useless and should not be specified.
-display sdl,window_close=... (since 6.1)
Use -display sdl,window-close=... instead (i.e. with a minus
instead of an underscore between “window” and “close”).
-no-quit (since 6.1)
The -no-quit is a synonym for -display ...,window-close=off which
should be used instead.
1.2.2 QEMU Machine Protocol (QMP) commands
blockdev-open-tray, blockdev-close-tray argument device (since
2.8.0)
Use argument id instead.
Use argument id instead.
Use argument id instead.
Use argument id instead.
Use argument value null instead.
block-commit arguments base and top (since 3.1.0)
Use arguments base-node and top-node instead.
4 Chapter 1. About QEMU
QEMU Documentation, Release 6.1.0
nbd-server-add and nbd-server-remove (since 5.2)
Use the more generic commands block-export-add and block-export-del
instead. As part of this depre- cation, where nbd-server-add used a
single bitmap, the new block-export-add uses a list of
bitmaps.
1.2.3 System accelerators
MIPS Trap-and-Emul KVM support (since 6.0)
The MIPS Trap-and-Emul KVM host and guest support has been removed
from Linux upstream kernel, declare it deprecated.
1.2.4 System emulator CPUS
Icelake-Client CPU Models are deprecated. Use Icelake-Server CPU
Models instead.
MIPS I7200 CPU Model (since 5.2)
The I7200 guest CPU relies on the nanoMIPS ISA, which is deprecated
(the ISA has never been upstreamed to a compiler toolchain).
Therefore this CPU is also deprecated.
1.2.5 System emulator machines
Raspberry Pi raspi2 and raspi3 machines (since 5.2)
The Raspberry Pi machines come in various models (A, A+, B, B+). To
be able to distinguish which model QEMU is implementing, the raspi2
and raspi3 machines have been renamed raspi2b and raspi3b.
Aspeed swift-bmc machine (since 6.1)
This machine is deprecated because we have enough AST2500 based
OpenPOWER machines. It can be easily replaced by the
witherspoon-bmc or the romulus-bmc machines.
1.2.6 Backend options
Using non-persistent backing file with pmem=on (since 6.1)
This option is used when memory-backend-file is consumed by
emulated NVDIMM device. However enabling memory-backend-file.pmem
option, when backing file is (a) not DAX capable or (b) not on a
filesystem that support direct mapping of persistent memory, is not
safe and may lead to data loss or corruption in case of host crash.
Options are:
• modify VM configuration to set pmem=off to continue using fake
NVDIMM (without persistence guaranties) with backing file on non
DAX storage
• move backing file to NVDIMM storage and keep pmem=on (to have
NVDIMM with persistence guaranties).
1.2. Deprecated features 5
QEMU Documentation, Release 6.1.0
-device virtio-blk,scsi=on|off (since 5.0.0)
The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.
VIRTIO 1.0 and later do not support it because the virtio-scsi
device was introduced for full SCSI support. Use virtio-scsi
instead when SCSI passthrough is required.
Note this also applies to -device virtio-blk-pci,scsi=on|off, which
is an alias.
Block device options
"backing": "" (since 2.12.0)
In order to prevent QEMU from automatically opening an image’s
backing chain, use "backing": null instead.
rbd keyvalue pair encoded filenames: "" (since 3.1.0)
Options for rbd should be specified according to its runtime
options, like other block drivers. Legacy parsing of keyvalue pair
encoded filenames is useful to open images with the old format for
backing files; These image files should be updated to use the
current format.
Example of legacy encoding:
json:{"file.driver":"rbd", "file.pool":"rbd",
"file.image":"name"}
1.2.8 linux-user mode CPUs
ppc64abi32 CPUs (since 5.2.0)
The ppc64abi32 architecture has a number of issues which regularly
trip up our CI testing and is suspected to be quite broken. For
that reason the maintainers strongly suspect no one actually uses
it.
MIPS I7200 CPU (since 5.2)
The I7200 guest CPU relies on the nanoMIPS ISA, which is deprecated
(the ISA has never been upstreamed to a compiler toolchain).
Therefore this CPU is also deprecated.
1.2.9 Related binaries
1.2.10 Backwards compatibility
QEMU Documentation, Release 6.1.0
Runnability guarantee of CPU models (since 4.1.0)
Previous versions of QEMU never changed existing CPU models in ways
that introduced additional host software or hardware requirements
to the VM. This allowed management software to safely change the
machine type of an existing VM without introducing new requirements
(“runnability guarantee”). This prevented CPU models from being
updated to include CPU vulnerability mitigations, leaving guests
vulnerable in the default configuration.
The CPU model runnability guarantee won’t apply anymore to existing
CPU models. Management software that needs runnability guarantees
must resolve the CPU model aliases using the alias-of field
returned by the query-cpu-definitions QMP command.
While those guarantees are kept, the return value of
query-cpu-definitions will have existing CPU model aliases point to
a version that doesn’t break runnability guarantees (specifically,
version 1 of those CPU models). In future QEMU versions, aliases
will point to newer CPU model versions depending on the machine
type, so manage- ment software must resolve CPU model aliases
before starting a virtual machine.
1.2.11 Guest Emulator ISAs
nanoMIPS ISA
The nanoMIPS ISA has never been upstreamed to any compiler
toolchain. As it is hard to generate binaries for it, declare it
deprecated.
1.3 Removed features
What follows is a record of recently removed, formerly deprecated
features that serves as a record for users who have encountered
trouble after a recent upgrade.
1.3.1 System emulator command line arguments
-hdachs (removed in 2.12)
The geometry defined by -hdachs c,h,s,t should now be specified via
-device ide-hd,drive=dr, cyls=c,heads=h,secs=s,bios-chs-trans=t
(together with -drive if=none,id=dr,...).
-net channel (removed in 2.12)
This option has been replaced by -net user,guestfwd=....
-net dump (removed in 2.12)
-net dump[,vlan=n][,file=filename][,len=maxlen] has been replaced
by -object
filter-dump,id=id,netdev=dev[,file=filename][,maxlen=maxlen]. Note
that the new syntax works with netdev IDs instead of the old “vlan”
hubs.
1.3. Removed features 7
QEMU Documentation, Release 6.1.0
-no-kvm-pit (removed in 2.12)
This was just a dummy option that has been ignored, since the
in-kernel PIT cannot be disabled separately from the irqchip
anymore. A similar effect (which also disables the KVM IOAPIC) can
be obtained with -M kernel_irqchip=split.
-tdf (removed in 2.12)
There is no replacement, the -tdf option has just been ignored
since the behaviour that could be changed by this option in
qemu-kvm is now the default when using the KVM PIT. It still can be
requested explicitly using -global
kvm-pit.lost_tick_policy=delay.
-drive secs=s, -drive heads=h & -drive cyls=c (removed in
3.0)
The drive geometry should now be specified via -device
...,drive=dr,cyls=c,heads=h,secs=s (to- gether with -drive
if=none,id=dr,...).
-drive serial=, -drive trans= & -drive addr= (removed in
3.0)
Use -device ...,drive=dr,serial=r,bios-chs-trans=t,addr=a instead
(together with -drive if=none,id=dr,...).
-net ...,vlan=x (removed in 3.0)
The term “vlan” was very confusing for most users in this context
(it’s about specifying a hub ID, not about IEEE 802.1Q or something
similar), so this has been removed. To connect one NIC frontend
with a network backend, either use -nic ... (e.g. for on-board
NICs) or use -netdev ...,id=n together with -device ...,netdev=n
(for full control over pluggable NICs). To connect multiple NICs or
network backends via a hub device (which is what vlan did), use
-nic hubport,hubid=x,... or -netdev hubport,id=n,hubid=x,... (with
-device ...,netdev=n) instead.
-no-kvm-irqchip (removed in 3.0)
-no-kvm-pit-reinjection (removed in 3.0)
-balloon (removed in 3.1)
The -balloon virtio option has been replaced by -device
virtio-balloon. The -balloon none option was a no-op and has no
replacement.
-bootp (removed in 3.1)
The -bootp /some/file argument is replaced by either -netdev
user,id=x,bootp=/some/file (for pluggable NICs, accompanied with
-device ...,netdev=x), or -nic user,bootp=/some/file (for on- board
NICs). The new syntax allows different settings to be provided per
NIC.
8 Chapter 1. About QEMU
QEMU Documentation, Release 6.1.0
-redir (removed in 3.1)
The -redir [tcp|udp]:hostport:[guestaddr]:guestport option is
replaced by either -netdev
user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
(for pluggable NICs, accompanied with -device ...,netdev=x) or by
the option -nic user,
hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport (for
on-board NICs). The new syntax allows different settings to be
provided per NIC.
-smb (removed in 3.1)
The -smb /some/dir argument is replaced by either -netdev
user,id=x,smb=/some/dir (for pluggable NICs, accompanied with
-device ...,netdev=x), or -nic user,smb=/some/dir (for on-board
NICs). The new syntax allows different settings to be provided per
NIC.
-tftp (removed in 3.1)
The -tftp /some/dir argument is replaced by either -netdev
user,id=x,tftp=/some/dir (for plug- gable NICs, accompanied with
-device ...,netdev=x), or -nic user,tftp=/some/dir (for embedded
NICs). The new syntax allows different settings to be provided per
NIC.
-localtime (removed in 3.1)
-nodefconfig (removed in 3.1)
-startdate (removed in 3.1)
-vnc ...,tls=..., -vnc ...,x509=... & -vnc
...,x509verify=...
The “tls-creds” option should be used instead to point to a
“tls-creds-x509” object created using “-object”.
-net ...,name=... (removed in 5.1)
The name parameter of the -net option was a synonym for the id
parameter, which should now be used instead.
-no-kvm (removed in 5.2)
The -no-kvm argument was a synonym for setting -machine
accel=tcg.
1.3. Removed features 9
QEMU Documentation, Release 6.1.0
-realtime (removed in 6.0)
The -realtime mlock=on|off argument has been replaced by the
-overcommit mem-lock=on|off ar- gument.
-show-cursor option (removed in 6.0)
Use -display sdl,show-cursor=on, -display gtk,show-cursor=on or
-display default, show-cursor=on instead.
-tb-size option (removed in 6.0)
QEMU 5.0 introduced an alternative syntax to specify the size of
the translation block cache, -accel tcg, tb-size=.
-usbdevice audio (removed in 6.0)
This option lacked the possibility to specify an audio backend
device. Use -device usb-audio now instead (and specify a
corresponding USB host controller or -usb if necessary).
-vnc acl (removed in 6.0)
The acl option to the -vnc argument has been replaced by the
tls-authz and sasl-authz options.
-mon ...,control=readline,pretty=on|off (removed in 6.0)
The pretty=on|off switch has no effect for HMP monitors and its use
is rejected.
-drive file=json:{...{'driver':'file'}} (removed 6.0)
The ‘file’ driver for drives is no longer appropriate for character
or host devices and will only accept regular files (S_IFREG). The
correct driver for these file types is ‘host_cdrom’ or
‘host_device’ as appropriate.
Floppy controllers’ drive properties (removed in 6.0)
Use -device floppy,... instead. When configuring onboard floppy
controllers
-global isa-fdc.driveA=... -global sysbus-fdc.driveA=... -global
SUNW,fdtwo.drive=...
become
QEMU Documentation, Release 6.1.0
-device isa-fdc,...,driveA=...
and
-drive with bogus interface type (removed in 6.0)
Drives with interface types other than if=none are for onboard
devices. Drives the board doesn’t pick up can no longer be used
with -device. Use if=none instead.
-usbdevice ccid (removed in 6.0)
This option was undocumented and not used in the field. Use -device
usb-ccid instead.
RISC-V firmware not booted by default (removed in 5.1)
QEMU 5.1 changes the default behaviour from -bios none to -bios
default for the RISC-V virt machine and sifive_u machine.
1.3.2 QEMU Machine Protocol (QMP) commands
block-dirty-bitmap-add “autoload” parameter (removed in
4.2.0)
The “autoload” parameter has been ignored since 2.12.0. All bitmaps
are automatically loaded from qcow2 images.
cpu-add (removed in 5.2)
Use device_add for hotplugging vCPUs instead of cpu-add. See
documentation of query-hotpluggable-cpus for additional
details.
change (removed in 6.0)
1.3. Removed features 11
QEMU Documentation, Release 6.1.0
query-events (removed in 6.0)
The query-events command has been superseded by the more powerful
and accurate query-qmp-schema command.
migrate_set_cache_size and query-migrate-cache-size (removed in
6.0)
Use migrate_set_parameter and info migrate_parameters
instead.
migrate_set_downtime and migrate_set_speed (removed in 6.0)
Use migrate_set_parameter instead.
query-cpus-fast arch output member (removed in 6.0)
The arch output member of the query-cpus-fast command is replaced
by the target output member.
chardev client socket with wait option (removed in 6.0)
Character devices creating sockets in client mode should not
specify the ‘wait’ field, which is only applicable to sockets in
server mode
query-named-block-nodes result encryption_key_missing (removed in
6.0)
Removed with no replacement.
Removed with no replacement.
query-named-block-nodes and query-block result
dirty-bitmaps[i].status (removed in 6.0)
The status field of the BlockDirtyInfo structure, returned by these
commands is removed. Two new boolean fields, recording and busy
effectively replace it.
query-block result field dirty-bitmaps (removed in 6.0)
The dirty-bitmaps field of the BlockInfo structure, returned by the
query-block command is itself now re- moved. The dirty-bitmaps
field of the BlockDeviceInfo struct should be used instead, which
is the type of the inserted field in query-block replies, as well
as the type of array items in query-named-block-nodes.
12 Chapter 1. About QEMU
QEMU Documentation, Release 6.1.0
Specify the properties for the object as top-level arguments
instead.
1.3.3 Human Monitor Protocol (HMP) commands
usb_add and usb_remove (removed in 2.12)
Replaced by device_add and device_del (use device_add help for a
list of available devices).
host_net_add and host_net_remove (removed in 2.12)
Replaced by netdev_add and netdev_del.
The hub_id parameter of hostfwd_add / hostfwd_remove (removed in
5.0)
The [hub_id name] parameter tuple of the ‘hostfwd_add’ and
‘hostfwd_remove’ HMP commands has been re- placed by
netdev_id.
cpu-add (removed in 5.2)
Use device_add for hotplugging vCPUs instead of cpu-add. See
documentation of query-hotpluggable-cpus for additional
details.
change vnc TARGET (removed in 6.0)
No replacement. The change vnc password and change DEVICE MEDIUM
commands are not affected.
acl_show, acl_reset, acl_policy, acl_add, acl_remove (removed in
6.0)
The acl_show, acl_reset, acl_policy, acl_add, and acl_remove
commands were removed with no replacement. Authorization for VNC
should be performed using the pluggable QAuthZ objects.
migrate-set-cache-size and info migrate-cache-size (removed in
6.0)
Use migrate-set-parameters and info migrate-parameters
instead.
migrate_set_downtime and migrate_set_speed (removed in 6.0)
Use migrate-set-parameters instead.
info cpustats (removed in 6.1)
This command didn’t produce any output already. Removed with no
replacement.
1.3. Removed features 13
QEMU Documentation, Release 6.1.0
1.3.4 Guest Emulator ISAs
RISC-V ISA privilege specification version 1.09.1 (removed in
5.1)
The RISC-V ISA privilege specification version 1.09.1 has been
removed. QEMU supports both the newer version 1.10.0 and the
ratified version 1.11.0, these should be used instead of the 1.09.1
version.
1.3.5 System emulator CPUS
KVM guest support on 32-bit Arm hosts (removed in 5.2)
The Linux kernel has dropped support for allowing 32-bit Arm
systems to host KVM guests as of the 5.7 kernel. Accordingly, QEMU
is deprecating its support for this configuration and will remove
it in a future version. Running 32-bit guests on a 64-bit Arm host
remains supported.
RISC-V ISA Specific CPUs (removed in 5.1)
The RISC-V cpus with the ISA version in the CPU name have been
removed. The four CPUs are: rv32gcsu-v1.9. 1, rv32gcsu-v1.10.0,
rv64gcsu-v1.9.1 and rv64gcsu-v1.10.0. Instead the version can be
specified via the CPU priv_spec option when using the rv32 or rv64
CPUs.
RISC-V no MMU CPUs (removed in 5.1)
The RISC-V no MMU cpus have been removed. The two CPUs:
rv32imacu-nommu and rv64imacu-nommu can no longer be used. Instead
the MMU status can be specified via the CPU mmu option when using
the rv32 or rv64 CPUs.
compat property of server class POWER CPUs (removed in 6.0)
The max-cpu-compat property of the pseries machine type should be
used instead.
moxie CPU (removed in 6.1)
Nobody was using this CPU emulation in QEMU, and there were no test
images available to make sure that the code is still working, so it
has been removed without replacement.
lm32 CPUs (removed in 6.1.0)
The only public user of this architecture was the milkymist
project, which has been dead for years; there was never an upstream
Linux port. Removed without replacement.
unicore32 CPUs (since 6.1.0)
Support for this CPU was removed from the upstream Linux kernel,
and there is no available upstream toolchain to build binaries for
it. Removed without replacement.
14 Chapter 1. About QEMU
QEMU Documentation, Release 6.1.0
1.3.6 System emulator machines
s390-virtio (removed in 2.6)
The m68k dummy machine (removed in 2.9)
Use the none machine with the loader device instead.
xlnx-ep108 (removed in 3.0)
The EP108 was an early access development board that is no longer
used. Use the xlnx-zcu102 machine instead.
spike_v1.9.1 and spike_v1.10 (removed in 5.1)
The version specific Spike machines have been removed in favour of
the generic spike machine. If you need to specify an older version
of the RISC-V spec you can use the -cpu rv64gcsu,priv_spec=v1.10.0
command line argument.
mips r4k platform (removed in 5.2)
This machine type was very old and unmaintained. Users should use
the malta machine type instead.
mips fulong2e machine alias (removed in 6.0)
This machine has been renamed fuloong2e.
pc-0.10 up to pc-1.3 (removed in 4.0 up to 6.0)
These machine types were very old and likely could not be used for
live migration from old QEMU versions anymore. Use a newer machine
type instead.
1.3.7 linux-user mode CPUs
tilegx CPUs (removed in 6.0)
The tilegx guest CPU support has been removed without replacement.
It was only implemented in linux-user mode, but support for this
CPU was removed from the upstream Linux kernel in 2018, and it has
also been dropped from glibc, so there is no new Linux development
taking place with this architecture. For running the old binaries,
you can use older versions of QEMU.
1.3.8 System emulator devices
spapr-pci-vfio-host-bridge (removed in 2.12)
1.3. Removed features 15
QEMU Documentation, Release 6.1.0
ivshmem (removed in 4.0)
ide-drive (removed in 6.0)
The ‘ide-drive’ device has been removed. Users should use ‘ide-hd’
or ‘ide-cd’ as appropriate to get an IDE hard disk or CD-ROM as
needed.
scsi-disk (removed in 6.0)
The ‘scsi-disk’ device has been removed. Users should use ‘scsi-hd’
or ‘scsi-cd’ as appropriate to get a SCSI hard disk or CD-ROM as
needed.
1.3.9 Related binaries
qemu-nbd --partition (removed in 5.0)
The qemu-nbd --partition $digit code (also spelled -P) could only
handle MBR partitions, and never correctly handled logical
partitions beyond partition 5. Exporting a partition can still be
done by utilizing the --image-opts option with a raw blockdev using
the offset and size parameters layered on top of any other existing
blockdev. For example, if partition 1 is 100MiB long starting at
1MiB, the old command:
qemu-nbd -t -P 1 -f qcow2 file.qcow2
can be rewritten as:
qemu-nbd -t --image-opts
driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.
→driver=file,file.file.filename=file.qcow2
qemu-img convert -n -o (removed in 5.1)
All options specified in -o are image creation options, so they are
now rejected when used with -n to skip image creation.
qemu-img create -b bad file $size (removed in 5.1)
When creating an image with a backing file that could not be
opened, qemu-img create used to issue a warning about the failure
but proceed with the image creation if an explicit size was
provided. However, as the -u option exists for this purpose, it is
safer to enforce that any failure to open the backing image
(including if the backing file is missing or an incorrect format
was specified) is an error when -u is not used.
1.3.10 Command line options
CPU topology properties should describe whole machine topology
including possible CPUs.
However, historically it was possible to start QEMU with an
incorrect topology where n <= sockets * cores * threads <
maxcpus, which could lead to an incorrect topology enumeration by
the guest. Support for invalid topologies is
16 Chapter 1. About QEMU
QEMU Documentation, Release 6.1.0
removed, the user must ensure topologies described with -smp
include all possible cpus, i.e. sockets * cores * threads =
maxcpus.
-numa node (without memory specified) (removed 5.2)
Splitting RAM by default between NUMA nodes had the same issues as
mem parameter with the difference that the role of the user plays
QEMU using implicit generic or board specific splitting rule. Use
memdev with memory- backend-ram backend or mem (if it’s supported
by used machine type) to define mapping explicitly instead. Users
of existing VMs, wishing to preserve the same RAM distribution,
should configure it explicitly using -numa node, memdev options.
Current RAM distribution can be retrieved using HMP command info
numa and if separate memory devices (pc|nv-dimm) are present use
info memory-device and subtract device memory from output of info
numa.
-numa node,mem=size (removed in 5.1)
The parameter mem of -numa node was used to assign a part of guest
RAM to a NUMA node. But when using it, it’s impossible to manage a
specified RAM chunk on the host side (like bind it to a host node,
setting bind policy, . . . ), so the guest ends up with the fake
NUMA configuration with suboptiomal performance. However since 2014
there is an alternative way to assign RAM to a NUMA node using
parameter memdev, which does the same as mem and adds means to
actually manage node RAM on the host side. Use parameter memdev
with memory-backend-ram backend as replacement for parameter mem to
achieve the same fake NUMA effect or a properly configured
memory-backend-file backend to actually benefit from NUMA
configuration. New machine versions (since 5.1) will not accept the
option but it will still work with old machine types. User can
check the QAPI schema to see if the legacy option is supported by
looking at MachineInfo::numa-mem-supported property.
-mem-path fallback to RAM (removed in 5.0)
If guest RAM allocation from file pointed by mem-path failed, QEMU
was falling back to allocating from RAM, which might have resulted
in unpredictable behavior since the backing file specified by the
user as ignored. Currently, users are responsible for making sure
the backing storage specified with -mem-path can actually provide
the guest RAM configured with -m and QEMU fails to start up if RAM
allocation is unsuccessful.
-smp (invalid topologies) (removed 5.2)
CPU topology properties should describe whole machine topology
including possible CPUs.
However, historically it was possible to start QEMU with an
incorrect topology where n <= sockets * cores * threads <
maxcpus, which could lead to an incorrect topology enumeration by
the guest. Support for invalid topologies is removed, the user must
ensure topologies described with -smp include all possible cpus,
i.e. sockets * cores * threads = maxcpus.
-machine enforce-config-section=on|off (removed 5.2)
The enforce-config-section property was replaced by the -global
migration. send-configuration={on|off} option.
qemu-img amend to adjust backing file (removed in 6.1)
The use of qemu-img amend to modify the name or format of a qcow2
backing image was never fully documented or tested, and interferes
with other amend operations that need access to the original
backing image (such as deciding
1.3. Removed features 17
QEMU Documentation, Release 6.1.0
whether a v3 zero cluster may be left unallocated when converting
to a v2 image). Any changes to the backing chain should be
performed with qemu-img rebase -u either before or after the
remaining changes being performed by amend, as appropriate.
qemu-img backing file without format (removed in 6.1)
The use of qemu-img create, qemu-img rebase, or qemu-img convert to
create or modify an image that depends on a backing file now
requires that an explicit backing format be provided. This is for
safety: if QEMU probes a different format than what you thought,
the data presented to the guest will be corrupt; similarly,
presenting a raw image to a guest allows a potential security
exploit if a future probe sees a non-raw image based on guest
writes.
To avoid creating unsafe backing chains, you must pass -o
backing_fmt= (or the shorthand -F during create) to specify the
intended backing format. You may use qemu-img rebase -u to
retroactively add a backing format to an existing image. However,
be aware that there are already potential security risks to blindly
using qemu-img info to probe the format of an untrusted backing
image, when deciding what format to add into an existing
image.
1.3.11 Block devices
VXHS backend (removed in 5.1)
The VXHS code did not compile since v2.12.0. It was removed in
5.1.
sheepdog driver (removed in 6.0)
The corresponding upstream server project is no longer maintained.
Users are recommended to switch to an alternative distributed block
device driver such as RBD.
1.4 License
QEMU is a trademark of Fabrice Bellard.
QEMU is released under the GNU General Public License, version 2.
Parts of QEMU have specific licenses, see file LICENSE.
18 Chapter 1. About QEMU
CHAPTER 2
System Emulation
This section of the manual is the overall guide for users using
QEMU for full system emulation (as opposed to user- mode
emulation). This includes working with hypervisors such as KVM,
Xen, Hax or Hypervisor.Framework.
2.1 Quick Start
Download and uncompress a PC hard disk image with Linux installed
(e.g. linux.img) and type:
qemu-system-x86_64 linux.img
Linux should boot and give you a prompt.
Users should be aware the above example elides a lot of the
complexity of setting up a VM with x86_64 specific defaults and
assumes the first non switch argument is a PC compatible disk image
with a boot sector. For a non-x86 system where we emulate a broad
range of machine types, the command lines are generally more
explicit in defining the machine and boot behaviour. You will find
more example command lines in the QEMU System Emulator Targets
section of the manual.
2.2 Invocation
qemu-system-x86_64 [options] [disk_image]
disk_image is a raw hard disk image for IDE hard disk 0. Some
targets do not need a disk image.
2.2.1 Standard options
-version Display version information and exit
19
QEMU Documentation, Release 6.1.0
-machine [type=]name[,prop=value[,...]] Select the emulated machine
by name. Use -machine help to list available machines.
For architectures which aim to support live migration compatibility
across releases, each release will introduce a new versioned
machine type. For example, the 2.8.0 release introduced machine
types “pc-i440fx-2.8” and “pc-q35-2.8” for the x86_64/i686
architectures.
To allow live migration of guests from QEMU version 2.8.0, to QEMU
version 2.9.0, the 2.9.0 version must support the “pc-i440fx-2.8”
and “pc-q35-2.8” machines too. To allow users live migrating VMs to
skip multiple intermediate releases when upgrading, new releases of
QEMU will support machine types from many previous versions.
Supported machine properties are:
accel=accels1[:accels2[:...]] This is used to enable an
accelerator. Depending on the target ar- chitecture, kvm, xen, hax,
hvf, nvmm, whpx or tcg can be available. By default, tcg is used.
If there is more than one accelerator specified, the next one is
used if the previous one fails to initialize.
vmport=on|off|auto Enables emulation of VMWare IO port, for vmmouse
etc. auto says to select the value based on accel. For accel=xen
the default is off otherwise the default is on.
dump-guest-core=on|off Include guest memory in a core dump. The
default is on.
mem-merge=on|off Enables or disables memory merge support. This
feature, when supported by the host, de-duplicates identical memory
pages among VMs instances (enabled by default).
aes-key-wrap=on|off Enables or disables AES key wrapping support on
s390-ccw hosts. This feature controls whether AES wrapping keys
will be created to allow execution of AES cryptographic functions.
The default is on.
dea-key-wrap=on|off Enables or disables DEA key wrapping support on
s390-ccw hosts. This feature controls whether DEA wrapping keys
will be created to allow execution of DEA cryptographic functions.
The default is on.
nvdimm=on|off Enables or disables NVDIMM support. The default is
off.
memory-encryption= Memory encryption object to use. The default is
none.
hmat=on|off Enables or disables ACPI Heterogeneous Memory Attribute
Table (HMAT) support. The de- fault is off.
memory-backend='id' An alternative to legacy -mem-path and
mem-prealloc options. Allows to use a memory backend as main
RAM.
For example:
Migration compatibility note:
• as backend id one shall use value of ‘default-ram-id’, advertised
by machine type (available via query-machines QMP command), if
migration to/from old QEMU (<5.0) is expected.
• for machine types 4.0 and older, user shall use
x-use-canonical-path-for-ramblock-id=off backend option if
migration to/from old QEMU (<5.0) is expected.
For example:
QEMU Documentation, Release 6.1.0
-object
memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-
→ramblock-id=off -machine memory-backend=pc.ram -m 512M
-cpu model Select CPU model (-cpu help for list and additional
feature selection)
-accel name[,prop=value[,...]] This is used to enable an
accelerator. Depending on the target architec- ture, kvm, xen, hax,
hvf, nvmm, whpx or tcg can be available. By default, tcg is used.
If there is more than one accelerator specified, the next one is
used if the previous one fails to initialize.
igd-passthru=on|off When Xen is in use, this option controls
whether Intel integrated graphics devices can be passed through to
the guest (default=off)
kernel-irqchip=on|off|split Controls KVM in-kernel irqchip support.
The default is full accelera- tion of the interrupt controllers. On
x86, split irqchip reduces the kernel attack surface, at a
performance cost for non-MSI interrupts. Disabling the in-kernel
irqchip completely is not recommended except for debugging
purposes.
kvm-shadow-mem=size Defines the size of the KVM shadow MMU.
split-wx=on|off Controls the use of split w^x mapping for the TCG
code generation buffer. Some operat- ing systems require this to be
enabled, and in such a case this will default on. On other
operating systems, this will default off, but one may enable this
for testing or debugging.
tb-size=n Controls the size (in MiB) of the TCG translation block
cache.
thread=single|multi Controls number of TCG threads. When the TCG is
multi-threaded there will be one thread per vCPU therefore taking
advantage of additional host cores. The default is to enable multi-
threading where both the back-end and front-ends support it and no
incompatible TCG features have been enabled (e.g.
icount/replay).
dirty-ring-size=n When the KVM accelerator is used, it controls the
size of the per-vCPU dirty page ring buffer (number of entries for
each vCPU). It should be a value that is power of two, and it
should be 1024 or bigger (but still less than the maximum value
that the kernel supports). 4096 could be a good initial value if
you have no idea which is the best. Set this value to 0 to disable
the feature. By default, this feature is disabled
(dirty-ring-size=0). When enabled, KVM will instead record dirty
pages in a bitmap.
-smp
[[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]
Simulate a SMP system with ‘n’ CPUs initially present on the
machine type board. On boards supporting CPU hotplug, the optional
‘maxcpus’ parameter can be set to enable further CPUs to be added
at runtime. If omitted the maximum number of CPUs will be set to
match the initial CPU count. Both parameters are subject to an
upper limit that is determined by the specific machine type
chosen.
To control reporting of CPU topology information, the number of
sockets, dies per socket, cores per die, and threads per core can
be specified. The sum ‘‘ sockets * cores * dies * threads ‘‘ must
be equal to the maximum CPU count. CPU targets may only support a
subset of the topology parameters. Where a CPU target does not
support use of a particular topology parameter, its value should be
assumed to be 1 for the purpose of computing the CPU maximum
count.
Either the initial CPU count, or at least one of the topology
parameters must be specified. Values for any omitted parameters
will be computed from those which are given. Historically
preference was given to the coarsest topology parameters when
computing missing values (ie sockets preferred over cores, which
were preferred over threads), however, this behaviour is considered
liable to change.
-numa
node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]
-numa
node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]
2.2. Invocation 21
-numa
cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
-numa
hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]
-numa
hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]
Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
distance from a source node to a destination node. Set the ACPI
Heterogeneous Memory Attributes for the given nodes.
Legacy VCPU assignment uses ‘cpus’ option where firstcpu and
lastcpu are CPU indexes. Each ‘cpus’ option represent a contiguous
range of CPU indexes (or a single VCPU if lastcpu is omitted). A
non-contiguous set of VCPUs can be represented by providing
multiple ‘cpus’ options. If ‘cpus’ is omitted on all nodes, VCPUs
are automatically split between them.
For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
NUMA node:
-numa node,cpus=0-2,cpus=5
‘cpu’ option is a new alternative to ‘cpus’ option which uses
‘socket-id|core-id|thread-id’ prop- erties to assign CPU objects to
a node using topology layout properties of CPU. The set of
properties is machine specific, and depends on used machine
type/’smp’ options. It could be queried with ‘hotpluggable-cpus’
monitor command. ‘node-id’ property specifies node to which CPU
object will be assigned, it’s required for node to be declared with
‘node’ option before it’s used with ‘cpu’ option.
For example:
-M pc \ -smp 1,sockets=2,maxcpus=2 \ -numa node,nodeid=0 -numa
node,nodeid=1 \ -numa cpu,node-id=0,socket-id=0 -numa
cpu,node-id=1,socket-id=1
Legacy ‘mem’ assigns a given RAM amount to a node (not supported
for 5.1 and newer machine types). ‘memdev’ assigns RAM from a given
memory backend device to a node. If ‘mem’ and ‘memdev’ are omitted
in all nodes, RAM is split equally between them.
‘mem’ and ‘memdev’ are mutually exclusive. Furthermore, if one node
uses ‘memdev’, all of them have to use it.
‘initiator’ is an additional option that points to an initiator
NUMA node that has best performance (the lowest latency or largest
bandwidth) to this NUMA node. Note that this option can be set only
when the machine property ‘hmat’ is set to ‘on’.
Following example creates a machine with 2 NUMA nodes, node 0 has
CPU. node 1 has only memory, and its initiator is node 0. Note that
because node 0 has CPU, by default the initiator of node 0 is
itself and must be itself.
-machine hmat=on \ -m 2G,slots=2,maxmem=4G \ -object
memory-backend-ram,size=1G,id=m0 \ -object
memory-backend-ram,size=1G,id=m1 \ -numa node,nodeid=0,memdev=m0 \
-numa node,nodeid=1,memdev=m1,initiator=0 \ -smp
2,sockets=2,maxcpus=2 \ -numa cpu,node-id=0,socket-id=0 \ -numa
cpu,node-id=0,socket-id=1
source and destination are NUMA node IDs. distance is the NUMA
distance from source to destination. The distance from a node to
itself is always 10. If any pair of nodes is given a distance, then
all pairs must be given
22 Chapter 2. System Emulation
QEMU Documentation, Release 6.1.0
distances. Although, when distances are only given in one direction
for each pair of nodes, then the distances in the opposite
directions are assumed to be the same. If, however, an asymmetrical
pair of distances is given for even one node pair, then all node
pairs must be provided distance values for both directions, even
when they are symmetrical. When a node is unreachable from another
node, set the pair’s distance to 255.
Note that the -numa option doesn’t allocate any of the specified
resources, it just assigns existing resources to NUMA nodes. This
means that one still has to use the -m, -smp options to allocate
RAM and VCPUs respectively.
Use ‘hmat-lb’ to set System Locality Latency and Bandwidth
Information between initiator and target NUMA nodes in ACPI
Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node
can create memory requests, usually it has one or more processors.
Target NUMA node contains addressable memory.
In ‘hmat-lb’ option, node are NUMA node IDs. hierarchy is the
memory hierarchy of the target NUMA node: if hierarchy is ‘memory’,
the structure represents the memory performance; if hierarchy is
‘first-level|second- level|third-level’, this structure represents
aggregated performance of memory side caches for each domain. type
of ‘data-type’ is type of data represented by this structure
instance: if ‘hierarchy’ is ‘memory’, ‘data-type’ is
‘access|read|write’ latency or ‘access|read|write’ bandwidth of the
target memory; if ‘hierarchy’ is ‘first-
level|second-level|third-level’, ‘data-type’ is ‘access|read|write’
hit latency or ‘access|read|write’ hit bandwidth of the target
memory side cache.
lat is latency value in nanoseconds. bw is bandwidth value, the
possible value and units are NUM[M|G|T], mean that the bandwidth
value are NUM byte per second (or MB/s, GB/s or TB/s depending on
used suffix). Note that if latency or bandwidth value is 0, means
the corresponding latency or bandwidth information is not
provided.
In ‘hmat-cache’ option, node-id is the NUMA-id of the memory
belongs. size is the size of memory side cache in bytes. level is
the cache level described in this structure, note that the cache
level 0 should not be used with ‘hmat-cache’ option. associativity
is the cache associativity, the possible value is
‘none/direct(direct- mapped)/complex(complex cache indexing)’.
policy is the write policy. line is the cache Line size in
bytes.
For example, the following options describe 2 NUMA nodes. Node 0
has 2 cpus and a ram, node 1 has only a ram. The processors in node
0 access memory in node 0 with access-latency 5 nanoseconds,
access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
memory in NUMA node 1 with access-latency 10 nanosec- onds,
access-bandwidth is 100 MB/s. And for memory side cache
information, NUMA node 0 and 1 both have 1 level memory cache, size
is 10KB, policy is write-back, the cache Line size is 8
bytes:
-machine hmat=on \ -m 2G \ -object memory-backend-ram,size=1G,id=m0
\ -object memory-backend-ram,size=1G,id=m1 \ -smp 2 \ -numa
node,nodeid=0,memdev=m0 \ -numa node,nodeid=1,memdev=m1,initiator=0
\ -numa cpu,node-id=0,socket-id=0 \ -numa cpu,node-id=0,socket-id=1
\ -numa
hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,
→latency=5 \ -numa
hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,
→bandwidth=200M \ -numa
hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,
→latency=10 \ -numa
hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,
→bandwidth=100M \ -numa
hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-
→back,line=8 \ -numa
hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-
→back,line=8
-add-fd fd=fd,set=set[,opaque=opaque] Add a file descriptor to an
fd set. Valid options are:
2.2. Invocation 23
QEMU Documentation, Release 6.1.0
fd=fd This option defines the file descriptor of which a duplicate
is added to fd set. The file descriptor cannot be stdin, stdout, or
stderr.
set=set This option defines the ID of the fd set to add the file
descriptor to.
opaque=opaque This option defines a free-form string that can be
used to describe fd.
You can open an image using pre-opened file descriptors from an fd
set:
qemu-system-x86_64 \ -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
\ -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \ -drive
file=/dev/fdset/2,index=0,media=disk
-set group.id.arg=value Set parameter arg for item id of type
group
-global driver.prop=value
-global driver=driver,property=property,value=value Set default
value of driver’s property prop to value, e.g.:
qemu-system-x86_64 -global ide-hd.physical_block_size=4096
disk-image.img
In particular, you can use this to set driver properties for
devices which are created automatically by the machine model. To
create a device which is not created automatically and set
properties on it, use -device.
-global driver.prop=value is shorthand for -global
driver=driver,property=prop,value=value. The longhand syn- tax
works even when driver contains a dot.
-boot
[order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]
Specify boot order drives as a string of drive letters. Valid drive
letters depend on the target architecture. The x86 PC uses: a, b
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
(Etherboot from network adapter 1-4), hard disk boot is the
default. To apply a particular boot order only on the first
startup, specify it via once. Note that the order or once parameter
should not be used together with the bootindex property of devices,
since the firmware implementations normally do not support both at
the same time.
Interactive boot menus/prompts can be enabled via menu=on as far as
firmware/BIOS supports them. The default is non-interactive
boot.
A splash picture could be passed to bios, enabling user to show it
as logo, when option splash=sp_name is given and menu=on, If
firmware/BIOS supports them. Currently Seabios for X86 system
support it. limitation: The splash file could be a jpeg file or a
BMP file in 24 BPP format(true color). The resolution should be
supported by the SVGA mode, so the recommended is 320x240, 640x480,
800x640.
A timeout could be passed to bios, guest will pause for rb_timeout
ms when boot failed, then reboot. If rb_timeout is ‘-1’, guest will
not reboot, qemu passes ‘-1’ to bios by default. Currently Seabios
for X86 system support it.
Do strict boot via strict=on as far as firmware/BIOS supports it.
This only effects when boot priority is changed by bootindex
options. The default is non-strict boot.
# try to boot from network first, then from hard disk
qemu-system-x86_64 -boot order=nc # boot from CD-ROM first, switch
back to default order after reboot qemu-system-x86_64 -boot once=d
# boot with a splash picture for 5 seconds. qemu-system-x86_64
-boot menu=on,splash=/root/boot.bmp,splash-time=5000
Note: The legacy format ‘-boot drives’ is still supported but its
use is discouraged as it may be removed from future versions.
-m [size=]megs[,slots=n,maxmem=size] Sets guest startup RAM size to
megs megabytes. Default is 128 MiB. Optionally, a suffix of “M” or
“G” can be used to signify a value in megabytes or gigabytes
respectively.
24 Chapter 2. System Emulation
QEMU Documentation, Release 6.1.0
Optional pair slots, maxmem could be used to set amount of
hotpluggable memory slots and maximum amount of memory. Note that
maxmem must be aligned to the page size.
For example, the following command-line sets the guest startup RAM
size to 1GB, creates 3 slots to hotplug additional memory and sets
the maximum memory the guest can reach to 4GB:
qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
If slots and maxmem are not specified, memory hotplug won’t be
enabled and the guest startup RAM will never increase.
-mem-path path Allocate guest RAM from a temporarily created file
in path.
-mem-prealloc Preallocate memory when using -mem-path.
-k language Use keyboard layout language (for example fr for
French). This option is only needed where it is not easy to get raw
PC keycodes (e.g. on Macs, with some X11 servers or with a VNC or
curses display). You don’t normally need to use it on PC/Linux or
PC/Windows hosts.
The available layouts are:
ar de-ch es fo fr-ca hu ja mk no pt-br sv da en-gb et fr fr-ch is
lt nl pl ru th de en-us fi fr-be hr it lv nl-be pt sl tr
The default is en-us.
-audio-help Will show the -audiodev equivalent of the currently
specified (deprecated) environment variables.
-audiodev [driver=]driver,id=id[,prop[=value][,...]] Adds a new
audio backend driver identified by id. There are global and driver
specific properties. Some values can be set differently for input
and output, they’re marked with in|out.. You can set the input’s
property with in.prop and the output’s property with out.prop. For
example:
-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
-audiodev alsa,id=example,out.channels=1 # leaves in.channels
unspecified
NOTE: parameter validation is known to be incomplete, in many cases
specifying an invalid option causes QEMU to print an error message
and continue emulation without sound.
Valid global options are:
id=identifier Identifies the audio backend.
timer-period=period Sets the timer period used by the audio
subsystem in microseconds. Default is 10000 (10 ms).
in|out.mixing-engine=on|off Use QEMU’s mixing engine to mix all
streams inside QEMU and convert audio formats when not supported by
the backend. When off, fixed-settings must be off too. Note that
disabling this option means that the selected backend must support
multiple streams and the audio formats used by the virtual cards,
otherwise you’ll get no sound. It’s not recommended to disable this
option unless you want to use 5.1 or 7.1 audio, as mixing engine
only supports mono and stereo audio. Default is on.
in|out.fixed-settings=on|off Use fixed settings for host audio.
When off, it will change based on how the guest opens the sound
card. In this case you must not specify frequency, channels or
format. Default is on.
in|out.frequency=frequency Specify the frequency to use when using
fixed-settings. Default is 44100Hz.
in|out.channels=channels Specify the number of channels to use when
using fixed-settings. Default is 2 (stereo).
2.2. Invocation 25
QEMU Documentation, Release 6.1.0
in|out.format=format Specify the sample format to use when using
fixed-settings. Valid values are: s8, s16, s32, u8, u16, u32, f32.
Default is s16.
in|out.voices=voices Specify the number of voices to use. Default
is 1.
in|out.buffer-length=usecs Sets the size of the buffer in
microseconds.
-audiodev none,id=id[,prop[=value][,...]] Creates a dummy backend
that discards all outputs. This backend has no backend specific
properties.
-audiodev alsa,id=id[,prop[=value][,...]] Creates backend using the
ALSA. This backend is only available on Linux.
ALSA specific options are:
in|out.dev=device Specify the ALSA device to use for input and/or
output. Default is default.
in|out.period-length=usecs Sets the period length in
microseconds.
in|out.try-poll=on|off Attempt to use poll mode with the device.
Default is on.
threshold=threshold Threshold (in microseconds) when playback
starts. Default is 0.
-audiodev coreaudio,id=id[,prop[=value][,...]] Creates a backend
using Apple’s Core Audio. This backend is only available on Mac OS
and only supports playback.
Core Audio specific options are:
in|out.buffer-count=count Sets the count of the buffers.
-audiodev dsound,id=id[,prop[=value][,...]] Creates a backend using
Microsoft’s DirectSound. This backend is only available on Windows
and only supports playback.
DirectSound specific options are:
latency=usecs Add extra usecs microseconds latency to playback.
Default is 10000 (10 ms).
-audiodev oss,id=id[,prop[=value][,...]] Creates a backend using
OSS. This backend is available on most Unix-like systems.
OSS specific options are:
in|out.dev=device Specify the file name of the OSS device to use.
Default is /dev/dsp.
in|out.buffer-count=count Sets the count of the buffers.
in|out.try-poll=on|of Attempt to use poll mode with the device.
Default is on.
try-mmap=on|off Try using memory mapped device access. Default is
off.
exclusive=on|off Open the device in exclusive mode (vmix won’t work
in this case). Default is off.
dsp-policy=policy Sets the timing policy (between 0 and 10, where
smaller number means smaller la- tency but higher CPU usage). Use
-1 to use buffer sizes specified by buffer and buffer-count. This
option is ignored if you do not have OSS 4. Default is 5.
-audiodev pa,id=id[,prop[=value][,...]] Creates a backend using
PulseAudio. This backend is available on most systems.
PulseAudio specific options are:
server=server Sets the PulseAudio server to connect to.
in|out.name=sink Use the specified source/sink for
recording/playback.
in|out.latency=usecs Desired latency in microseconds. The
PulseAudio server will try to honor this value but actual latencies
may be lower or higher.
26 Chapter 2. System Emulation
QEMU Documentation, Release 6.1.0
-audiodev sdl,id=id[,prop[=value][,...]] Creates a backend using
SDL. This backend is available on most systems, but you should use
your platform’s native backend if possible.
SDL specific options are:
in|out.buffer-count=count Sets the count of the buffers.
-audiodev spice,id=id[,prop[=value][,...]] Creates a backend that
sends audio through SPICE. This backend requires -spice and
automatically selected in that case, so usually you can ignore this
option. This backend has no backend specific properties.
-audiodev wav,id=id[,prop[=value][,...]] Creates a backend that
writes audio to a WAV file.
Backend specific options are:
path=path Write recorded audio into the specified file. Default is
qemu.wav.
-soundhw card1[,card2,...] or -soundhw all Enable audio and
selected sound hardware. Use ‘help’ to print all available sound
hardware. For example:
qemu-system-x86_64 -soundhw sb16,adlib disk.img qemu-system-x86_64
-soundhw es1370 disk.img qemu-system-x86_64 -soundhw ac97 disk.img
qemu-system-x86_64 -soundhw hda disk.img qemu-system-x86_64
-soundhw all disk.img qemu-system-x86_64 -soundhw help
Note that Linux’s i810_audio OSS kernel (for AC97) module might
require manually specifying clocking.
modprobe i810_audio clocking=48000
-device driver[,prop[=value][,...]] Add device driver. prop=value
sets driver properties. Valid properties depend on the driver. To
get help on possible drivers and properties, use -device help and
-device driver,help.
Some drivers are:
-device ipmi-bmc-sim,id=id[,prop[=value][,...]] Add an IPMI BMC.
This is a simulation of a hardware management interface processor
that normally sits on a system. It provides a watchdog and the
ability to reset and power control the system. You need to connect
this to an IPMI interface to make it useful
The IPMI slave address to use for the BMC. The default is 0x20.
This address is the BMC’s address on the I2C network of management
controllers. If you don’t know what this means, it is safe to
ignore it.
id=id The BMC id for interfaces to use this device.
slave_addr=val Define slave address to use for the BMC. The default
is 0x20.
sdrfile=file file containing raw Sensor Data Records (SDR) data.
The default is none.
fruareasize=val size of a Field Replaceable Unit (FRU) area. The
default is 1024.
frudatafile=file file containing raw Field Replaceable Unit (FRU)
inventory data. The default is none.
guid=uuid value for the GUID for the BMC, in standard UUID format.
If this is set, get “Get GUID” command to the BMC will return it.
Otherwise “Get GUID” will return an error.
-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val] Add a
connection to an exter- nal IPMI BMC simulator. Instead of locally
emulating the BMC like the above item, instead connect to an
external entity that provides the IPMI services.
A connection is made to an external BMC simulator. If you do this,
it is strongly recommended that you use the “reconnect=” chardev
option to reconnect to the simulator if the connection is lost.
Note that if this is not used carefully, it can be a security
issue, as the interface has the ability to send resets, NMIs, and
power off the VM.
2.2. Invocation 27
QEMU Documentation, Release 6.1.0
It’s best if QEMU makes a connection to an external simulator
running on a secure port on localhost, so neither the simulator nor
QEMU is exposed to any outside network.
See the “lanserv/README.vm” file in the OpenIPMI library for more
details on the external interface.
-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val] Add a KCS IPMI
interafce on the ISA bus. This also adds a corresponding ACPI and
SMBIOS entries, if appropriate.
bmc=id The BMC to connect to, one of ipmi-bmc-sim or
ipmi-bmc-extern above.
ioport=val Define the I/O address of the interface. The default is
0xca0 for KCS.
irq=val Define the interrupt to use. The default is 5. To disable
interrupts, set this to 0.
-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val] Like the KCS
interface, but defines a BT interface. The default port is 0xe4 and
the default interrupt is 5.
-device pci-ipmi-kcs,bmc=id Add a KCS IPMI interafce on the PCI
bus.
bmc=id The BMC to connect to, one of ipmi-bmc-sim or
ipmi-bmc-extern above.
-device pci-ipmi-bt,bmc=id Like the KCS interface, but defines a BT
interface on the PCI bus.
-device intel-iommu[,option=...] This is only supported by -machine
q35, which will enable Intel VT-d emulation within the guest. It
supports below options:
intremap=on|off (default: auto) This enables interrupt remapping
feature. It’s required to enable com- plete x2apic. Currently it
only supports kvm kernel-irqchip modes off or split, while full
kernel- irqchip is not yet supported. The default value is “auto”,
which will be decided by the mode of kernel- irqchip.
caching-mode=on|off (default: off) This enables caching mode for
the VT-d emulated device. When caching-mode is enabled, each guest
DMA buffer mapping will generate an IOTLB invalidation from the
guest IOMMU driver to the vIOMMU device in a synchronous way. It is
required for -device vfio-pci to work with the VT-d device, because
host assigned devices requires to setup the DMA mapping on the host
before guest DMA starts.
device-iotlb=on|off (default: off) This enables device-iotlb
capability for the emulated VT-d device. So far virtio/vhost should
be the only real user for this parameter, paired with ats=on
configured for the device.
aw-bits=39|48 (default: 39) This decides the address width of IOVA
address space. The address space has 39 bits width for 3-level
IOMMU page tables, and 48 bits for 4-level IOMMU page tables.
Please also refer to the wiki page for general scenarios of VT-d
emulation in QEMU: https://wiki.qemu.org/ Features/VT-d.
-name name Sets the name of the guest. This name will be displayed
in the SDL window caption. The name will also be used for the VNC
server. Also optionally set the top visible process name in Linux.
Naming of individual threads can also be enabled on Linux to aid
debugging.
-uuid uuid Set system UUID.
2.2.2 Block device options
-fda file
-fdb file Use file as floppy disk 0/1 image (see the Disk Images
chapter in the System Emulation Users Guide).
-hda file
-hdb file
-hdc file
QEMU Documentation, Release 6.1.0
-hdd file Use file as hard disk 0, 1, 2 or 3 image (see the Disk
Images chapter in the System Emulation Users Guide).
-cdrom file Use file as CD-ROM image (you cannot use -hdc and
-cdrom at the same time). You can use the host CD-ROM by using
/dev/cdrom as filename.
-blockdev option[,option[,option[,...]]] Define a new block driver
node. Some of the options apply to all block drivers, other options
are only accepted for a specific block driver. See below for a list
of generic options and options for the most common block
drivers.
Options that expect a reference to another node (e.g. file) can be
given in two ways. Either you specify the node name of an already
existing node (file=node-name), or you define a new node inline,
adding options for the referenced node after a dot
(file.filename=path,file.aio=native).
A block driver node created with -blockdev can be used for a guest
device by specifying its node name for the drive property in a
-device argument that defines a block device.
Valid options for any block driver node:
driver Specifies the block driver to use for the given node.
node-name This defines the name of the block driver node by which
it will be referenced later. The name must be unique, i.e. it must
not match the name of a different block driver node, or (if you use
-drive as well) the ID of a drive.
If no node name is specified, it is automatically generated. The
generated node name is not intended to be predictable and changes
between QEMU invocations. For the top level, an explicit node name
must be specified.
read-only Open the node read-only. Guest write attempts will
fail.
Note that some block drivers support only read-only access, either
generally or in certain configu- rations. In this case, the default
value read-only=off does not work and the option must be specified
explicitly.
auto-read-only If auto-read-only=on is set, QEMU may fall back to
read-only usage even when read-only=off is requested, or even
switch between modes as needed, e.g. depending on whether the image
file is writable or whether a writing user is attached to the
node.
force-share Override the image locking system of QEMU by forcing
the node to utilize weaker shared access for permissions where it
would normally request exclusive access. When there is the po-
tential for multiple instances to have the same file open (whether
this invocation of QEMU is the first or the second instance), both
instances must permit shared access for the second instance to
succeed at opening the file.
Enabling force-share=on requires read-only=on.
cache.direct The host page cache can be avoided with
cache.direct=on. This will attempt to do disk IO directly to the
guest’s memory. QEMU may still perform an internal copy of the
data.
cache.no-flush In case you don’t care about data integrity over
host failures, you can use cache. no-flush=on. This option tells
QEMU that it never needs to write any data to the disk but can
instead keep things in cache. If anything goes wrong, like your
host losing power, the disk storage getting disconnected
accidentally, etc. your image will most probably be rendered
unusable.
discard=discard discard is one of “ignore” (or “off”) or “unmap”
(or “on”) and controls whether discard (also known as trim or
unmap) requests are ignored or passed to the filesystem. Some
machine types may not support discard requests.
detect-zeroes=detect-zeroes detect-zeroes is “off”, “on” or “unmap”
and enables the auto- matic conversion of plain zero writes by the
OS to driver specific optimized zero write commands.
2.2. Invocation 29
QEMU Documentation, Release 6.1.0
You may even choose “unmap” if discard is set to “unmap” to allow a
zero write to be converted to an unmap operation.
Driver-specific options for file This is the protocol-level block
driver for accessing regular files.
filename The path to the image file in the local filesystem
aio Specifies the AIO backend (threads/native/io_uring, default:
threads)
locking Specifies whether the image file is protected with Linux
OFD / POSIX locks. The default is to use the Linux Open File
Descriptor API if available, otherwise no lock is applied.
(auto/on/off, default: auto)
Example:
-blockdev driver=file,node-name=disk,filename=disk.img
Driver-specific options for raw This is the image format block
driver for raw images. It is usu- ally stacked on top of a protocol
level block driver such as file.
file Reference to or definition of the data source block driver
node (e.g. a file driver node)
Example 1:
Example 2:
-blockdev
driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
Driver-specific options for qcow2 This is the image format block
driver for qcow2 images. It is usually stacked on top of a protocol
level block driver such as file.
file Reference to or definition of the data source block driver
node (e.g. a file driver node)
backing Reference to or definition of the backing file block device
(default is taken from the image file). It is allowed to pass null
here in order to disable the default backing file.
lazy-refcounts Whether to enable the lazy refcounts feature
(on/off; default is taken from the image file)
cache-size The maximum total size of the L2 table and refcount
block caches in bytes (default: the sum of l2-cache-size and
refcount-cache-size)
l2-cache-size The maximum size of the L2 table cache in bytes
(default: if cache-size is not speci- fied - 32M on Linux
platforms, and 8M on non-Linux platforms; otherwise, as large as
possible within the cache-size, while permitting the requested or
the minimal refcount cache size)
refcount-cache-size The maximum size of the refcount block cache in
bytes (default: 4 times the cluster size; or if cache-size is
specified, the part of it which is not used for the L2 cache)
cache-clean-interval Clean unused entries in the L2 and refcount
caches. The interval is in seconds. The default value is 600 on
supporting platforms, and 0 on other platforms. Setting it to 0
disables this feature.
pass-discard-request Whether discard requests to the qcow2 device
should be forwarded to the data source (on/off; default: on if
discard=unmap is specified, off otherwise)
pass-discard-snapshot Whether discard requests for the data source
should be issued when a snapshot operation (e.g. deleting a
snapshot) frees clusters in the qcow2 file (on/off; default:
on)
30 Chapter 2. System Emulation
QEMU Documentation, Release 6.1.0
pass-discard-other Whether discard requests for the data source
should be issued on other occa- sions where a cluster gets freed
(on/off; default: off)
overlap-check Which overlap checks to perform for writes to the
image (none/constant/cached/all; default: cached). For details or
finer granularity control refer to the QAPI documentation of
blockdev-add.
Example 1:
Example 2:
-blockdev
driver=qcow2,node-name=disk,file.driver=http,file.filename=http://
→example.com/image.qcow2
Driver-specific options for other drivers Please refer to the QAPI
documentation of the blockdev-add QMP command.
-drive option[,option[,option[,...]]] Define a new drive. This
includes creating a block driver node (the backend) as well as a
guest device, and is mostly a shortcut for defining the
corresponding -blockdev and -device options.
-drive accepts all options that are accepted by -blockdev. In
addition, it knows the following options:
file=file This option defines which disk image (see the Disk Images
chapter in the System Emulation Users Guide) to use with this
drive. If the filename contains comma, you must double it (for
instance, “file=my„file” to use file “my,file”).
Special files such as iSCSI devices can be specified using protocol
specific URLs. See the section for “Device URL Syntax” for more
information.
if=interface This option defines on which type on interface the
drive is connected. Available types are: ide, scsi, sd, mtd,
floppy, pflash, virtio, none.
bus=bus,unit=unit These options define where is connected the drive
by defining the bus number and the unit id.
index=index This option defines where is connected the drive by
using an index in the list of available connectors of a given
interface type.
media=media This option defines the type of the media: disk or
cdrom.
snapshot=snapshot snapshot is “on” or “off” and controls snapshot
mode for the given drive (see -snapshot).
cache=cache cache is “none”, “writeback”, “unsafe”, “directsync” or
“writethrough” and controls how the host cache is used to access
block data. This is a shortcut that sets the cache.direct and
cache. no-flush options (as in -blockdev), and additionally
cache.writeback, which provides a de- fault for the write-cache
option of block guest devices (as in -device). The modes correspond
to the following settings:
cache.writeback cache.direct cache.no-flush writeback on off off
none on on off writethrough off off off directsync off on off
unsafe on off on
2.2. Invocation 31
The default mode is cache=writeback.
aio=aio aio is “threads”, “native”, or “io_uring” and selects
between pthread based disk I/O, native Linux AIO, or Linux io_uring
API.
format=format Specify which disk format will be used rather than
detecting the format. Can be used to specify format=raw to avoid
interpreting an untrusted format header.
werror=action,rerror=action Specify which action to take on write
and read errors. Valid actions are: “ignore” (ignore the error and
try to continue), “stop” (pause QEMU), “report” (report the error
to the guest), “enospc” (pause QEMU only if the host disk is full;
report the error to the guest otherwise). The default setting is
werror=enospc and rerror=report.
copy-on-read=copy-on-read copy-on-read is “on” or “off” and enables
whether to copy read backing file sectors into the image
file.
bps=b,bps_rd=r,bps_wr=w Specify bandwidth throttling limits in
bytes per second, either for all request types or for reads or
writes only. Small values can lead to timeouts or hangs inside the
guest. A safe minimum for disks is 2 MB/s.
bps_max=bm,bps_rd_max=rm,bps_wr_max=wm Specify bursts in bytes per
second, either for all re- quest types or for reads or writes only.
Bursts allow the guest I/O to spike above the limit
temporarily.
iops=i,iops_rd=r,iops_wr=w Specify request rate limits in requests
per second, either for all request types or for reads or writes
only.
iops_max=bm,iops_rd_max=rm,iops_wr_max=