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