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