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