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 42``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 43'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 44 45``tty`` and ``parport`` are aliases that will be removed. Instead, the 46actual backend names ``serial`` and ``parallel`` should be used. 47 48Short-form boolean options (since 6.0) 49'''''''''''''''''''''''''''''''''''''' 50 51Boolean options such as ``share=on``/``share=off`` could be written 52in short form as ``share`` and ``noshare``. This is now deprecated 53and will cause a warning. 54 55``delay`` option for socket character devices (since 6.0) 56''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 57 58The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 59rather than ``delay=off``. 60 61Userspace local APIC with KVM (x86, since 6.0) 62'''''''''''''''''''''''''''''''''''''''''''''' 63 64Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 65APIC is deprecated. The ``split`` setting is supported, as is using 66``-M kernel-irqchip=off`` with the ISA PC machine type. 67 68hexadecimal sizes with scaling multipliers (since 6.0) 69'''''''''''''''''''''''''''''''''''''''''''''''''''''' 70 71Input parameters that take a size value should only use a size suffix 72(such as 'k' or 'M') when the base is written in decimal, and not when 73the value is hexadecimal. That is, '0x20M' is deprecated, and should 74be written either as '32M' or as '0x2000000'. 75 76``-spice password=string`` (since 6.0) 77'''''''''''''''''''''''''''''''''''''' 78 79This option is insecure because the SPICE password remains visible in 80the process listing. This is replaced by the new ``password-secret`` 81option which lets the password be securely provided on the command 82line using a ``secret`` object instance. 83 84``-watchdog`` (since 6.2) 85''''''''''''''''''''''''' 86 87Use ``-device`` instead. 88 89``-smp`` ("parameter=0" SMP configurations) (since 6.2) 90''''''''''''''''''''''''''''''''''''''''''''''''''''''' 91 92Specified CPU topology parameters must be greater than zero. 93 94In the SMP configuration, users should either provide a CPU topology 95parameter with a reasonable value (greater than zero) or just omit it 96and QEMU will compute the missing value. 97 98However, historically it was implicitly allowed for users to provide 99a parameter with zero value, which is meaningless and could also possibly 100cause unexpected results in the -smp parsing. So support for this kind of 101configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 102be removed in the near future, users have to ensure that all the topology 103members described with -smp are greater than zero. 104 105Plugin argument passing through ``arg=<string>`` (since 6.1) 106'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 107 108Passing TCG plugins arguments through ``arg=`` is redundant is makes the 109command-line less readable, especially when the argument itself consist of a 110name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 111Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 112as short-form boolean values, and passed to plugins as ``arg_name=on``. 113However, short-form booleans are deprecated and full explicit ``arg_name=on`` 114form is preferred. 115 116``-drive if=none`` for the sifive_u OTP device (since 6.2) 117'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 118 119Using ``-drive if=none`` to configure the OTP device of the sifive_u 120RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 121 122 123QEMU Machine Protocol (QMP) commands 124------------------------------------ 125 126``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 127''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 128 129Use argument ``id`` instead. 130 131``eject`` argument ``device`` (since 2.8) 132''''''''''''''''''''''''''''''''''''''''' 133 134Use argument ``id`` instead. 135 136``blockdev-change-medium`` argument ``device`` (since 2.8) 137'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 138 139Use argument ``id`` instead. 140 141``block_set_io_throttle`` argument ``device`` (since 2.8) 142''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 143 144Use argument ``id`` instead. 145 146``blockdev-add`` empty string argument ``backing`` (since 2.10) 147''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 148 149Use argument value ``null`` instead. 150 151``block-commit`` arguments ``base`` and ``top`` (since 3.1) 152''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 153 154Use arguments ``base-node`` and ``top-node`` instead. 155 156``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 157'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 158 159Use the more generic commands ``block-export-add`` and ``block-export-del`` 160instead. As part of this deprecation, where ``nbd-server-add`` used a 161single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 162 163``query-qmp-schema`` return value member ``values`` (since 6.2) 164''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 165 166Member ``values`` in return value elements with meta-type ``enum`` is 167deprecated. Use ``members`` instead. 168 169``drive-backup`` (since 6.2) 170'''''''''''''''''''''''''''' 171 172Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 173This change primarily separates the creation/opening process of the backup 174target with explicit, separate steps. ``blockdev-backup`` uses mostly the 175same arguments as ``drive-backup``, except the ``format`` and ``mode`` 176options are removed in favor of using explicit ``blockdev-create`` and 177``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 178details. 179 180Incorrectly typed ``device_add`` arguments (since 6.2) 181'''''''''''''''''''''''''''''''''''''''''''''''''''''' 182 183Due to shortcomings in the internal implementation of ``device_add``, QEMU 184incorrectly accepts certain invalid arguments: Any object or list arguments are 185silently ignored. Other argument types are not checked, but an implicit 186conversion happens, so that e.g. string values can be assigned to integer 187device properties or vice versa. 188 189This is a bug in QEMU that will be fixed in the future so that previously 190accepted incorrect commands will return an error. Users should make sure that 191all arguments passed to ``device_add`` are consistent with the documented 192property types. 193 194``query-sgx`` return value member ``section-size`` (since 7.0) 195'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 196 197Member ``section-size`` in return value elements with meta-type ``uint64`` is 198deprecated. Use ``sections`` instead. 199 200 201``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 202''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 203 204Member ``section-size`` in return value elements with meta-type ``uint64`` is 205deprecated. Use ``sections`` instead. 206 207System accelerators 208------------------- 209 210MIPS ``Trap-and-Emul`` KVM support (since 6.0) 211'''''''''''''''''''''''''''''''''''''''''''''' 212 213The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 214from Linux upstream kernel, declare it deprecated. 215 216System emulator CPUS 217-------------------- 218 219MIPS ``I7200`` CPU Model (since 5.2) 220'''''''''''''''''''''''''''''''''''' 221 222The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 223(the ISA has never been upstreamed to a compiler toolchain). Therefore 224this CPU is also deprecated. 225 226 227QEMU API (QAPI) events 228---------------------- 229 230``MEM_UNPLUG_ERROR`` (since 6.2) 231'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 232 233Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 234 235 236System emulator machines 237------------------------ 238 239PPC 405 ``taihu`` machine (since 7.0) 240''''''''''''''''''''''''''''''''''''' 241 242The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar, 243except for some external periphery. However, the periphery of the ``taihu`` 244machine is hardly emulated at all (e.g. neither the LCD nor the USB part had 245been implemented), so there is not much value added by this board. Use the 246``ref405ep`` machine instead. 247 248``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) 249''''''''''''''''''''''''''''''''''''''''''''''''''''' 250 251These old machine types are quite neglected nowadays and thus might have 252various pitfalls with regards to live migration. Use a newer machine type 253instead. 254 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 sga`` (since 6.2) 291^^^^^^^^^^^^^^^^^^^^^^^^^^^ 292 293The ``sga`` device loads an option ROM for x86 targets which enables 294SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 295contains native support for this feature and thus use of the option 296ROM approach is obsolete. The native SeaBIOS support can be activated 297by using ``-machine graphics=off``. 298 299``-device nvme-ns,eui64-default=on|off`` (since 7.1) 300^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 301 302In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 303identifer that is not globally unique. If an EUI-64 identifer is required, the 304user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 305 306``-device nvme,use-intel-id=on|off`` (since 7.1) 307^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 308 309The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 310from Intel that was not properly allocated. Since version 5.2, the controller 311has used a properly allocated identifier. Deprecate the ``use-intel-id`` 312machine compatibility parameter. 313 314 315Block device options 316'''''''''''''''''''' 317 318``"backing": ""`` (since 2.12) 319^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 320 321In order to prevent QEMU from automatically opening an image's backing 322chain, use ``"backing": null`` instead. 323 324``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 325^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 326 327Options for ``rbd`` should be specified according to its runtime options, 328like other block drivers. Legacy parsing of keyvalue pair encoded 329filenames is useful to open images with the old format for backing files; 330These image files should be updated to use the current format. 331 332Example of legacy encoding:: 333 334 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 335 336The above, converted to the current supported format:: 337 338 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 339 340linux-user mode CPUs 341-------------------- 342 343MIPS ``I7200`` CPU (since 5.2) 344'''''''''''''''''''''''''''''' 345 346The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 347(the ISA has never been upstreamed to a compiler toolchain). Therefore 348this CPU is also deprecated. 349 350Backwards compatibility 351----------------------- 352 353Runnability guarantee of CPU models (since 4.1) 354''''''''''''''''''''''''''''''''''''''''''''''' 355 356Previous versions of QEMU never changed existing CPU models in 357ways that introduced additional host software or hardware 358requirements to the VM. This allowed management software to 359safely change the machine type of an existing VM without 360introducing new requirements ("runnability guarantee"). This 361prevented CPU models from being updated to include CPU 362vulnerability mitigations, leaving guests vulnerable in the 363default configuration. 364 365The CPU model runnability guarantee won't apply anymore to 366existing CPU models. Management software that needs runnability 367guarantees must resolve the CPU model aliases using the 368``alias-of`` field returned by the ``query-cpu-definitions`` QMP 369command. 370 371While those guarantees are kept, the return value of 372``query-cpu-definitions`` will have existing CPU model aliases 373point to a version that doesn't break runnability guarantees 374(specifically, version 1 of those CPU models). In future QEMU 375versions, aliases will point to newer CPU model versions 376depending on the machine type, so management software must 377resolve CPU model aliases before starting a virtual machine. 378 379Guest Emulator ISAs 380------------------- 381 382nanoMIPS ISA 383'''''''''''' 384 385The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 386As it is hard to generate binaries for it, declare it deprecated. 387 388Tools 389----- 390 391virtiofsd 392''''''''' 393 394There is a new Rust implementation of ``virtiofsd`` at 395``https://gitlab.com/virtio-fs/virtiofsd``; 396since this is now marked stable, new development should be done on that 397rather than the existing C version in the QEMU tree. 398The C version will still accept fixes and patches that 399are already in development for the moment, but will eventually 400be deleted from this tree. 401New deployments should use the Rust version, and existing systems 402should consider moving to it. The command line and feature set 403is very close and moving should be simple. 404