1Deprecated features 2=================== 3 4In general features are intended to be supported indefinitely once 5introduced into QEMU. In the event that a feature needs to be removed, 6it will be listed in this section. The feature will remain functional for the 7release in which it was deprecated and one further release. After these two 8releases, the feature is liable to be removed. Deprecated features may also 9generate warnings on the console when QEMU starts up, or if activated via a 10monitor command, however, this is not a mandatory requirement. 11 12Prior to the 2.10.0 release there was no official policy on how 13long features would be deprecated prior to their removal, nor 14any documented list of which features were deprecated. Thus 15any features deprecated prior to 2.10.0 will be treated as if 16they were first deprecated in the 2.10.0 release. 17 18What follows is a list of all features currently marked as 19deprecated. 20 21System emulator command line arguments 22-------------------------------------- 23 24``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) 25''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 26 27The ``-audiodev`` argument is now the preferred way to specify audio 28backend settings instead of environment variables. To ease migration to 29the new format, the ``-audiodev-help`` option can be used to convert 30the current values of the environment variables to ``-audiodev`` options. 31 32Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) 33'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 34 35When not using the deprecated legacy audio config, each sound card 36should specify an ``audiodev=`` property. Additionally, when using 37vnc, you should specify an ``audiodev=`` property if you plan to 38transmit audio through the VNC protocol. 39 40Creating sound card devices using ``-soundhw`` (since 5.1) 41'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 42 43Sound card devices should be created using ``-device`` instead. The 44names are the same for most devices. The exceptions are ``hda`` which 45needs two devices (``-device intel-hda -device hda-duplex``) and 46``pcspk`` which can be activated using ``-machine 47pcspk-audiodev=<name>``. 48 49``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 50'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 51 52``tty`` and ``parport`` are aliases that will be removed. Instead, the 53actual backend names ``serial`` and ``parallel`` should be used. 54 55Short-form boolean options (since 6.0) 56'''''''''''''''''''''''''''''''''''''' 57 58Boolean options such as ``share=on``/``share=off`` could be written 59in short form as ``share`` and ``noshare``. This is now deprecated 60and will cause a warning. 61 62``delay`` option for socket character devices (since 6.0) 63''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 64 65The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 66rather than ``delay=off``. 67 68``--enable-fips`` (since 6.0) 69''''''''''''''''''''''''''''' 70 71This option restricts usage of certain cryptographic algorithms when 72the host is operating in FIPS mode. 73 74If FIPS compliance is required, QEMU should be built with the ``libgcrypt`` 75library enabled as a cryptography provider. 76 77Neither the ``nettle`` library, or the built-in cryptography provider are 78supported on FIPS enabled hosts. 79 80``-writeconfig`` (since 6.0) 81''''''''''''''''''''''''''''' 82 83The ``-writeconfig`` option is not able to serialize the entire contents 84of the QEMU command line. It is thus considered a failed experiment 85and deprecated, with no current replacement. 86 87Userspace local APIC with KVM (x86, since 6.0) 88'''''''''''''''''''''''''''''''''''''''''''''' 89 90Using ``-M kernel-irqchip=off`` with x86 machine types that include a local 91APIC is deprecated. The ``split`` setting is supported, as is using 92``-M kernel-irqchip=off`` with the ISA PC machine type. 93 94hexadecimal sizes with scaling multipliers (since 6.0) 95'''''''''''''''''''''''''''''''''''''''''''''''''''''' 96 97Input parameters that take a size value should only use a size suffix 98(such as 'k' or 'M') when the base is written in decimal, and not when 99the value is hexadecimal. That is, '0x20M' is deprecated, and should 100be written either as '32M' or as '0x2000000'. 101 102``-spice password=string`` (since 6.0) 103'''''''''''''''''''''''''''''''''''''' 104 105This option is insecure because the SPICE password remains visible in 106the process listing. This is replaced by the new ``password-secret`` 107option which lets the password be securely provided on the command 108line using a ``secret`` object instance. 109 110``opened`` property of ``rng-*`` objects (since 6.0) 111'''''''''''''''''''''''''''''''''''''''''''''''''''' 112 113The only effect of specifying ``opened=on`` in the command line or QMP 114``object-add`` is that the device is opened immediately, possibly before all 115other options have been processed. This will either have no effect (if 116``opened`` was the last option) or cause errors. The property is therefore 117useless and should not be specified. 118 119``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0) 120'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 121 122The only effect of specifying ``loaded=on`` in the command line or QMP 123``object-add`` is that the secret is loaded immediately, possibly before all 124other options have been processed. This will either have no effect (if 125``loaded`` was the last option) or cause options to be effectively ignored as 126if they were not given. The property is therefore useless and should not be 127specified. 128 129``-display sdl,window_close=...`` (since 6.1) 130''''''''''''''''''''''''''''''''''''''''''''' 131 132Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of 133an underscore between "window" and "close"). 134 135``-no-quit`` (since 6.1) 136'''''''''''''''''''''''' 137 138The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which 139should be used instead. 140 141``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2) 142'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 143 144Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. 145 146``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2) 147'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 148 149Use ``-display sdl,grab-mod=rctrl`` instead. 150 151``-sdl`` (since 6.2) 152'''''''''''''''''''' 153 154Use ``-display sdl`` instead. 155 156``-curses`` (since 6.2) 157''''''''''''''''''''''' 158 159Use ``-display curses`` instead. 160 161 162Plugin argument passing through ``arg=<string>`` (since 6.1) 163'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 164 165Passing TCG plugins arguments through ``arg=`` is redundant is makes the 166command-line less readable, especially when the argument itself consist of a 167name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 168Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 169as short-form boolean values, and passed to plugins as ``arg_name=on``. 170However, short-form booleans are deprecated and full explicit ``arg_name=on`` 171form is preferred. 172 173 174QEMU Machine Protocol (QMP) commands 175------------------------------------ 176 177``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 178''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 179 180Use argument ``id`` instead. 181 182``eject`` argument ``device`` (since 2.8) 183''''''''''''''''''''''''''''''''''''''''' 184 185Use argument ``id`` instead. 186 187``blockdev-change-medium`` argument ``device`` (since 2.8) 188'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 189 190Use argument ``id`` instead. 191 192``block_set_io_throttle`` argument ``device`` (since 2.8) 193''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 194 195Use argument ``id`` instead. 196 197``blockdev-add`` empty string argument ``backing`` (since 2.10) 198''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 199 200Use argument value ``null`` instead. 201 202``block-commit`` arguments ``base`` and ``top`` (since 3.1) 203''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 204 205Use arguments ``base-node`` and ``top-node`` instead. 206 207``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 208'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 209 210Use the more generic commands ``block-export-add`` and ``block-export-del`` 211instead. As part of this deprecation, where ``nbd-server-add`` used a 212single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 213 214System accelerators 215------------------- 216 217MIPS ``Trap-and-Emul`` KVM support (since 6.0) 218'''''''''''''''''''''''''''''''''''''''''''''' 219 220The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 221from Linux upstream kernel, declare it deprecated. 222 223System emulator CPUS 224-------------------- 225 226``Icelake-Client`` CPU Model (since 5.2) 227'''''''''''''''''''''''''''''''''''''''' 228 229``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 230Models instead. 231 232MIPS ``I7200`` CPU Model (since 5.2) 233'''''''''''''''''''''''''''''''''''' 234 235The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 236(the ISA has never been upstreamed to a compiler toolchain). Therefore 237this CPU is also deprecated. 238 239System emulator machines 240------------------------ 241 242Aspeed ``swift-bmc`` machine (since 6.1) 243'''''''''''''''''''''''''''''''''''''''' 244 245This machine is deprecated because we have enough AST2500 based OpenPOWER 246machines. It can be easily replaced by the ``witherspoon-bmc`` or the 247``romulus-bmc`` machines. 248 249Backend options 250--------------- 251 252Using non-persistent backing file with pmem=on (since 6.1) 253'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 254 255This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 256device. However enabling ``memory-backend-file.pmem`` option, when backing file 257is (a) not DAX capable or (b) not on a filesystem that support direct mapping 258of persistent memory, is not safe and may lead to data loss or corruption in case 259of host crash. 260Options are: 261 262 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 263 (without persistence guaranties) with backing file on non DAX storage 264 - move backing file to NVDIMM storage and keep ``pmem=on`` 265 (to have NVDIMM with persistence guaranties). 266 267Device options 268-------------- 269 270Emulated device options 271''''''''''''''''''''''' 272 273``-device virtio-blk,scsi=on|off`` (since 5.0) 274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 275 276The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 277and later do not support it because the virtio-scsi device was introduced for 278full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 279 280Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 281alias. 282 283Block device options 284'''''''''''''''''''' 285 286``"backing": ""`` (since 2.12) 287^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 288 289In order to prevent QEMU from automatically opening an image's backing 290chain, use ``"backing": null`` instead. 291 292``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 293^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 294 295Options for ``rbd`` should be specified according to its runtime options, 296like other block drivers. Legacy parsing of keyvalue pair encoded 297filenames is useful to open images with the old format for backing files; 298These image files should be updated to use the current format. 299 300Example of legacy encoding:: 301 302 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 303 304The above, converted to the current supported format:: 305 306 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 307 308linux-user mode CPUs 309-------------------- 310 311``ppc64abi32`` CPUs (since 5.2) 312''''''''''''''''''''''''''''''' 313 314The ``ppc64abi32`` architecture has a number of issues which regularly 315trip up our CI testing and is suspected to be quite broken. For that 316reason the maintainers strongly suspect no one actually uses it. 317 318MIPS ``I7200`` CPU (since 5.2) 319'''''''''''''''''''''''''''''' 320 321The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 322(the ISA has never been upstreamed to a compiler toolchain). Therefore 323this CPU is also deprecated. 324 325Related binaries 326---------------- 327 328Backwards compatibility 329----------------------- 330 331Runnability guarantee of CPU models (since 4.1) 332''''''''''''''''''''''''''''''''''''''''''''''' 333 334Previous versions of QEMU never changed existing CPU models in 335ways that introduced additional host software or hardware 336requirements to the VM. This allowed management software to 337safely change the machine type of an existing VM without 338introducing new requirements ("runnability guarantee"). This 339prevented CPU models from being updated to include CPU 340vulnerability mitigations, leaving guests vulnerable in the 341default configuration. 342 343The CPU model runnability guarantee won't apply anymore to 344existing CPU models. Management software that needs runnability 345guarantees must resolve the CPU model aliases using the 346``alias-of`` field returned by the ``query-cpu-definitions`` QMP 347command. 348 349While those guarantees are kept, the return value of 350``query-cpu-definitions`` will have existing CPU model aliases 351point to a version that doesn't break runnability guarantees 352(specifically, version 1 of those CPU models). In future QEMU 353versions, aliases will point to newer CPU model versions 354depending on the machine type, so management software must 355resolve CPU model aliases before starting a virtual machine. 356 357Guest Emulator ISAs 358------------------- 359 360nanoMIPS ISA 361'''''''''''' 362 363The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 364As it is hard to generate binaries for it, declare it deprecated. 365