Jump to navigation Jump to search

System emulation

Incompatible changes

  • The 'name' parameter of the '-net' option has been removed. 'id' can be used instead.
  • 'qemu-img resize' now requires --shrink for shrinking raw images, too. Previously, this was an error only for non-raw formats and resulting only in a deprecation warning for raw images.
  • The 'mem' parameter of the '-numa' option is not supported for 5.1 and newer machine types, use the 'memdev' parameter instead. Though for compatibility reasons the 'mem' parameter should still work for 5.0 and older machine types. The 'memdev' parameter provides better performance (pinning RAM to specified host NUMA nodes) and more control over backend's RAM, and users are advised to reconfigure existing virtual machines to use the 'memdev' parameter (requires restarting virtual machine).

Details can be found in the "Recently removed features" chapter of the QEMU System Emulation User's Guide.

New deprecated options and features

Consult the "Deprecated Features" chapter of the QEMU System Emulation User's Guide for the full list of historically deprecated features/options.

In particular, note that the TileGX guest support has been deprecated and will be removed in a future version.


  • The coldfire machines do not bail out anymore if a guest writes to or reads from an unimplemented hardware register. You can start QEMU with "-d unimp" to see these accesses instead.
  • Fixes in the FPU emulation



  • Emulation of the following architecture features is now implemented:
    • ARMv8.2-TTS2UXN
    • ARMv8.5-MemTag ('virt' board only, disabled by default: enable with '-machine mte=on')
  • xlnx-versal-virt: machine now supports RTC and SD
  • New board model: sonorapass-bmc
  • Host memory errors can now be reported to AArch64 KVM guests via ACPI when using the 'virt' board (this is disabled by default; enable with '-machine ras=on')
  • All the imx6 and imx7 machines now support the watchdog timer device
  • The Raspberry Pi boards now support the USB controller. Note that for the moment booting a Raspbian guest kernel requires adding "dwc_otg.fiq_fsm_enable=0" to the guest kernel command line.
  • MPS2 board models have a few new devices (watchdog, S2I, I2C)
  • The "virt" board now supports hot-remove of memory
  • Some arm boards used to automatically create a fake "empty" SD card if none was provided on the command line; these boards now correctly emulate an SD controller with no SD card present in this situation.


  • QEMU now supports some AVR CPUs and related boards: Arduino Duemilanove (ATmega168), Arduino Mega 2560 (ATmega2560), Arduino Mega (ATmega1280) and Arduino UNO (ATmega328P).




  • Added support for two Loongson 3A CPUs.
  • Loongson MMI ASE is now emulated completely.
  • Hardware page walker and CMMGR features enabled for P5600 CPU.
  • Performance of all FPU instructions for all ISAs is slightly improved.
  • Performance of all MSA FPU instructions is slightly improved.
  • Performance of a number of MSA non-FPU instructions is slightly improved.
  • Fulong 2E machine is renamed to Fuloong 2E.




  • The "label-size" property is now mandatory for NVDIMMs on the "pseries" machine type (the PAPR specification only supports labelled NVDIMMs)
  • NVLink2 devices can no longer be unplugged. This is not possible on real hardware, and was never supported by the guest side drivers, so this makes things safer.
  • We no longer use reconfiguration reboots to handle difficult cases during CAS option negotiation
  • Added an interface to inject POWER style NMIs
  • scv and rfscv instructions now supported in TCG
  • Can now select POWER10 with the "pseries" machine type
  • Fix regression when booting from virtio-blk-pci devices for the g3beige/mac99 machines (OpenBIOS)

Renesas RX

  • RX GDB simulator added (as machines gdbsim-r5f562n7 and gdbsim-r5f562n8)

Renesas SH


  • OpenSBI loaded by default for virt and sifive_u machines
  • The spike_v1.9.1 and spike_v1.10 machines have been removed
  • The rv32gcsu-v1.9.1, rv32gcsu-v1.10.0, rv64gcsu-v1.9.1, rv64gcsu-v1.10.0, rv32imacu-nommu and rv64imacu-nommu CPUs have been removed
  • The RISC-V privilege spec 1.09.1 has been removed
  • Spike machine supports more then 1 CPU
  • Spike machine supports the -bios option
  • OpenSBI updated to v0.7
  • Support for OpenSBI firmware dynamic support
  • Experimental support for the v0.7.1 Vector extensions
  • linux-usermode improvements
  • Expose a "serial" property for the sifive_u machine that specifys the board serial number
  • Expose a "msel" property for the sifive_u machine that specifys the MSEL pin state
  • Support for the SiFive E34 CPU
  • Support for the Ibex CPU
  • Support for the SiFive HiFive1 revB
  • Support for the OpenTitan machine (opentitan) with PLIC and UART support
  • 32-bit improvements for the sifive_u machine
  • Corrections to the Hypervisor extension page table walking
  • Checks implemented when running the hfence instruction
  • Support for booting U-Boot on the sifive_u machine


  • Support for protected virtualization aka secure execution has been merged (KVM only)
    • The host needs to be a z15 or Linux One III with at least Linux 5.7
  • vfio-ccw devices no longer require that the issuer sets the 'allow prefetch' bit in the ORB
    • The host kernel still may reject those requests, though (5.7 or older)
    • Note that a channel program that actually relies on no prefetching being done will still fail. In practice, though, this only applies to IPL CCWs, and that process is accommodated by the s390-ccw bios already.
    • The 'force-orb-pfch' property to force setting of the 'allow prefetch' bit by vfio-ccw itself still exists.
  • vfio-ccw now contains basic support for relaying changes of the path state to the guest


  • Fix booting SPARC64 kernels directly via -kernel (OpenBIOS)
  • Fix regression when booting from virtio-blk-pci devices for the sun4u machine (OpenBIOS)



  • Add gdb stub
  • Fix segfault due to uninitialized ctx->env ptr


  • Improve integration between QEMU monitor and HVF accel on macOS (e.g. "info registers" displays state of CPU registers)
  • Fix an issue with HVF accel where guests stop responding to interrupts
  • Fix an issue with boot from floppy on isapc and 486 cpu (applies for all accels)
  • Support for live migration of AMD systems with nested virtualization


Device emulation and assignment


  • QEMU now exposes a WAET (Windows ACPI Emulated Devices Table) to guests -

this reduces virtualization overhead for non-enlightened windows (Vista and later) guests by avoiding guest workarounds for an unreliable ACPI PM timer.

  • QEMU now supports both cold and hot plug of nvdimms for ARM Guests with ACPI.


Block devices

  • The maximum logical and physical blocksizes for virtual storage devices have been increased from 32 KiB to 2 MiB.
  • The limit for min_io_size has been increased from 65536 bytes to 65536 logical blocks.
  • The options min_io_size, opt_io_size and discard_granularity accept the usual size unit suffixes (k for kilobytes, M for megabytes etc.) now.


Input devices


Network devices



  • Introduce PMR support from NVMe 1.4 spec
  • Add the max_ioqpairs device parameter. The parameter specifies the maximum number of supported I/O queue pairs and should be used instead of the num_queues parameter. num_queues is not formally deprecated, but the device will issue a warning if used. If neither num_queues nor max_ioqpairs are specified, device behavior is unchanged from the previous default.
  • Add the msix_qsize parameter. The parameter specifies the maximum number of msix interrupt vectors supported by the device. If not specified, device behavior is unchanged from the previous default.


Attempts to hotplug devices into a pci slot with hotplug disabled will now return an error instead of adding the device without notifying the guest.


SD card

Images not multiple of power of 2 are not allowed any longer and have to be expanded to a power of 2.






  • TCG guests can now use vhost-user daemons (including virtiofsd). There are corner cases which could interfere with TCG's self-modifying code detection although this shouldn't occur with sane guest OSes.
  • The virtio code (PCI and CCW) now enforces that newer devices for which legacy support has never been specified indeed show up as virtio-1.0 or later only.
    • For most devices this should be not noticeable; for virtio-iommu-pci, you may need to specify the device as modern only.
  • A new feature, VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS, has been added to the vhost-user protocol. VMs with vhost-user device backends which support this feature will not be subject to the current max RAM slots limit of 8 and will be able to hot-add memory as many times as the target platform supports.
  • A first version of virtio-mem, including virtio-mem-pci, for x86-64 has been included in QEMU. virtio-mem allows for fine-grained, NUMA-aware memory hot(un)plug for VMs, avoiding many limitations known from memory ballooning (virtio-balloon) and DIMM-based memory hot(un)plug. Linux guests support virito-mem with v5.8. More information can be found at





  • virtiofsd:
    • Security fix: CVE-2020-10717, resource exhaustion of host fd's
    • Jailing improvements
    • Ensure that existing mounts under the shared directory are visible to the guest



Character devices

  • The 'socket' backend now supports the abstract namespace for UNIX sockets, with the new 'abstract' and 'tight' options

Crypto subsystem

  • Support for passing secrets to QEMU via the Linux keyring, using the "secret-keyring" object type.
  • Add ability to disable all RNG sources at build time for constrained use cases not requiring this functionality.
  • Added support for LUKS keyslot management via qemu-img amend and via qmp (experimental)

Typical usage:

  • Adding new keyslot
qemu-img amend \
      --object secret,id=sec0,data=current_password \
      --object secret,id=sec1,data=new_password \
      --image-opts driver=luks,file.filename=test.luks,key-secret=sec0 \ #image has to be opened with --image-opts to pass current secret
      -o state=active,new-secret=sec1,[keyslot=1] #keyslot is optional

  • Erasing a keyslot that contains an old password.

qemu-img amend \
      --object secret,id=sec0,data=current_password \
      --object secret,id=sec1,data=new_password \
      --image-opts driver=luks,file.filename=test.luks,key-secret=sec0 \
      -o state=inactive,old-secret=sec1 

Note that you can't erase last keyslot since that will make image non-recoverable.

If you insist to destroy the data by erasing last keyslot you can pass --force to qemu-img for that purpose.

You can also erase a specific keyslot. The comment about last keyslot applies here as well.

qemu-img amend \
      --object secret,id=sec0,data=current_password \
      --object secret,id=sec1,data=new_password \
      --image-opts driver=luks,file.filename=test.luks,key-secret=sec0 \
      -o state=inactive,keyslot=sec1 

The same interface is also available for qcow2 encrypted images in similar matter:

qemu-img amend \
      --object secret,id=sec0,data=current_password \
      --object secret,id=sec1,data=new_password  \
       --image-opts driver=qcow2,file.filename=test.qcow2,encrypt.key-secret=sec0 \

experimental qmp interface

x-blockdev-amend was added with similiar interface to blockdev-create, which accepts driver specific options.

It is currently only defined for luks and qcow2

Open an image:

{'execute': 'object-add', 'arguments': {'qom-type': 'secret', 'id': 'keysec0', 'props': {'data': 'current_password'}}}
{'execute': 'object-add', 'arguments': {'qom-type': 'secret', 'id': 'keysec1', 'props': {'data': 'new_password'}}}
{'execute': 'blockdev-add', 'arguments': {'driver': 'qcow2', 'node-name': 'testdev', 'read-only': False, 'encrypt': {
 'format': 'luks', 'key-secret': 'keysec0'}, 'file': {'driver': 'file', 'filename': 'test.qcow2'}}}

Add a new key (as blockdev-create, also uses a job, so job needs to be waited upon)

{'execute': 'x-blockdev-amend', 'arguments': {'node-name': 'testdev', 'job-id': 'my_job_id', 'options': {'driver': 'qcow2', 'encrypt': {'state': 'active', 'new-secret': 'keysec1', 'format': 'luks'}}}}

Remove a key:

{'execute': 'x-blockdev-amend', 'arguments': {'node-name': 'testdev', 'job-id': 'my_job_id', 'options': {'driver': 'qcow2', 'encrypt': {'state': 'inactive', 'old-secret': 'keysec0', 'format': 'luks'}}}}

It is expected that higher-level libraries (e.g libvirt) will make more user friendly interface.


  • Windows keyboard fixes for GTK and SDL


  • bug fix to m68k gdbstub
  • linux-user now supports unix socket for debugging (needs a new gdb)
  • some tests for the stub added to check-tcg
  • wider watchpoints are supported in system emulation mode

Host support

Memory backends


  • Migration of block dirty bitmaps when not using -blockdev now avoids using generated node names; without this fix, a migration attempt that included bitmaps and was attempted while a mirror job was active (which was a common scenario with older libvirt that did not use -blockdev but set up an NBD mirror for storage migration in parallel) would generally fail due to the difference in generated node names between the source and destination.
  • Error handling during migration with block dirty bitmaps is improved. As block dirty bitmaps are not essential to guest operation but merely permit an incremental backup, and as a full backup is always a reliable solution when incremental backup is not possible, any failure to migrate a dirty bitmap is no longer fatal to migration in general. Similarly, migrating when a backing file has a read-only bitmap no longer causes an error when trying to reload that bitmap.



  • "info qom-tree" now shows children sorted.


Block device backends and tools

  • Optional zstd compression for qcow2 (enable with compression_type=zstd as a creation option)
  • file-posix has a new image creation option extent_size_hint that defines an extent size hint that should be added to the image file to help avoiding fragmentation (especially with cache=none or more generally The default is 1M, 0 disables the hint. Note that this optimisation does not apply to existing images and images created outside of QEMU. For example, if you copy images with tools like cp, the copy will not have the extent size hint set and will be as prone to filesystem fragmentation as before.
  • 'qemu-img map' gained --start-offset and --max-length options for mapping only a subset of a file
  • 'qemu-img' gained a new command mode 'bitmap' for manipulating persistent bitmaps in qcow2 files
  • 'qemu-img measure' now reports the space occupied by persistent bitmaps in qcow2 files
  • 'qemu-img convert' gained a new --bitmaps option for convenience in copying bitmaps alongside guest-visible content of qcow2 files
  • Fixed regression with 'qemu-nbd -c /dev/nbd0' keeping inherited stderr open (introduced in 4.1)
  • Fixed regression where a compliant NBD client could cause qemu as NBD server to assert (CVE-2020-10761, introduced in 4.2)
  • Fixed extending resize of overlay images that are shorter than their backing file (this would previously make the backing file content reappear, but it should contain only zeros)
  • Block jobs that copy the image content check now that the source and target image have the same size and return an error if this is not the case. If you are intentionally copying only part of the image, consider using a raw node with a size=... option specified to make only the right size of the larger image visible.
  • file-posix: Fixed read-only Linux block devices with auto-read-only
  • VMDK: Fixed handling of zeroed clusters
  • Fixed bug where NBD trim and zero requests larger than 2G would fail with EIO
  • Fixed bug where NBD reconnect could deadlock in various scenarios
  • NBD now allows no-op resize requests, which in turn permits 'qemu-img convert -c' to an appropriately-sized NBD destination



  • HMP: qom-set can now take JSON for the value with the optional -j flag
  • HMP: new command: qom-get can now be used to read the value of a qom property

User-mode emulation


  • support for wider watchpoints in system emulation
  • support for vhost-user daemons
  • new "lockstep" plugin
  • smarter auto-sizing of tb-size based on host-physical memory. You should still use -tb-size if you run a lot of system emulation at the same time.

Guest agent

Build Information


GIT submodules

Container Based Builds

  • Prebuilt docker images are now stored at the GitLab registry:
  • build framework is now registry aware
  • Updated aarch64 container for bullseye based compiler for testing newer features

Build Dependencies

  • Now requires GTK 3.22 or newer


  • vm-build tests can now use alternatives to genisoimage (cdrkit)
  • new ubuntu.aarch64 and centos.aarch64 vm-build targets
  • Support for --enable-tsan build


Known issues