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