Features/LegacyRemoval

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 this wiki page, and that there have to be at least two public releases of QEMU where the interface still works, but issues a warning when used. 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. The warning should say that the 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	Removal in
-net channel	Replaced by "-netdev user,guestfwd=..." (and is even not documented, i.e. hardly used in the wild)	v2.6.0	v3.0.0
-net dump	Replaced by "-object filter-dump,..."	v2.10.0	v3.0.0
-smb	Replaced by "-netdev user,smb=..."	v2.6.0	v3.0.0
-tftp	Replaced by "-netdev user,tftp=..."	v2.6.0	v3.0.0
-bootp	Replaced by "-netdev user,bootfile=..."	v2.6.0	v3.0.0
-redir	Replaced by "-netdev user,hostfwd=..."	v2.6.0	v3.0.0
-hdachs	Replaced by options on "-device"	v2.10.0	v3.0.0
-drive boot=	Dummy legacy option from qemu-kvm	v1.3.0	v3.0.0
-no-kvm-pit	Dummy legacy option from qemu-kvm	v1.3.0	v3.0.0
-no-kvm-pit-reinjection	Legacy option from qemu-kvm	v1.3.0	v3.0.0
-tdf	Dummy legacy option from qemu-kvm	v1.3.0	v3.0.0
-usbdevice	Replaced by the generic -device parameter	v2.10.0	v3.0.0
-drive serial= -drive trans= -drive secs= -drive heads= -drive cyls= -drive addr=	Replaced by options on "-device".	v2.10.0	v3.0.0

Future candidates

Parameter	Rationale
-net	Replaced by "-netdev id=netdev0 -device e1000,netdev=netdev0". There are several loose ends: what about machine type built-in NICs that use nd_table[]? Can vlan command-line options be removed in some places?
-netdev hubport	Should be removed in line with the 'vlan' concept of the -net parameter
-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
-no-kvm	Not necessary anymore, TCG is default
-localtime	Undocumented. Replace by -rtc base=localtime
-startdate	Undocumented. Replaced by -rtc option
-clock	Silently ignored for compatibility

Deprecated qemu-img parameters

Parameter	Rationale	Deprecated in	Removal in
snapshot_id_or_name	Use snapshot_param instead	v2.0.0	v3.0.0
-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	v3.0.0
-e	-o encryption	v0.14	v2.10.0
-6	-o compat6	v0.14	v2.10.0

Deprecated HMP commands

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

Future candidates

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

Deprecated machines

Future candidates

Machine	Rationale
prep (ppc)	Obsoleted by the "40p" machine
isapc (x86)	guests should be able to use "pc" instead (but firmware code paths would be different, do we care?)
pc-0.10 and pc-0.11	Oldest QEMU version that is likely still used in the wild is 0.12 (CentOS 6)

Deprecated devices

Device	Rationale	Deprecated in	Removal in
spapr-pci-vfio-host-bridge	See commit 72700d7e733948fa	v2.6.0	v3.0.0
ide-device	Replaced by "ide-cd" and "ide-hd"	v0.15.0	v3.0.0 ?
scsi-disk	Replaced by "scsi-cd" and "scsi-hd"	v0.15.0	v3.0.0 ?

Future candidates

Machine	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
• Solaris as host OS
• The Itanium ia64 TCG backend

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)