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 42``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 43'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 44 45``tty`` and ``parport`` are aliases that will be removed. Instead, the 46actual backend names ``serial`` and ``parallel`` should be used. 47 48Short-form boolean options (since 6.0) 49'''''''''''''''''''''''''''''''''''''' 50 51Boolean options such as ``share=on``/``share=off`` could be written 52in short form as ``share`` and ``noshare``. This is now deprecated 53and will cause a warning. 54 55``delay`` option for socket character devices (since 6.0) 56''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 57 58The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 59rather than ``delay=off``. 60 61Userspace local APIC with KVM (x86, since 6.0) 62'''''''''''''''''''''''''''''''''''''''''''''' 63 64Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 65APIC is deprecated. The ``split`` setting is supported, as is using 66``-M kernel-irqchip=off`` with the ISA PC machine type. 67 68hexadecimal sizes with scaling multipliers (since 6.0) 69'''''''''''''''''''''''''''''''''''''''''''''''''''''' 70 71Input parameters that take a size value should only use a size suffix 72(such as 'k' or 'M') when the base is written in decimal, and not when 73the value is hexadecimal. That is, '0x20M' is deprecated, and should 74be written either as '32M' or as '0x2000000'. 75 76``-spice password=string`` (since 6.0) 77'''''''''''''''''''''''''''''''''''''' 78 79This option is insecure because the SPICE password remains visible in 80the process listing. This is replaced by the new ``password-secret`` 81option which lets the password be securely provided on the command 82line using a ``secret`` object instance. 83 84``-smp`` ("parameter=0" SMP configurations) (since 6.2) 85''''''''''''''''''''''''''''''''''''''''''''''''''''''' 86 87Specified CPU topology parameters must be greater than zero. 88 89In the SMP configuration, users should either provide a CPU topology 90parameter with a reasonable value (greater than zero) or just omit it 91and QEMU will compute the missing value. 92 93However, historically it was implicitly allowed for users to provide 94a parameter with zero value, which is meaningless and could also possibly 95cause unexpected results in the -smp parsing. So support for this kind of 96configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 97be removed in the near future, users have to ensure that all the topology 98members described with -smp are greater than zero. 99 100Plugin argument passing through ``arg=<string>`` (since 6.1) 101'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 102 103Passing TCG plugins arguments through ``arg=`` is redundant is makes the 104command-line less readable, especially when the argument itself consist of a 105name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 106Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 107as short-form boolean values, and passed to plugins as ``arg_name=on``. 108However, short-form booleans are deprecated and full explicit ``arg_name=on`` 109form is preferred. 110 111``-drive if=none`` for the sifive_u OTP device (since 6.2) 112'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 113 114Using ``-drive if=none`` to configure the OTP device of the sifive_u 115RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 116 117``-no-hpet`` (since 8.0) 118'''''''''''''''''''''''' 119 120The HPET setting has been turned into a machine property. 121Use ``-machine hpet=off`` instead. 122 123 124QEMU Machine Protocol (QMP) commands 125------------------------------------ 126 127``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 128''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 129 130Use argument ``id`` instead. 131 132``eject`` argument ``device`` (since 2.8) 133''''''''''''''''''''''''''''''''''''''''' 134 135Use argument ``id`` instead. 136 137``blockdev-change-medium`` argument ``device`` (since 2.8) 138'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 139 140Use argument ``id`` instead. 141 142``block_set_io_throttle`` argument ``device`` (since 2.8) 143''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 144 145Use argument ``id`` instead. 146 147``blockdev-add`` empty string argument ``backing`` (since 2.10) 148''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 149 150Use argument value ``null`` instead. 151 152``block-commit`` arguments ``base`` and ``top`` (since 3.1) 153''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 154 155Use arguments ``base-node`` and ``top-node`` instead. 156 157``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 158'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 159 160Use the more generic commands ``block-export-add`` and ``block-export-del`` 161instead. As part of this deprecation, where ``nbd-server-add`` used a 162single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 163 164``query-qmp-schema`` return value member ``values`` (since 6.2) 165''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 166 167Member ``values`` in return value elements with meta-type ``enum`` is 168deprecated. Use ``members`` instead. 169 170``drive-backup`` (since 6.2) 171'''''''''''''''''''''''''''' 172 173Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 174This change primarily separates the creation/opening process of the backup 175target with explicit, separate steps. ``blockdev-backup`` uses mostly the 176same arguments as ``drive-backup``, except the ``format`` and ``mode`` 177options are removed in favor of using explicit ``blockdev-create`` and 178``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 179details. 180 181Incorrectly typed ``device_add`` arguments (since 6.2) 182'''''''''''''''''''''''''''''''''''''''''''''''''''''' 183 184Due to shortcomings in the internal implementation of ``device_add``, QEMU 185incorrectly accepts certain invalid arguments: Any object or list arguments are 186silently ignored. Other argument types are not checked, but an implicit 187conversion happens, so that e.g. string values can be assigned to integer 188device properties or vice versa. 189 190This is a bug in QEMU that will be fixed in the future so that previously 191accepted incorrect commands will return an error. Users should make sure that 192all arguments passed to ``device_add`` are consistent with the documented 193property types. 194 195``query-sgx`` return value member ``section-size`` (since 7.0) 196'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 197 198Member ``section-size`` in return value elements with meta-type ``uint64`` is 199deprecated. Use ``sections`` instead. 200 201 202``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 203''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 204 205Member ``section-size`` in return value elements with meta-type ``uint64`` is 206deprecated. Use ``sections`` instead. 207 208System accelerators 209------------------- 210 211MIPS ``Trap-and-Emul`` KVM support (since 6.0) 212'''''''''''''''''''''''''''''''''''''''''''''' 213 214The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 215from Linux upstream kernel, declare it deprecated. 216 217Host Architectures 218------------------ 219 220BE MIPS (since 7.2) 221''''''''''''''''''' 222 223As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 224MIPS moved out of support making it hard to maintain our 225cross-compilation CI tests of the architecture. As we no longer have 226CI coverage support may bitrot away before the deprecation process 227completes. The little endian variants of MIPS (both 32 and 64 bit) are 228still a supported host architecture. 229 230QEMU API (QAPI) events 231---------------------- 232 233``MEM_UNPLUG_ERROR`` (since 6.2) 234'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 235 236Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 237 238 239System emulator machines 240------------------------ 241 242Arm ``virt`` machine ``dtb-kaslr-seed`` property 243'''''''''''''''''''''''''''''''''''''''''''''''' 244 245The ``dtb-kaslr-seed`` property on the ``virt`` board has been 246deprecated; use the new name ``dtb-randomness`` instead. The new name 247better reflects the way this property affects all random data within 248the device tree blob, not just the ``kaslr-seed`` node. 249 250``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) 251''''''''''''''''''''''''''''''''''''''''''''''''''''' 252 253These old machine types are quite neglected nowadays and thus might have 254various pitfalls with regards to live migration. Use a newer machine type 255instead. 256 257 258Backend options 259--------------- 260 261Using non-persistent backing file with pmem=on (since 6.1) 262'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 263 264This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 265device. However enabling ``memory-backend-file.pmem`` option, when backing file 266is (a) not DAX capable or (b) not on a filesystem that support direct mapping 267of persistent memory, is not safe and may lead to data loss or corruption in case 268of host crash. 269Options are: 270 271 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 272 (without persistence guaranties) with backing file on non DAX storage 273 - move backing file to NVDIMM storage and keep ``pmem=on`` 274 (to have NVDIMM with persistence guaranties). 275 276Device options 277-------------- 278 279Emulated device options 280''''''''''''''''''''''' 281 282``-device virtio-blk,scsi=on|off`` (since 5.0) 283^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 284 285The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 286and later do not support it because the virtio-scsi device was introduced for 287full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 288 289Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 290alias. 291 292``-device sga`` (since 6.2) 293^^^^^^^^^^^^^^^^^^^^^^^^^^^ 294 295The ``sga`` device loads an option ROM for x86 targets which enables 296SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 297contains native support for this feature and thus use of the option 298ROM approach is obsolete. The native SeaBIOS support can be activated 299by using ``-machine graphics=off``. 300 301``-device nvme-ns,eui64-default=on|off`` (since 7.1) 302^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 303 304In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 305identifier that is not globally unique. If an EUI-64 identifier is required, the 306user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 307 308``-device nvme,use-intel-id=on|off`` (since 7.1) 309^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 310 311The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 312from Intel that was not properly allocated. Since version 5.2, the controller 313has used a properly allocated identifier. Deprecate the ``use-intel-id`` 314machine compatibility parameter. 315 316 317Block device options 318'''''''''''''''''''' 319 320``"backing": ""`` (since 2.12) 321^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 322 323In order to prevent QEMU from automatically opening an image's backing 324chain, use ``"backing": null`` instead. 325 326``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 327^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 328 329Options for ``rbd`` should be specified according to its runtime options, 330like other block drivers. Legacy parsing of keyvalue pair encoded 331filenames is useful to open images with the old format for backing files; 332These image files should be updated to use the current format. 333 334Example of legacy encoding:: 335 336 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 337 338The above, converted to the current supported format:: 339 340 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 341 342Backwards compatibility 343----------------------- 344 345Runnability guarantee of CPU models (since 4.1) 346''''''''''''''''''''''''''''''''''''''''''''''' 347 348Previous versions of QEMU never changed existing CPU models in 349ways that introduced additional host software or hardware 350requirements to the VM. This allowed management software to 351safely change the machine type of an existing VM without 352introducing new requirements ("runnability guarantee"). This 353prevented CPU models from being updated to include CPU 354vulnerability mitigations, leaving guests vulnerable in the 355default configuration. 356 357The CPU model runnability guarantee won't apply anymore to 358existing CPU models. Management software that needs runnability 359guarantees must resolve the CPU model aliases using the 360``alias-of`` field returned by the ``query-cpu-definitions`` QMP 361command. 362 363While those guarantees are kept, the return value of 364``query-cpu-definitions`` will have existing CPU model aliases 365point to a version that doesn't break runnability guarantees 366(specifically, version 1 of those CPU models). In future QEMU 367versions, aliases will point to newer CPU model versions 368depending on the machine type, so management software must 369resolve CPU model aliases before starting a virtual machine. 370 371Tools 372----- 373 374virtiofsd 375''''''''' 376 377There is a new Rust implementation of ``virtiofsd`` at 378``https://gitlab.com/virtio-fs/virtiofsd``; 379since this is now marked stable, new development should be done on that 380rather than the existing C version in the QEMU tree. 381The C version will still accept fixes and patches that 382are already in development for the moment, but will eventually 383be deleted from this tree. 384New deployments should use the Rust version, and existing systems 385should consider moving to it. The command line and feature set 386is very close and moving should be simple. 387 388 389QEMU guest agent 390---------------- 391 392``--blacklist`` command line option (since 7.2) 393''''''''''''''''''''''''''''''''''''''''''''''' 394 395``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better 396wording for what this option does). The short form ``-b`` still stays 397the same and thus is the preferred way for scripts that should run with 398both, older and future versions of QEMU. 399 400``blacklist`` config file option (since 7.2) 401'''''''''''''''''''''''''''''''''''''''''''' 402 403The ``blacklist`` config file option has been renamed to ``block-rpcs`` 404(to be in sync with the renaming of the corresponding command line 405option). 406