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``-sdl`` (since 6.2) 85'''''''''''''''''''' 86 87Use ``-display sdl`` instead. 88 89``-curses`` (since 6.2) 90''''''''''''''''''''''' 91 92Use ``-display curses`` instead. 93 94``-watchdog`` (since 6.2) 95''''''''''''''''''''''''' 96 97Use ``-device`` instead. 98 99``-smp`` ("parameter=0" SMP configurations) (since 6.2) 100''''''''''''''''''''''''''''''''''''''''''''''''''''''' 101 102Specified CPU topology parameters must be greater than zero. 103 104In the SMP configuration, users should either provide a CPU topology 105parameter with a reasonable value (greater than zero) or just omit it 106and QEMU will compute the missing value. 107 108However, historically it was implicitly allowed for users to provide 109a parameter with zero value, which is meaningless and could also possibly 110cause unexpected results in the -smp parsing. So support for this kind of 111configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 112be removed in the near future, users have to ensure that all the topology 113members described with -smp are greater than zero. 114 115Plugin argument passing through ``arg=<string>`` (since 6.1) 116'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 117 118Passing TCG plugins arguments through ``arg=`` is redundant is makes the 119command-line less readable, especially when the argument itself consist of a 120name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 121Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 122as short-form boolean values, and passed to plugins as ``arg_name=on``. 123However, short-form booleans are deprecated and full explicit ``arg_name=on`` 124form is preferred. 125 126``-drive if=none`` for the sifive_u OTP device (since 6.2) 127'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 128 129Using ``-drive if=none`` to configure the OTP device of the sifive_u 130RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. 131 132 133QEMU Machine Protocol (QMP) commands 134------------------------------------ 135 136``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 137''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 138 139Use argument ``id`` instead. 140 141``eject`` argument ``device`` (since 2.8) 142''''''''''''''''''''''''''''''''''''''''' 143 144Use argument ``id`` instead. 145 146``blockdev-change-medium`` argument ``device`` (since 2.8) 147'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 148 149Use argument ``id`` instead. 150 151``block_set_io_throttle`` argument ``device`` (since 2.8) 152''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 153 154Use argument ``id`` instead. 155 156``blockdev-add`` empty string argument ``backing`` (since 2.10) 157''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 158 159Use argument value ``null`` instead. 160 161``block-commit`` arguments ``base`` and ``top`` (since 3.1) 162''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 163 164Use arguments ``base-node`` and ``top-node`` instead. 165 166``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 167'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 168 169Use the more generic commands ``block-export-add`` and ``block-export-del`` 170instead. As part of this deprecation, where ``nbd-server-add`` used a 171single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 172 173``query-qmp-schema`` return value member ``values`` (since 6.2) 174''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 175 176Member ``values`` in return value elements with meta-type ``enum`` is 177deprecated. Use ``members`` instead. 178 179``drive-backup`` (since 6.2) 180'''''''''''''''''''''''''''' 181 182Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 183This change primarily separates the creation/opening process of the backup 184target with explicit, separate steps. ``blockdev-backup`` uses mostly the 185same arguments as ``drive-backup``, except the ``format`` and ``mode`` 186options are removed in favor of using explicit ``blockdev-create`` and 187``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 188details. 189 190Incorrectly typed ``device_add`` arguments (since 6.2) 191'''''''''''''''''''''''''''''''''''''''''''''''''''''' 192 193Due to shortcomings in the internal implementation of ``device_add``, QEMU 194incorrectly accepts certain invalid arguments: Any object or list arguments are 195silently ignored. Other argument types are not checked, but an implicit 196conversion happens, so that e.g. string values can be assigned to integer 197device properties or vice versa. 198 199This is a bug in QEMU that will be fixed in the future so that previously 200accepted incorrect commands will return an error. Users should make sure that 201all arguments passed to ``device_add`` are consistent with the documented 202property types. 203 204``query-sgx`` return value member ``section-size`` (since 7.0) 205'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 206 207Member ``section-size`` in return value elements with meta-type ``uint64`` is 208deprecated. Use ``sections`` instead. 209 210 211``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) 212''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 213 214Member ``section-size`` in return value elements with meta-type ``uint64`` is 215deprecated. Use ``sections`` instead. 216 217System accelerators 218------------------- 219 220MIPS ``Trap-and-Emul`` KVM support (since 6.0) 221'''''''''''''''''''''''''''''''''''''''''''''' 222 223The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 224from Linux upstream kernel, declare it deprecated. 225 226System emulator CPUS 227-------------------- 228 229MIPS ``I7200`` CPU Model (since 5.2) 230'''''''''''''''''''''''''''''''''''' 231 232The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 233(the ISA has never been upstreamed to a compiler toolchain). Therefore 234this CPU is also deprecated. 235 236 237QEMU API (QAPI) events 238---------------------- 239 240``MEM_UNPLUG_ERROR`` (since 6.2) 241'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 242 243Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 244 245 246System emulator machines 247------------------------ 248 249PPC 405 ``taihu`` machine (since 7.0) 250''''''''''''''''''''''''''''''''''''' 251 252The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar, 253except for some external periphery. However, the periphery of the ``taihu`` 254machine is hardly emulated at all (e.g. neither the LCD nor the USB part had 255been implemented), so there is not much value added by this board. Use the 256``ref405ep`` machine instead. 257 258``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) 259''''''''''''''''''''''''''''''''''''''''''''''''''''' 260 261These old machine types are quite neglected nowadays and thus might have 262various pitfalls with regards to live migration. Use a newer machine type 263instead. 264 265 266Backend options 267--------------- 268 269Using non-persistent backing file with pmem=on (since 6.1) 270'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 271 272This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 273device. However enabling ``memory-backend-file.pmem`` option, when backing file 274is (a) not DAX capable or (b) not on a filesystem that support direct mapping 275of persistent memory, is not safe and may lead to data loss or corruption in case 276of host crash. 277Options are: 278 279 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 280 (without persistence guaranties) with backing file on non DAX storage 281 - move backing file to NVDIMM storage and keep ``pmem=on`` 282 (to have NVDIMM with persistence guaranties). 283 284Device options 285-------------- 286 287Emulated device options 288''''''''''''''''''''''' 289 290``-device virtio-blk,scsi=on|off`` (since 5.0) 291^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 292 293The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 294and later do not support it because the virtio-scsi device was introduced for 295full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 296 297Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 298alias. 299 300``-device sga`` (since 6.2) 301^^^^^^^^^^^^^^^^^^^^^^^^^^^ 302 303The ``sga`` device loads an option ROM for x86 targets which enables 304SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards 305contains native support for this feature and thus use of the option 306ROM approach is obsolete. The native SeaBIOS support can be activated 307by using ``-machine graphics=off``. 308 309 310Block device options 311'''''''''''''''''''' 312 313``"backing": ""`` (since 2.12) 314^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 315 316In order to prevent QEMU from automatically opening an image's backing 317chain, use ``"backing": null`` instead. 318 319``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 320^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 321 322Options for ``rbd`` should be specified according to its runtime options, 323like other block drivers. Legacy parsing of keyvalue pair encoded 324filenames is useful to open images with the old format for backing files; 325These image files should be updated to use the current format. 326 327Example of legacy encoding:: 328 329 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 330 331The above, converted to the current supported format:: 332 333 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 334 335linux-user mode CPUs 336-------------------- 337 338MIPS ``I7200`` CPU (since 5.2) 339'''''''''''''''''''''''''''''' 340 341The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 342(the ISA has never been upstreamed to a compiler toolchain). Therefore 343this CPU is also deprecated. 344 345Backwards compatibility 346----------------------- 347 348Runnability guarantee of CPU models (since 4.1) 349''''''''''''''''''''''''''''''''''''''''''''''' 350 351Previous versions of QEMU never changed existing CPU models in 352ways that introduced additional host software or hardware 353requirements to the VM. This allowed management software to 354safely change the machine type of an existing VM without 355introducing new requirements ("runnability guarantee"). This 356prevented CPU models from being updated to include CPU 357vulnerability mitigations, leaving guests vulnerable in the 358default configuration. 359 360The CPU model runnability guarantee won't apply anymore to 361existing CPU models. Management software that needs runnability 362guarantees must resolve the CPU model aliases using the 363``alias-of`` field returned by the ``query-cpu-definitions`` QMP 364command. 365 366While those guarantees are kept, the return value of 367``query-cpu-definitions`` will have existing CPU model aliases 368point to a version that doesn't break runnability guarantees 369(specifically, version 1 of those CPU models). In future QEMU 370versions, aliases will point to newer CPU model versions 371depending on the machine type, so management software must 372resolve CPU model aliases before starting a virtual machine. 373 374Guest Emulator ISAs 375------------------- 376 377nanoMIPS ISA 378'''''''''''' 379 380The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 381As it is hard to generate binaries for it, declare it deprecated. 382 383Tools 384----- 385 386virtiofsd 387''''''''' 388 389There is a new Rust implementation of ``virtiofsd`` at 390``https://gitlab.com/virtio-fs/virtiofsd``; 391since this is now marked stable, new development should be done on that 392rather than the existing C version in the QEMU tree. 393The C version will still accept fixes and patches that 394are already in development for the moment, but will eventually 395be deleted from this tree. 396New deployments should use the Rust version, and existing systems 397should consider moving to it. The command line and feature set 398is very close and moving should be simple. 399