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