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.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.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 142QEMU Machine Protocol (QMP) commands 143------------------------------------ 144 145``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0) 146''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 147 148Use argument ``id`` instead. 149 150``eject`` argument ``device`` (since 2.8.0) 151''''''''''''''''''''''''''''''''''''''''''' 152 153Use argument ``id`` instead. 154 155``blockdev-change-medium`` argument ``device`` (since 2.8.0) 156'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 157 158Use argument ``id`` instead. 159 160``block_set_io_throttle`` argument ``device`` (since 2.8.0) 161''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 162 163Use argument ``id`` instead. 164 165``blockdev-add`` empty string argument ``backing`` (since 2.10.0) 166''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 167 168Use argument value ``null`` instead. 169 170``block-commit`` arguments ``base`` and ``top`` (since 3.1.0) 171''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 172 173Use arguments ``base-node`` and ``top-node`` instead. 174 175``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 176'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 177 178Use the more generic commands ``block-export-add`` and ``block-export-del`` 179instead. As part of this deprecation, where ``nbd-server-add`` used a 180single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 181 182System accelerators 183------------------- 184 185MIPS ``Trap-and-Emul`` KVM support (since 6.0) 186'''''''''''''''''''''''''''''''''''''''''''''' 187 188The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 189from Linux upstream kernel, declare it deprecated. 190 191System emulator CPUS 192-------------------- 193 194``Icelake-Client`` CPU Model (since 5.2.0) 195'''''''''''''''''''''''''''''''''''''''''' 196 197``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 198Models instead. 199 200MIPS ``I7200`` CPU Model (since 5.2) 201'''''''''''''''''''''''''''''''''''' 202 203The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 204(the ISA has never been upstreamed to a compiler toolchain). Therefore 205this CPU is also deprecated. 206 207System emulator machines 208------------------------ 209 210Raspberry Pi ``raspi2`` and ``raspi3`` machines (since 5.2) 211''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 212 213The Raspberry Pi machines come in various models (A, A+, B, B+). To be able 214to distinguish which model QEMU is implementing, the ``raspi2`` and ``raspi3`` 215machines have been renamed ``raspi2b`` and ``raspi3b``. 216 217Aspeed ``swift-bmc`` machine (since 6.1) 218'''''''''''''''''''''''''''''''''''''''' 219 220This machine is deprecated because we have enough AST2500 based OpenPOWER 221machines. It can be easily replaced by the ``witherspoon-bmc`` or the 222``romulus-bmc`` machines. 223 224Backend options 225--------------- 226 227Using non-persistent backing file with pmem=on (since 6.1) 228'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 229 230This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 231device. However enabling ``memory-backend-file.pmem`` option, when backing file 232is (a) not DAX capable or (b) not on a filesystem that support direct mapping 233of persistent memory, is not safe and may lead to data loss or corruption in case 234of host crash. 235Options are: 236 237 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 238 (without persistence guaranties) with backing file on non DAX storage 239 - move backing file to NVDIMM storage and keep ``pmem=on`` 240 (to have NVDIMM with persistence guaranties). 241 242Device options 243-------------- 244 245Emulated device options 246''''''''''''''''''''''' 247 248``-device virtio-blk,scsi=on|off`` (since 5.0.0) 249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 250 251The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 252and later do not support it because the virtio-scsi device was introduced for 253full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 254 255Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 256alias. 257 258Block device options 259'''''''''''''''''''' 260 261``"backing": ""`` (since 2.12.0) 262^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 263 264In order to prevent QEMU from automatically opening an image's backing 265chain, use ``"backing": null`` instead. 266 267``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0) 268^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269 270Options for ``rbd`` should be specified according to its runtime options, 271like other block drivers. Legacy parsing of keyvalue pair encoded 272filenames is useful to open images with the old format for backing files; 273These image files should be updated to use the current format. 274 275Example of legacy encoding:: 276 277 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 278 279The above, converted to the current supported format:: 280 281 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 282 283linux-user mode CPUs 284-------------------- 285 286``ppc64abi32`` CPUs (since 5.2.0) 287''''''''''''''''''''''''''''''''' 288 289The ``ppc64abi32`` architecture has a number of issues which regularly 290trip up our CI testing and is suspected to be quite broken. For that 291reason the maintainers strongly suspect no one actually uses it. 292 293MIPS ``I7200`` CPU (since 5.2) 294'''''''''''''''''''''''''''''' 295 296The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 297(the ISA has never been upstreamed to a compiler toolchain). Therefore 298this CPU is also deprecated. 299 300Related binaries 301---------------- 302 303Backwards compatibility 304----------------------- 305 306Runnability guarantee of CPU models (since 4.1.0) 307''''''''''''''''''''''''''''''''''''''''''''''''' 308 309Previous versions of QEMU never changed existing CPU models in 310ways that introduced additional host software or hardware 311requirements to the VM. This allowed management software to 312safely change the machine type of an existing VM without 313introducing new requirements ("runnability guarantee"). This 314prevented CPU models from being updated to include CPU 315vulnerability mitigations, leaving guests vulnerable in the 316default configuration. 317 318The CPU model runnability guarantee won't apply anymore to 319existing CPU models. Management software that needs runnability 320guarantees must resolve the CPU model aliases using the 321``alias-of`` field returned by the ``query-cpu-definitions`` QMP 322command. 323 324While those guarantees are kept, the return value of 325``query-cpu-definitions`` will have existing CPU model aliases 326point to a version that doesn't break runnability guarantees 327(specifically, version 1 of those CPU models). In future QEMU 328versions, aliases will point to newer CPU model versions 329depending on the machine type, so management software must 330resolve CPU model aliases before starting a virtual machine. 331 332Guest Emulator ISAs 333------------------- 334 335nanoMIPS ISA 336'''''''''''' 337 338The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 339As it is hard to generate binaries for it, declare it deprecated. 340