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``--enable-fips`` (since 6.0) 71''''''''''''''''''''''''''''' 72 73This option restricts usage of certain cryptographic algorithms when 74the host is operating in FIPS mode. 75 76If FIPS compliance is required, QEMU should be built with the ``libgcrypt`` 77library enabled as a cryptography provider. 78 79Neither the ``nettle`` library, or the built-in cryptography provider are 80supported on FIPS enabled hosts. 81 82``-writeconfig`` (since 6.0) 83''''''''''''''''''''''''''''' 84 85The ``-writeconfig`` option is not able to serialize the entire contents 86of the QEMU command line. It is thus considered a failed experiment 87and deprecated, with no current replacement. 88 89Userspace local APIC with KVM (x86, since 6.0) 90'''''''''''''''''''''''''''''''''''''''''''''' 91 92Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 93APIC is deprecated. The ``split`` setting is supported, as is using 94``-M kernel-irqchip=off`` with the ISA PC machine type. 95 96hexadecimal sizes with scaling multipliers (since 6.0) 97'''''''''''''''''''''''''''''''''''''''''''''''''''''' 98 99Input parameters that take a size value should only use a size suffix 100(such as 'k' or 'M') when the base is written in decimal, and not when 101the value is hexadecimal. That is, '0x20M' is deprecated, and should 102be written either as '32M' or as '0x2000000'. 103 104``-spice password=string`` (since 6.0) 105'''''''''''''''''''''''''''''''''''''' 106 107This option is insecure because the SPICE password remains visible in 108the process listing. This is replaced by the new ``password-secret`` 109option which lets the password be securely provided on the command 110line using a ``secret`` object instance. 111 112``opened`` property of ``rng-*`` objects (since 6.0) 113'''''''''''''''''''''''''''''''''''''''''''''''''''' 114 115The only effect of specifying ``opened=on`` in the command line or QMP 116``object-add`` is that the device is opened immediately, possibly before all 117other options have been processed. This will either have no effect (if 118``opened`` was the last option) or cause errors. The property is therefore 119useless and should not be specified. 120 121``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0) 122'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 123 124The only effect of specifying ``loaded=on`` in the command line or QMP 125``object-add`` is that the secret is loaded immediately, possibly before all 126other options have been processed. This will either have no effect (if 127``loaded`` was the last option) or cause options to be effectively ignored as 128if they were not given. The property is therefore useless and should not be 129specified. 130 131``-display sdl,window_close=...`` (since 6.1) 132''''''''''''''''''''''''''''''''''''''''''''' 133 134Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of 135an underscore between "window" and "close"). 136 137``-no-quit`` (since 6.1) 138'''''''''''''''''''''''' 139 140The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which 141should be used instead. 142 143``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2) 144'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 145 146Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. 147 148``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2) 149'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 150 151Use ``-display sdl,grab-mod=rctrl`` instead. 152 153``-sdl`` (since 6.2) 154'''''''''''''''''''' 155 156Use ``-display sdl`` instead. 157 158``-curses`` (since 6.2) 159''''''''''''''''''''''' 160 161Use ``-display curses`` instead. 162 163``-watchdog`` (since 6.2) 164''''''''''''''''''''''''' 165 166Use ``-device`` instead. 167 168``-smp`` ("parameter=0" SMP configurations) (since 6.2) 169''''''''''''''''''''''''''''''''''''''''''''''''''''''' 170 171Specified CPU topology parameters must be greater than zero. 172 173In the SMP configuration, users should either provide a CPU topology 174parameter with a reasonable value (greater than zero) or just omit it 175and QEMU will compute the missing value. 176 177However, historically it was implicitly allowed for users to provide 178a parameter with zero value, which is meaningless and could also possibly 179cause unexpected results in the -smp parsing. So support for this kind of 180configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 181be removed in the near future, users have to ensure that all the topology 182members described with -smp are greater than zero. 183 184Plugin argument passing through ``arg=<string>`` (since 6.1) 185'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 186 187Passing TCG plugins arguments through ``arg=`` is redundant is makes the 188command-line less readable, especially when the argument itself consist of a 189name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 190Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 191as short-form boolean values, and passed to plugins as ``arg_name=on``. 192However, short-form booleans are deprecated and full explicit ``arg_name=on`` 193form is preferred. 194 195``-drive if=none`` for the sifive_u OTP device (since 6.2) 196'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 197 198Using ``-drive if=none`` to configure the OTP device of the sifive_u 199RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 200 201 202QEMU Machine Protocol (QMP) commands 203------------------------------------ 204 205``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 206''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 207 208Use argument ``id`` instead. 209 210``eject`` argument ``device`` (since 2.8) 211''''''''''''''''''''''''''''''''''''''''' 212 213Use argument ``id`` instead. 214 215``blockdev-change-medium`` argument ``device`` (since 2.8) 216'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 217 218Use argument ``id`` instead. 219 220``block_set_io_throttle`` argument ``device`` (since 2.8) 221''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 222 223Use argument ``id`` instead. 224 225``blockdev-add`` empty string argument ``backing`` (since 2.10) 226''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 227 228Use argument value ``null`` instead. 229 230``block-commit`` arguments ``base`` and ``top`` (since 3.1) 231''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 232 233Use arguments ``base-node`` and ``top-node`` instead. 234 235``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 236'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 237 238Use the more generic commands ``block-export-add`` and ``block-export-del`` 239instead. As part of this deprecation, where ``nbd-server-add`` used a 240single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 241 242``query-qmp-schema`` return value member ``values`` (since 6.2) 243''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 244 245Member ``values`` in return value elements with meta-type ``enum`` is 246deprecated. Use ``members`` instead. 247 248``drive-backup`` (since 6.2) 249'''''''''''''''''''''''''''' 250 251Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 252This change primarily separates the creation/opening process of the backup 253target with explicit, separate steps. ``blockdev-backup`` uses mostly the 254same arguments as ``drive-backup``, except the ``format`` and ``mode`` 255options are removed in favor of using explicit ``blockdev-create`` and 256``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 257details. 258 259Incorrectly typed ``device_add`` arguments (since 6.2) 260'''''''''''''''''''''''''''''''''''''''''''''''''''''' 261 262Due to shortcomings in the internal implementation of ``device_add``, QEMU 263incorrectly accepts certain invalid arguments: Any object or list arguments are 264silently ignored. Other argument types are not checked, but an implicit 265conversion happens, so that e.g. string values can be assigned to integer 266device properties or vice versa. 267 268This is a bug in QEMU that will be fixed in the future so that previously 269accepted incorrect commands will return an error. Users should make sure that 270all arguments passed to ``device_add`` are consistent with the documented 271property types. 272 273System accelerators 274------------------- 275 276MIPS ``Trap-and-Emul`` KVM support (since 6.0) 277'''''''''''''''''''''''''''''''''''''''''''''' 278 279The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 280from Linux upstream kernel, declare it deprecated. 281 282System emulator CPUS 283-------------------- 284 285``Icelake-Client`` CPU Model (since 5.2) 286'''''''''''''''''''''''''''''''''''''''' 287 288``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 289Models instead. 290 291MIPS ``I7200`` CPU Model (since 5.2) 292'''''''''''''''''''''''''''''''''''' 293 294The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 295(the ISA has never been upstreamed to a compiler toolchain). Therefore 296this CPU is also deprecated. 297 298 299QEMU API (QAPI) events 300---------------------- 301 302``MEM_UNPLUG_ERROR`` (since 6.2) 303'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 304 305Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 306 307 308System emulator machines 309------------------------ 310 311Aspeed ``swift-bmc`` machine (since 6.1) 312'''''''''''''''''''''''''''''''''''''''' 313 314This machine is deprecated because we have enough AST2500 based OpenPOWER 315machines. It can be easily replaced by the ``witherspoon-bmc`` or the 316``romulus-bmc`` machines. 317 318Backend options 319--------------- 320 321Using non-persistent backing file with pmem=on (since 6.1) 322'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 323 324This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 325device. However enabling ``memory-backend-file.pmem`` option, when backing file 326is (a) not DAX capable or (b) not on a filesystem that support direct mapping 327of persistent memory, is not safe and may lead to data loss or corruption in case 328of host crash. 329Options are: 330 331 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 332 (without persistence guaranties) with backing file on non DAX storage 333 - move backing file to NVDIMM storage and keep ``pmem=on`` 334 (to have NVDIMM with persistence guaranties). 335 336Device options 337-------------- 338 339Emulated device options 340''''''''''''''''''''''' 341 342``-device virtio-blk,scsi=on|off`` (since 5.0) 343^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 344 345The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 346and later do not support it because the virtio-scsi device was introduced for 347full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 348 349Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 350alias. 351 352``-device sga`` (since 6.2) 353^^^^^^^^^^^^^^^^^^^^^^^^^^^ 354 355The ``sga`` device loads an option ROM for x86 targets which enables 356SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 357contains native support for this feature and thus use of the option 358ROM approach is obsolete. The native SeaBIOS support can be activated 359by using ``-machine graphics=off``. 360 361 362Block device options 363'''''''''''''''''''' 364 365``"backing": ""`` (since 2.12) 366^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 367 368In order to prevent QEMU from automatically opening an image's backing 369chain, use ``"backing": null`` instead. 370 371``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 372^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 373 374Options for ``rbd`` should be specified according to its runtime options, 375like other block drivers. Legacy parsing of keyvalue pair encoded 376filenames is useful to open images with the old format for backing files; 377These image files should be updated to use the current format. 378 379Example of legacy encoding:: 380 381 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 382 383The above, converted to the current supported format:: 384 385 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 386 387linux-user mode CPUs 388-------------------- 389 390``ppc64abi32`` CPUs (since 5.2) 391''''''''''''''''''''''''''''''' 392 393The ``ppc64abi32`` architecture has a number of issues which regularly 394trip up our CI testing and is suspected to be quite broken. For that 395reason the maintainers strongly suspect no one actually uses it. 396 397MIPS ``I7200`` CPU (since 5.2) 398'''''''''''''''''''''''''''''' 399 400The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 401(the ISA has never been upstreamed to a compiler toolchain). Therefore 402this CPU is also deprecated. 403 404Backwards compatibility 405----------------------- 406 407Runnability guarantee of CPU models (since 4.1) 408''''''''''''''''''''''''''''''''''''''''''''''' 409 410Previous versions of QEMU never changed existing CPU models in 411ways that introduced additional host software or hardware 412requirements to the VM. This allowed management software to 413safely change the machine type of an existing VM without 414introducing new requirements ("runnability guarantee"). This 415prevented CPU models from being updated to include CPU 416vulnerability mitigations, leaving guests vulnerable in the 417default configuration. 418 419The CPU model runnability guarantee won't apply anymore to 420existing CPU models. Management software that needs runnability 421guarantees must resolve the CPU model aliases using the 422``alias-of`` field returned by the ``query-cpu-definitions`` QMP 423command. 424 425While those guarantees are kept, the return value of 426``query-cpu-definitions`` will have existing CPU model aliases 427point to a version that doesn't break runnability guarantees 428(specifically, version 1 of those CPU models). In future QEMU 429versions, aliases will point to newer CPU model versions 430depending on the machine type, so management software must 431resolve CPU model aliases before starting a virtual machine. 432 433Guest Emulator ISAs 434------------------- 435 436nanoMIPS ISA 437'''''''''''' 438 439The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 440As it is hard to generate binaries for it, declare it deprecated. 441