Features/LegacyRemoval

From QEMU
Jump to: navigation, search

Note: This page is used to gather ideas about deprecated features and interfaces, the lists here are by no means mandatory! For a list of features / interfaces that have really been deprecated, please visit https://qemu.weilnetz.de/doc/qemu-doc.html#Deprecated-features instead.

Problem description

QEMU has a lot of interfaces (like command line options or HMP commands) and old features (like certain machine types) which are considered as deprecated since other more generic interfaces/features have been established instead. We likely don't want to carry the old code around forever. But we also do not want to remove it immediately to give the users and upper layer software stacks (like libvirt) a chance to migrate to the new interfaces step by step. So this page is about collecting information and ideas about which interfaces/features are considered as obsolete and when they should be removed.

Rules for removing an interface

Before an interface can be removed, there needs to be a clear transition plan for doing so. This means it should be added to the deprecation chapter in the qemu-doc file (see link at the top of this page), and that there have to be at least two public releases of QEMU where the interface still works after it ha been deprecated. Two public releases are required so that the users have at least one development cycle to complain if they think that there is a good reason that the interface should not be removed. Ideally the code should also emit a warning that says that the feature / interface is deprecated / going away soon, with a pointer to documentation or similar information about its replacement syntax.

Deprecated command line parameters

Parameter Rationale Deprecated in Removed in
-net channel Replaced by "-netdev user,guestfwd=..."

(and is even not documented, i.e. hardly used in the wild)

v2.6.0 v2.12.0
-net dump Replaced by "-object filter-dump,..." v2.10.0 v2.12.0
-smb Replaced by "-netdev user,smb=..." v2.6.0 TBD
-tftp Replaced by "-netdev user,tftp=..." v2.6.0 TBD
-bootp Replaced by "-netdev user,bootfile=..." v2.6.0 TBD
-redir Replaced by "-netdev user,hostfwd=..." v2.6.0 TBD
-tdf Dummy legacy option from qemu-kvm v1.3.0 v2.12.0
-usbdevice Replaced by the generic -device parameter v2.10.0 partly in v2.12.0
-mon ...,default=on The "default" parameter does nothing anymore v2.8.0 v2.12.0
-hdachs Replaced by options on "-device" v2.10.0 v2.12.0
-drive boot= Dummy legacy option from qemu-kvm v1.3.0 v2.12.0
-drive serial=
-drive trans=
-drive secs=
-drive heads=
-drive cyls=
-drive addr=
Replaced by options on "-device". v2.10.0 v3.0
-localtime Undocumented. Replace by -rtc base=localtime v2.12.0 TBD
-startdate Undocumented. Replaced by -rtc option v2.12.0 TBD
-rtc-td-hack Replaced by -rtc option v2.12.0 TBD
-no-kvm Not necessary anymore, TCG is default v1.3.0 TBD
-no-kvm-irqchip Use "-machine kernel_irqchip=off" instead v1.3.0 v3.0
-no-kvm-pit Dummy legacy option from qemu-kvm v1.3.0 v2.12.0
-no-kvm-pit-reinjection Legacy option from qemu-kvm v1.3.0 v3.0
-vnc …,tls=… Deprecated in favour of tls-creds v2.5.0 TBD
-vnc …,x509=… Deprecated in favour of tls-creds v2.5.0 TBD
-vnc …,x509verify=… Deprecated in favour of tls-creds v2.5.0 TBD
-fsdev handle Use "-fsdev local" instead v2.12.0 TBD
-clock Silently ignored for compatibility v3.0 TBD

Future candidates

Parameter Rationale
-net Replaced by "-netdev id=netdev0 -device e1000,netdev=netdev0" or the new -nic option
-drive media= Replaced by parameter on -device
-drive Replaced by "-blockdev" and "-device". Need to check that all devices automatically created by machines are still configurable, and "-blockdev" also needs better documentation first.
-enable-kvm Use "-accel kvm" instead
-enable-hax Use "-accel hax" instead

Deprecated qemu-img parameters

Parameter Rationale Deprecated in Removed in
snapshot_id_or_name Use snapshot_param instead v2.0.0 TBD
-b <invalid-image> Old QEMU versions did not check the validity of the given backing file string in qemu-img create unless the backing file needed to be opened for getting its size. Such checks are wanted and need to be disabled explicitly with -u now if necessary. v2.10.0 TBD
-e -o encryption v0.14 v2.10.0
-6 -o compat6 v0.14 v2.10.0

Deprecated HMP commands

Parameter Rationale Deprecated in Removed in
usb_add, usb_remove Replaced by "device_add" and "device_del" v2.10.0 v2.12.0
host_net_add, host_net_remove Replaced by "netdev_add" and "netdev_del" v2.10.0 v2.12.0

Future candidates

Parameter Rationale
migrate_set_downtime, migrate_set_speed Replaced by "migrate_set_parameter" since v2.8

Deprecated machines

Machine Rationale Deprecated in Removed in
xlnx-ep108 The EP108 was an early access development board that is no longer used. v2.11 v3.0
pc-0.10 and pc-0.11 Oldest QEMU version that is likely still used in the wild is 0.12 (CentOS 6) v3.0 TBD
prep (ppc) Obsoleted by the "40p" machine v3.1 TBD

Future candidates

Machine Rationale
isapc (x86) It's still under discussion whether we should keep this machine or not. Guests should be able to use "pc" instead, but firmware and OS code paths would be different, and it helps to remind us that there is also a world without PCI / ACPI / APIC, so to a small degree, this machine is still useful.

Deprecated machine options

Option Machine Rationale Deprecated in Removed in
s390-squash-mcss s390-ccw-virtio Made obsolete by unrestricting cssids v2.12.0 TBD

Deprecated devices

Device Rationale Deprecated in Removed in
spapr-pci-vfio-host-bridge See commit 72700d7e733948fa v2.6.0 v2.12.0
ivshmem Replaced by either the "ivshmem-plain" or "ivshmem-doorbell" v2.6.0 TBD
ide-device Replaced by "ide-cd" and "ide-hd" v0.15.0 ? TBD
scsi-disk Replaced by "scsi-cd" and "scsi-hd" v0.15.0 ? TBD

Future candidates

Device Rationale
isa-vga unused when isapc machine type goes away
isa-cirrus-vga unused when isapc machine type goes away
ne2k_isa unused when isapc machine type goes away

Alternatively: drop media=cdrom, make ide-hd and scsi-hd synonyms for ide-disk and scsi-disk.

Miscellaneous

Certain host OS / CPUs are currently unmaintained, and we've got no build machine available for those, so they are scheduled for removal:

  • AIX as host OS (Removed in 2.11)
  • Solaris 9 as host OS (Removed in 2.10)
  • The Itanium ia64 TCG backend (Removed in 2.11)

We also might want to drop support for older versions of libraries that are needed for building QEMU:

  • SDL 1.2 (since SDL 2.0 is established nowadays)
  • GTK 2 (since GTK 3 is established nowadays)