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``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2) 138'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 139 140Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. 141 142``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2) 143'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 144 145Use ``-display sdl,grab-mod=rctrl`` instead. 146 147``-sdl`` (since 6.2) 148'''''''''''''''''''' 149 150Use ``-display sdl`` instead. 151 152``-curses`` (since 6.2) 153''''''''''''''''''''''' 154 155Use ``-display curses`` instead. 156 157``-watchdog`` (since 6.2) 158''''''''''''''''''''''''' 159 160Use ``-device`` instead. 161 162``-smp`` ("parameter=0" SMP configurations) (since 6.2) 163''''''''''''''''''''''''''''''''''''''''''''''''''''''' 164 165Specified CPU topology parameters must be greater than zero. 166 167In the SMP configuration, users should either provide a CPU topology 168parameter with a reasonable value (greater than zero) or just omit it 169and QEMU will compute the missing value. 170 171However, historically it was implicitly allowed for users to provide 172a parameter with zero value, which is meaningless and could also possibly 173cause unexpected results in the -smp parsing. So support for this kind of 174configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 175be removed in the near future, users have to ensure that all the topology 176members described with -smp are greater than zero. 177 178Plugin argument passing through ``arg=<string>`` (since 6.1) 179'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 180 181Passing TCG plugins arguments through ``arg=`` is redundant is makes the 182command-line less readable, especially when the argument itself consist of a 183name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 184Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 185as short-form boolean values, and passed to plugins as ``arg_name=on``. 186However, short-form booleans are deprecated and full explicit ``arg_name=on`` 187form is preferred. 188 189``-drive if=none`` for the sifive_u OTP device (since 6.2) 190'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 191 192Using ``-drive if=none`` to configure the OTP device of the sifive_u 193RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 194 195 196QEMU Machine Protocol (QMP) commands 197------------------------------------ 198 199``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 200''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 201 202Use argument ``id`` instead. 203 204``eject`` argument ``device`` (since 2.8) 205''''''''''''''''''''''''''''''''''''''''' 206 207Use argument ``id`` instead. 208 209``blockdev-change-medium`` argument ``device`` (since 2.8) 210'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 211 212Use argument ``id`` instead. 213 214``block_set_io_throttle`` argument ``device`` (since 2.8) 215''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 216 217Use argument ``id`` instead. 218 219``blockdev-add`` empty string argument ``backing`` (since 2.10) 220''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 221 222Use argument value ``null`` instead. 223 224``block-commit`` arguments ``base`` and ``top`` (since 3.1) 225''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 226 227Use arguments ``base-node`` and ``top-node`` instead. 228 229``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 230'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 231 232Use the more generic commands ``block-export-add`` and ``block-export-del`` 233instead. As part of this deprecation, where ``nbd-server-add`` used a 234single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 235 236``query-qmp-schema`` return value member ``values`` (since 6.2) 237''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 238 239Member ``values`` in return value elements with meta-type ``enum`` is 240deprecated. Use ``members`` instead. 241 242``drive-backup`` (since 6.2) 243'''''''''''''''''''''''''''' 244 245Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 246This change primarily separates the creation/opening process of the backup 247target with explicit, separate steps. ``blockdev-backup`` uses mostly the 248same arguments as ``drive-backup``, except the ``format`` and ``mode`` 249options are removed in favor of using explicit ``blockdev-create`` and 250``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 251details. 252 253Incorrectly typed ``device_add`` arguments (since 6.2) 254'''''''''''''''''''''''''''''''''''''''''''''''''''''' 255 256Due to shortcomings in the internal implementation of ``device_add``, QEMU 257incorrectly accepts certain invalid arguments: Any object or list arguments are 258silently ignored. Other argument types are not checked, but an implicit 259conversion happens, so that e.g. string values can be assigned to integer 260device properties or vice versa. 261 262This is a bug in QEMU that will be fixed in the future so that previously 263accepted incorrect commands will return an error. Users should make sure that 264all arguments passed to ``device_add`` are consistent with the documented 265property types. 266 267``query-sgx`` return value member ``section-size`` (since 7.0) 268'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 269 270Member ``section-size`` in return value elements with meta-type ``uint64`` is 271deprecated. Use ``sections`` instead. 272 273 274``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 275''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 276 277Member ``section-size`` in return value elements with meta-type ``uint64`` is 278deprecated. Use ``sections`` instead. 279 280System accelerators 281------------------- 282 283MIPS ``Trap-and-Emul`` KVM support (since 6.0) 284'''''''''''''''''''''''''''''''''''''''''''''' 285 286The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 287from Linux upstream kernel, declare it deprecated. 288 289System emulator CPUS 290-------------------- 291 292``Icelake-Client`` CPU Model (since 5.2) 293'''''''''''''''''''''''''''''''''''''''' 294 295``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 296Models instead. 297 298MIPS ``I7200`` CPU Model (since 5.2) 299'''''''''''''''''''''''''''''''''''' 300 301The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 302(the ISA has never been upstreamed to a compiler toolchain). Therefore 303this CPU is also deprecated. 304 305 306QEMU API (QAPI) events 307---------------------- 308 309``MEM_UNPLUG_ERROR`` (since 6.2) 310'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 311 312Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 313 314 315System emulator machines 316------------------------ 317 318PPC 405 ``taihu`` machine (since 7.0) 319''''''''''''''''''''''''''''''''''''' 320 321The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar, 322except for some external periphery. However, the periphery of the ``taihu`` 323machine is hardly emulated at all (e.g. neither the LCD nor the USB part had 324been implemented), so there is not much value added by this board. Use the 325``ref405ep`` machine instead. 326 327Backend options 328--------------- 329 330Using non-persistent backing file with pmem=on (since 6.1) 331'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 332 333This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 334device. However enabling ``memory-backend-file.pmem`` option, when backing file 335is (a) not DAX capable or (b) not on a filesystem that support direct mapping 336of persistent memory, is not safe and may lead to data loss or corruption in case 337of host crash. 338Options are: 339 340 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 341 (without persistence guaranties) with backing file on non DAX storage 342 - move backing file to NVDIMM storage and keep ``pmem=on`` 343 (to have NVDIMM with persistence guaranties). 344 345Device options 346-------------- 347 348Emulated device options 349''''''''''''''''''''''' 350 351``-device virtio-blk,scsi=on|off`` (since 5.0) 352^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 353 354The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 355and later do not support it because the virtio-scsi device was introduced for 356full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 357 358Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 359alias. 360 361``-device sga`` (since 6.2) 362^^^^^^^^^^^^^^^^^^^^^^^^^^^ 363 364The ``sga`` device loads an option ROM for x86 targets which enables 365SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 366contains native support for this feature and thus use of the option 367ROM approach is obsolete. The native SeaBIOS support can be activated 368by using ``-machine graphics=off``. 369 370 371Block device options 372'''''''''''''''''''' 373 374``"backing": ""`` (since 2.12) 375^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 376 377In order to prevent QEMU from automatically opening an image's backing 378chain, use ``"backing": null`` instead. 379 380``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 382 383Options for ``rbd`` should be specified according to its runtime options, 384like other block drivers. Legacy parsing of keyvalue pair encoded 385filenames is useful to open images with the old format for backing files; 386These image files should be updated to use the current format. 387 388Example of legacy encoding:: 389 390 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 391 392The above, converted to the current supported format:: 393 394 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 395 396linux-user mode CPUs 397-------------------- 398 399MIPS ``I7200`` CPU (since 5.2) 400'''''''''''''''''''''''''''''' 401 402The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 403(the ISA has never been upstreamed to a compiler toolchain). Therefore 404this CPU is also deprecated. 405 406Backwards compatibility 407----------------------- 408 409Runnability guarantee of CPU models (since 4.1) 410''''''''''''''''''''''''''''''''''''''''''''''' 411 412Previous versions of QEMU never changed existing CPU models in 413ways that introduced additional host software or hardware 414requirements to the VM. This allowed management software to 415safely change the machine type of an existing VM without 416introducing new requirements ("runnability guarantee"). This 417prevented CPU models from being updated to include CPU 418vulnerability mitigations, leaving guests vulnerable in the 419default configuration. 420 421The CPU model runnability guarantee won't apply anymore to 422existing CPU models. Management software that needs runnability 423guarantees must resolve the CPU model aliases using the 424``alias-of`` field returned by the ``query-cpu-definitions`` QMP 425command. 426 427While those guarantees are kept, the return value of 428``query-cpu-definitions`` will have existing CPU model aliases 429point to a version that doesn't break runnability guarantees 430(specifically, version 1 of those CPU models). In future QEMU 431versions, aliases will point to newer CPU model versions 432depending on the machine type, so management software must 433resolve CPU model aliases before starting a virtual machine. 434 435Guest Emulator ISAs 436------------------- 437 438nanoMIPS ISA 439'''''''''''' 440 441The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 442As it is hard to generate binaries for it, declare it deprecated. 443 444Tools 445----- 446 447virtiofsd 448''''''''' 449 450There is a new Rust implementation of ``virtiofsd`` at 451``https://gitlab.com/virtio-fs/virtiofsd``; 452since this is now marked stable, new development should be done on that 453rather than the existing C version in the QEMU tree. 454The C version will still accept fixes and patches that 455are already in development for the moment, but will eventually 456be deleted from this tree. 457New deployments should use the Rust version, and existing systems 458should consider moving to it. The command line and feature set 459is very close and moving should be simple. 460