1.. _Deprecated features: 2 3Deprecated features 4=================== 5 6In general features are intended to be supported indefinitely once 7introduced into QEMU. In the event that a feature needs to be removed, 8it will be listed in this section. The feature will remain functional for the 9release in which it was deprecated and one further release. After these two 10releases, the feature is liable to be removed. Deprecated features may also 11generate warnings on the console when QEMU starts up, or if activated via a 12monitor command, however, this is not a mandatory requirement. 13 14Prior to the 2.10.0 release there was no official policy on how 15long features would be deprecated prior to their removal, nor 16any documented list of which features were deprecated. Thus 17any features deprecated prior to 2.10.0 will be treated as if 18they were first deprecated in the 2.10.0 release. 19 20What follows is a list of all features currently marked as 21deprecated. 22 23System emulator command line arguments 24-------------------------------------- 25 26``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) 27''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 28 29The ``-audiodev`` argument is now the preferred way to specify audio 30backend settings instead of environment variables. To ease migration to 31the new format, the ``-audiodev-help`` option can be used to convert 32the current values of the environment variables to ``-audiodev`` options. 33 34Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) 35'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 36 37When not using the deprecated legacy audio config, each sound card 38should specify an ``audiodev=`` property. Additionally, when using 39vnc, you should specify an ``audiodev=`` property if you plan to 40transmit audio through the VNC protocol. 41 42Creating sound card devices using ``-soundhw`` (since 5.1) 43'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 44 45Sound card devices should be created using ``-device`` instead. The 46names are the same for most devices. The exceptions are ``hda`` which 47needs two devices (``-device intel-hda -device hda-duplex``) and 48``pcspk`` which can be activated using ``-machine 49pcspk-audiodev=<name>``. 50 51``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 52'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 53 54``tty`` and ``parport`` are aliases that will be removed. Instead, the 55actual backend names ``serial`` and ``parallel`` should be used. 56 57Short-form boolean options (since 6.0) 58'''''''''''''''''''''''''''''''''''''' 59 60Boolean options such as ``share=on``/``share=off`` could be written 61in short form as ``share`` and ``noshare``. This is now deprecated 62and will cause a warning. 63 64``delay`` option for socket character devices (since 6.0) 65''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 66 67The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 68rather than ``delay=off``. 69 70``-writeconfig`` (since 6.0) 71''''''''''''''''''''''''''''' 72 73The ``-writeconfig`` option is not able to serialize the entire contents 74of the QEMU command line. It is thus considered a failed experiment 75and deprecated, with no current replacement. 76 77Userspace local APIC with KVM (x86, since 6.0) 78'''''''''''''''''''''''''''''''''''''''''''''' 79 80Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 81APIC is deprecated. The ``split`` setting is supported, as is using 82``-M kernel-irqchip=off`` with the ISA PC machine type. 83 84hexadecimal sizes with scaling multipliers (since 6.0) 85'''''''''''''''''''''''''''''''''''''''''''''''''''''' 86 87Input parameters that take a size value should only use a size suffix 88(such as 'k' or 'M') when the base is written in decimal, and not when 89the value is hexadecimal. That is, '0x20M' is deprecated, and should 90be written either as '32M' or as '0x2000000'. 91 92``-spice password=string`` (since 6.0) 93'''''''''''''''''''''''''''''''''''''' 94 95This option is insecure because the SPICE password remains visible in 96the process listing. This is replaced by the new ``password-secret`` 97option which lets the password be securely provided on the command 98line using a ``secret`` object instance. 99 100``opened`` property of ``rng-*`` objects (since 6.0) 101'''''''''''''''''''''''''''''''''''''''''''''''''''' 102 103The only effect of specifying ``opened=on`` in the command line or QMP 104``object-add`` is that the device is opened immediately, possibly before all 105other options have been processed. This will either have no effect (if 106``opened`` was the last option) or cause errors. The property is therefore 107useless and should not be specified. 108 109``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0) 110'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 111 112The only effect of specifying ``loaded=on`` in the command line or QMP 113``object-add`` is that the secret is loaded immediately, possibly before all 114other options have been processed. This will either have no effect (if 115``loaded`` was the last option) or cause options to be effectively ignored as 116if they were not given. The property is therefore useless and should not be 117specified. 118 119``-display sdl,window_close=...`` (since 6.1) 120''''''''''''''''''''''''''''''''''''''''''''' 121 122Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of 123an underscore between "window" and "close"). 124 125``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2) 126'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 127 128Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. 129 130``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2) 131'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 132 133Use ``-display sdl,grab-mod=rctrl`` instead. 134 135``-sdl`` (since 6.2) 136'''''''''''''''''''' 137 138Use ``-display sdl`` instead. 139 140``-curses`` (since 6.2) 141''''''''''''''''''''''' 142 143Use ``-display curses`` instead. 144 145``-watchdog`` (since 6.2) 146''''''''''''''''''''''''' 147 148Use ``-device`` instead. 149 150``-smp`` ("parameter=0" SMP configurations) (since 6.2) 151''''''''''''''''''''''''''''''''''''''''''''''''''''''' 152 153Specified CPU topology parameters must be greater than zero. 154 155In the SMP configuration, users should either provide a CPU topology 156parameter with a reasonable value (greater than zero) or just omit it 157and QEMU will compute the missing value. 158 159However, historically it was implicitly allowed for users to provide 160a parameter with zero value, which is meaningless and could also possibly 161cause unexpected results in the -smp parsing. So support for this kind of 162configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 163be removed in the near future, users have to ensure that all the topology 164members described with -smp are greater than zero. 165 166Plugin argument passing through ``arg=<string>`` (since 6.1) 167'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 168 169Passing TCG plugins arguments through ``arg=`` is redundant is makes the 170command-line less readable, especially when the argument itself consist of a 171name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 172Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 173as short-form boolean values, and passed to plugins as ``arg_name=on``. 174However, short-form booleans are deprecated and full explicit ``arg_name=on`` 175form is preferred. 176 177``-drive if=none`` for the sifive_u OTP device (since 6.2) 178'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 179 180Using ``-drive if=none`` to configure the OTP device of the sifive_u 181RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 182 183 184QEMU Machine Protocol (QMP) commands 185------------------------------------ 186 187``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 188''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 189 190Use argument ``id`` instead. 191 192``eject`` argument ``device`` (since 2.8) 193''''''''''''''''''''''''''''''''''''''''' 194 195Use argument ``id`` instead. 196 197``blockdev-change-medium`` argument ``device`` (since 2.8) 198'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 199 200Use argument ``id`` instead. 201 202``block_set_io_throttle`` argument ``device`` (since 2.8) 203''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 204 205Use argument ``id`` instead. 206 207``blockdev-add`` empty string argument ``backing`` (since 2.10) 208''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 209 210Use argument value ``null`` instead. 211 212``block-commit`` arguments ``base`` and ``top`` (since 3.1) 213''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 214 215Use arguments ``base-node`` and ``top-node`` instead. 216 217``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 218'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 219 220Use the more generic commands ``block-export-add`` and ``block-export-del`` 221instead. As part of this deprecation, where ``nbd-server-add`` used a 222single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 223 224``query-qmp-schema`` return value member ``values`` (since 6.2) 225''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 226 227Member ``values`` in return value elements with meta-type ``enum`` is 228deprecated. Use ``members`` instead. 229 230``drive-backup`` (since 6.2) 231'''''''''''''''''''''''''''' 232 233Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 234This change primarily separates the creation/opening process of the backup 235target with explicit, separate steps. ``blockdev-backup`` uses mostly the 236same arguments as ``drive-backup``, except the ``format`` and ``mode`` 237options are removed in favor of using explicit ``blockdev-create`` and 238``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 239details. 240 241Incorrectly typed ``device_add`` arguments (since 6.2) 242'''''''''''''''''''''''''''''''''''''''''''''''''''''' 243 244Due to shortcomings in the internal implementation of ``device_add``, QEMU 245incorrectly accepts certain invalid arguments: Any object or list arguments are 246silently ignored. Other argument types are not checked, but an implicit 247conversion happens, so that e.g. string values can be assigned to integer 248device properties or vice versa. 249 250This is a bug in QEMU that will be fixed in the future so that previously 251accepted incorrect commands will return an error. Users should make sure that 252all arguments passed to ``device_add`` are consistent with the documented 253property types. 254 255``query-sgx`` return value member ``section-size`` (since 7.0) 256'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 257 258Member ``section-size`` in return value elements with meta-type ``uint64`` is 259deprecated. Use ``sections`` instead. 260 261 262``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 263''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 264 265Member ``section-size`` in return value elements with meta-type ``uint64`` is 266deprecated. Use ``sections`` instead. 267 268System accelerators 269------------------- 270 271MIPS ``Trap-and-Emul`` KVM support (since 6.0) 272'''''''''''''''''''''''''''''''''''''''''''''' 273 274The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 275from Linux upstream kernel, declare it deprecated. 276 277System emulator CPUS 278-------------------- 279 280``Icelake-Client`` CPU Model (since 5.2) 281'''''''''''''''''''''''''''''''''''''''' 282 283``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 284Models instead. 285 286MIPS ``I7200`` CPU Model (since 5.2) 287'''''''''''''''''''''''''''''''''''' 288 289The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 290(the ISA has never been upstreamed to a compiler toolchain). Therefore 291this CPU is also deprecated. 292 293 294QEMU API (QAPI) events 295---------------------- 296 297``MEM_UNPLUG_ERROR`` (since 6.2) 298'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 299 300Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 301 302 303System emulator machines 304------------------------ 305 306PPC 405 ``taihu`` machine (since 7.0) 307''''''''''''''''''''''''''''''''''''' 308 309The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar, 310except for some external periphery. However, the periphery of the ``taihu`` 311machine is hardly emulated at all (e.g. neither the LCD nor the USB part had 312been implemented), so there is not much value added by this board. Use the 313``ref405ep`` machine instead. 314 315``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) 316''''''''''''''''''''''''''''''''''''''''''''''''''''' 317 318These old machine types are quite neglected nowadays and thus might have 319various pitfalls with regards to live migration. Use a newer machine type 320instead. 321 322 323Backend options 324--------------- 325 326Using non-persistent backing file with pmem=on (since 6.1) 327'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 328 329This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 330device. However enabling ``memory-backend-file.pmem`` option, when backing file 331is (a) not DAX capable or (b) not on a filesystem that support direct mapping 332of persistent memory, is not safe and may lead to data loss or corruption in case 333of host crash. 334Options are: 335 336 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 337 (without persistence guaranties) with backing file on non DAX storage 338 - move backing file to NVDIMM storage and keep ``pmem=on`` 339 (to have NVDIMM with persistence guaranties). 340 341Device options 342-------------- 343 344Emulated device options 345''''''''''''''''''''''' 346 347``-device virtio-blk,scsi=on|off`` (since 5.0) 348^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 349 350The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 351and later do not support it because the virtio-scsi device was introduced for 352full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 353 354Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 355alias. 356 357``-device sga`` (since 6.2) 358^^^^^^^^^^^^^^^^^^^^^^^^^^^ 359 360The ``sga`` device loads an option ROM for x86 targets which enables 361SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 362contains native support for this feature and thus use of the option 363ROM approach is obsolete. The native SeaBIOS support can be activated 364by using ``-machine graphics=off``. 365 366 367Block device options 368'''''''''''''''''''' 369 370``"backing": ""`` (since 2.12) 371^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 372 373In order to prevent QEMU from automatically opening an image's backing 374chain, use ``"backing": null`` instead. 375 376``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 378 379Options for ``rbd`` should be specified according to its runtime options, 380like other block drivers. Legacy parsing of keyvalue pair encoded 381filenames is useful to open images with the old format for backing files; 382These image files should be updated to use the current format. 383 384Example of legacy encoding:: 385 386 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 387 388The above, converted to the current supported format:: 389 390 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 391 392linux-user mode CPUs 393-------------------- 394 395MIPS ``I7200`` CPU (since 5.2) 396'''''''''''''''''''''''''''''' 397 398The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 399(the ISA has never been upstreamed to a compiler toolchain). Therefore 400this CPU is also deprecated. 401 402Backwards compatibility 403----------------------- 404 405Runnability guarantee of CPU models (since 4.1) 406''''''''''''''''''''''''''''''''''''''''''''''' 407 408Previous versions of QEMU never changed existing CPU models in 409ways that introduced additional host software or hardware 410requirements to the VM. This allowed management software to 411safely change the machine type of an existing VM without 412introducing new requirements ("runnability guarantee"). This 413prevented CPU models from being updated to include CPU 414vulnerability mitigations, leaving guests vulnerable in the 415default configuration. 416 417The CPU model runnability guarantee won't apply anymore to 418existing CPU models. Management software that needs runnability 419guarantees must resolve the CPU model aliases using the 420``alias-of`` field returned by the ``query-cpu-definitions`` QMP 421command. 422 423While those guarantees are kept, the return value of 424``query-cpu-definitions`` will have existing CPU model aliases 425point to a version that doesn't break runnability guarantees 426(specifically, version 1 of those CPU models). In future QEMU 427versions, aliases will point to newer CPU model versions 428depending on the machine type, so management software must 429resolve CPU model aliases before starting a virtual machine. 430 431Guest Emulator ISAs 432------------------- 433 434nanoMIPS ISA 435'''''''''''' 436 437The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 438As it is hard to generate binaries for it, declare it deprecated. 439 440Tools 441----- 442 443virtiofsd 444''''''''' 445 446There is a new Rust implementation of ``virtiofsd`` at 447``https://gitlab.com/virtio-fs/virtiofsd``; 448since this is now marked stable, new development should be done on that 449rather than the existing C version in the QEMU tree. 450The C version will still accept fixes and patches that 451are already in development for the moment, but will eventually 452be deleted from this tree. 453New deployments should use the Rust version, and existing systems 454should consider moving to it. The command line and feature set 455is very close and moving should be simple. 456