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 23Build options 24------------- 25 26``gprof`` builds (since 8.0) 27'''''''''''''''''''''''''''' 28 29The ``--enable-gprof`` configure setting relies on compiler 30instrumentation to gather its data which can distort the generated 31profile. As other non-instrumenting tools are available that give a 32more holistic view of the system with non-instrumented binaries we are 33deprecating the build option and no longer defend it in CI. The 34``--enable-gcov`` build option remains for analysis test case 35coverage. 36 37System emulator command line arguments 38-------------------------------------- 39 40Creating sound card devices without ``audiodev=`` property (since 4.2) 41'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 42 43When not using the deprecated legacy audio config, each sound card 44should specify an ``audiodev=`` property. 45 46Short-form boolean options (since 6.0) 47'''''''''''''''''''''''''''''''''''''' 48 49Boolean options such as ``share=on``/``share=off`` could be written 50in short form as ``share`` and ``noshare``. This is now deprecated 51and will cause a warning. 52 53``delay`` option for socket character devices (since 6.0) 54''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 55 56The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 57rather than ``delay=off``. 58 59``-smp`` ("parameter=0" SMP configurations) (since 6.2) 60''''''''''''''''''''''''''''''''''''''''''''''''''''''' 61 62Specified CPU topology parameters must be greater than zero. 63 64In the SMP configuration, users should either provide a CPU topology 65parameter with a reasonable value (greater than zero) or just omit it 66and QEMU will compute the missing value. 67 68However, historically it was implicitly allowed for users to provide 69a parameter with zero value, which is meaningless and could also possibly 70cause unexpected results in the -smp parsing. So support for this kind of 71configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 72be removed in the near future, users have to ensure that all the topology 73members described with -smp are greater than zero. 74 75Plugin argument passing through ``arg=<string>`` (since 6.1) 76'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 77 78Passing TCG plugins arguments through ``arg=`` is redundant is makes the 79command-line less readable, especially when the argument itself consist of a 80name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 81Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 82as short-form boolean values, and passed to plugins as ``arg_name=on``. 83However, short-form booleans are deprecated and full explicit ``arg_name=on`` 84form is preferred. 85 86``-no-hpet`` (since 8.0) 87'''''''''''''''''''''''' 88 89The HPET setting has been turned into a machine property. 90Use ``-machine hpet=off`` instead. 91 92``-no-acpi`` (since 8.0) 93'''''''''''''''''''''''' 94 95The ``-no-acpi`` setting has been turned into a machine property. 96Use ``-machine acpi=off`` instead. 97 98``-async-teardown`` (since 8.1) 99''''''''''''''''''''''''''''''' 100 101Use ``-run-with async-teardown=on`` instead. 102 103``-chroot`` (since 8.1) 104''''''''''''''''''''''' 105 106Use ``-run-with chroot=dir`` instead. 107 108``-singlestep`` (since 8.1) 109''''''''''''''''''''''''''' 110 111The ``-singlestep`` option has been turned into an accelerator property, 112and given a name that better reflects what it actually does. 113Use ``-accel tcg,one-insn-per-tb=on`` instead. 114 115User-mode emulator command line arguments 116----------------------------------------- 117 118``-singlestep`` (since 8.1) 119''''''''''''''''''''''''''' 120 121The ``-singlestep`` option has been given a name that better reflects 122what it actually does. For both linux-user and bsd-user, use the 123new ``-one-insn-per-tb`` option instead. 124 125QEMU Machine Protocol (QMP) commands 126------------------------------------ 127 128``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 129''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 130 131Use argument ``id`` instead. 132 133``eject`` argument ``device`` (since 2.8) 134''''''''''''''''''''''''''''''''''''''''' 135 136Use argument ``id`` instead. 137 138``blockdev-change-medium`` argument ``device`` (since 2.8) 139'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 140 141Use argument ``id`` instead. 142 143``block_set_io_throttle`` argument ``device`` (since 2.8) 144''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 145 146Use argument ``id`` instead. 147 148``blockdev-add`` empty string argument ``backing`` (since 2.10) 149''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 150 151Use argument value ``null`` instead. 152 153``block-commit`` arguments ``base`` and ``top`` (since 3.1) 154''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 155 156Use arguments ``base-node`` and ``top-node`` instead. 157 158``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 159'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 160 161Use the more generic commands ``block-export-add`` and ``block-export-del`` 162instead. As part of this deprecation, where ``nbd-server-add`` used a 163single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 164 165``query-qmp-schema`` return value member ``values`` (since 6.2) 166''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 167 168Member ``values`` in return value elements with meta-type ``enum`` is 169deprecated. Use ``members`` instead. 170 171``drive-backup`` (since 6.2) 172'''''''''''''''''''''''''''' 173 174Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 175This change primarily separates the creation/opening process of the backup 176target with explicit, separate steps. ``blockdev-backup`` uses mostly the 177same arguments as ``drive-backup``, except the ``format`` and ``mode`` 178options are removed in favor of using explicit ``blockdev-create`` and 179``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 180details. 181 182Incorrectly typed ``device_add`` arguments (since 6.2) 183'''''''''''''''''''''''''''''''''''''''''''''''''''''' 184 185Due to shortcomings in the internal implementation of ``device_add``, QEMU 186incorrectly accepts certain invalid arguments: Any object or list arguments are 187silently ignored. Other argument types are not checked, but an implicit 188conversion happens, so that e.g. string values can be assigned to integer 189device properties or vice versa. 190 191This is a bug in QEMU that will be fixed in the future so that previously 192accepted incorrect commands will return an error. Users should make sure that 193all arguments passed to ``device_add`` are consistent with the documented 194property types. 195 196``StatusInfo`` member ``singlestep`` (since 8.1) 197'''''''''''''''''''''''''''''''''''''''''''''''' 198 199The ``singlestep`` member of the ``StatusInfo`` returned from the 200``query-status`` command is deprecated. This member has a confusing 201name and it never did what the documentation claimed or what its name 202suggests. We do not believe that anybody is actually using the 203information provided in this member. 204 205The information it reports is whether the TCG JIT is in "one 206instruction per translated block" mode (which can be set on the 207command line or via the HMP, but not via QMP). The information remains 208available via the HMP 'info jit' command. 209 210QEMU Machine Protocol (QMP) events 211---------------------------------- 212 213``MEM_UNPLUG_ERROR`` (since 6.2) 214'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 215 216Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 217 218``vcpu`` trace events (since 8.1) 219''''''''''''''''''''''''''''''''' 220 221The ability to instrument QEMU helper functions with vCPU-aware trace 222points was removed in 7.0. However QMP still exposed the vcpu 223parameter. This argument has now been deprecated and the remaining 224remaining trace points that used it are selected just by name. 225 226Human Monitor Protocol (HMP) commands 227------------------------------------- 228 229``singlestep`` (since 8.1) 230'''''''''''''''''''''''''' 231 232The ``singlestep`` command has been replaced by the ``one-insn-per-tb`` 233command, which has the same behaviour but a less misleading name. 234 235Host Architectures 236------------------ 237 238BE MIPS (since 7.2) 239''''''''''''''''''' 240 241As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 242MIPS moved out of support making it hard to maintain our 243cross-compilation CI tests of the architecture. As we no longer have 244CI coverage support may bitrot away before the deprecation process 245completes. The little endian variants of MIPS (both 32 and 64 bit) are 246still a supported host architecture. 247 248System emulation on 32-bit x86 hosts (since 8.0) 249'''''''''''''''''''''''''''''''''''''''''''''''' 250 251Support for 32-bit x86 host deployments is increasingly uncommon in mainstream 252OS distributions given the widespread availability of 64-bit x86 hardware. 253The QEMU project no longer considers 32-bit x86 support for system emulation to 254be an effective use of its limited resources, and thus intends to discontinue 255it. Since all recent x86 hardware from the past >10 years is capable of the 25664-bit x86 extensions, a corresponding 64-bit OS should be used instead. 257 258 259System emulator machines 260------------------------ 261 262Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 263'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 264 265The ``dtb-kaslr-seed`` property on the ``virt`` board has been 266deprecated; use the new name ``dtb-randomness`` instead. The new name 267better reflects the way this property affects all random data within 268the device tree blob, not just the ``kaslr-seed`` node. 269 270Backend options 271--------------- 272 273Using non-persistent backing file with pmem=on (since 6.1) 274'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 275 276This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 277device. However enabling ``memory-backend-file.pmem`` option, when backing file 278is (a) not DAX capable or (b) not on a filesystem that support direct mapping 279of persistent memory, is not safe and may lead to data loss or corruption in case 280of host crash. 281Options are: 282 283 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 284 (without persistence guaranties) with backing file on non DAX storage 285 - move backing file to NVDIMM storage and keep ``pmem=on`` 286 (to have NVDIMM with persistence guaranties). 287 288Device options 289-------------- 290 291Emulated device options 292''''''''''''''''''''''' 293 294``-device virtio-blk,scsi=on|off`` (since 5.0) 295^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 296 297The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 298and later do not support it because the virtio-scsi device was introduced for 299full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 300 301Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 302alias. 303 304``-device nvme-ns,eui64-default=on|off`` (since 7.1) 305^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 306 307In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 308identifier that is not globally unique. If an EUI-64 identifier is required, the 309user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 310 311``-device nvme,use-intel-id=on|off`` (since 7.1) 312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 313 314The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 315from Intel that was not properly allocated. Since version 5.2, the controller 316has used a properly allocated identifier. Deprecate the ``use-intel-id`` 317machine compatibility parameter. 318 319``-device cxl-type3,memdev=xxxx`` (since 8.0) 320^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 321 322The ``cxl-type3`` device initially only used a single memory backend. With 323the addition of volatile memory support, it is now necessary to distinguish 324between persistent and volatile memory backends. As such, memdev is deprecated 325in favor of persistent-memdev. 326 327``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 328^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 329 330The 9p ``proxy`` filesystem backend driver has been deprecated and will be 331removed (along with its proxy helper daemon) in a future version of QEMU. Please 332use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 333backend, or alternatively consider deploying virtiofsd instead. 334 335The 9p ``proxy`` backend was originally developed as an alternative to the 9p 336``local`` backend. The idea was to enhance security by dispatching actual low 337level filesystem operations from 9p server (QEMU process) over to a separate 338process (the virtfs-proxy-helper binary). However this alternative never gained 339momentum. The proxy backend is much slower than the local backend, hasn't seen 340any development in years, and showed to be less secure, especially due to the 341fact that its helper daemon must be run as root, whereas with the local backend 342QEMU is typically run as unprivileged user and allows to tighten behaviour by 343mapping permissions et al by using its 'mapped' security model option. 344 345Nowadays it would make sense to reimplement the ``proxy`` backend by using 346QEMU's ``vhost`` feature, which would eliminate the high latency costs under 347which the 9p ``proxy`` backend currently suffers. However as of to date nobody 348has indicated plans for such kind of reimplementation unfortunately. 349 350 351Block device options 352'''''''''''''''''''' 353 354``"backing": ""`` (since 2.12) 355^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 356 357In order to prevent QEMU from automatically opening an image's backing 358chain, use ``"backing": null`` instead. 359 360``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 361^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 362 363Options for ``rbd`` should be specified according to its runtime options, 364like other block drivers. Legacy parsing of keyvalue pair encoded 365filenames is useful to open images with the old format for backing files; 366These image files should be updated to use the current format. 367 368Example of legacy encoding:: 369 370 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 371 372The above, converted to the current supported format:: 373 374 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 375 376``iscsi,password=xxx`` (since 8.0) 377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 378 379Specifying the iSCSI password in plain text on the command line using the 380``password`` option is insecure. The ``password-secret`` option should be 381used instead, to refer to a ``--object secret...`` instance that provides 382a password via a file, or encrypted. 383 384Backwards compatibility 385----------------------- 386 387Runnability guarantee of CPU models (since 4.1) 388''''''''''''''''''''''''''''''''''''''''''''''' 389 390Previous versions of QEMU never changed existing CPU models in 391ways that introduced additional host software or hardware 392requirements to the VM. This allowed management software to 393safely change the machine type of an existing VM without 394introducing new requirements ("runnability guarantee"). This 395prevented CPU models from being updated to include CPU 396vulnerability mitigations, leaving guests vulnerable in the 397default configuration. 398 399The CPU model runnability guarantee won't apply anymore to 400existing CPU models. Management software that needs runnability 401guarantees must resolve the CPU model aliases using the 402``alias-of`` field returned by the ``query-cpu-definitions`` QMP 403command. 404 405While those guarantees are kept, the return value of 406``query-cpu-definitions`` will have existing CPU model aliases 407point to a version that doesn't break runnability guarantees 408(specifically, version 1 of those CPU models). In future QEMU 409versions, aliases will point to newer CPU model versions 410depending on the machine type, so management software must 411resolve CPU model aliases before starting a virtual machine. 412 413QEMU guest agent 414---------------- 415 416``--blacklist`` command line option (since 7.2) 417''''''''''''''''''''''''''''''''''''''''''''''' 418 419``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better 420wording for what this option does). The short form ``-b`` still stays 421the same and thus is the preferred way for scripts that should run with 422both, older and future versions of QEMU. 423 424``blacklist`` config file option (since 7.2) 425'''''''''''''''''''''''''''''''''''''''''''' 426 427The ``blacklist`` config file option has been renamed to ``block-rpcs`` 428(to be in sync with the renaming of the corresponding command line 429option). 430 431Migration 432--------- 433 434``skipped`` MigrationStats field (since 8.1) 435'''''''''''''''''''''''''''''''''''''''''''' 436 437``skipped`` field in Migration stats has been deprecated. It hasn't 438been used for more than 10 years. 439 440