1*f3478392SPeter MaydellDeprecated features 2*f3478392SPeter Maydell=================== 3*f3478392SPeter Maydell 4*f3478392SPeter MaydellIn general features are intended to be supported indefinitely once 5*f3478392SPeter Maydellintroduced into QEMU. In the event that a feature needs to be removed, 6*f3478392SPeter Maydellit will be listed in this section. The feature will remain functional for the 7*f3478392SPeter Maydellrelease in which it was deprecated and one further release. After these two 8*f3478392SPeter Maydellreleases, the feature is liable to be removed. Deprecated features may also 9*f3478392SPeter Maydellgenerate warnings on the console when QEMU starts up, or if activated via a 10*f3478392SPeter Maydellmonitor command, however, this is not a mandatory requirement. 11*f3478392SPeter Maydell 12*f3478392SPeter MaydellPrior to the 2.10.0 release there was no official policy on how 13*f3478392SPeter Maydelllong features would be deprecated prior to their removal, nor 14*f3478392SPeter Maydellany documented list of which features were deprecated. Thus 15*f3478392SPeter Maydellany features deprecated prior to 2.10.0 will be treated as if 16*f3478392SPeter Maydellthey were first deprecated in the 2.10.0 release. 17*f3478392SPeter Maydell 18*f3478392SPeter MaydellWhat follows is a list of all features currently marked as 19*f3478392SPeter Maydelldeprecated. 20*f3478392SPeter Maydell 21*f3478392SPeter MaydellSystem emulator command line arguments 22*f3478392SPeter Maydell-------------------------------------- 23*f3478392SPeter Maydell 24*f3478392SPeter Maydell``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) 25*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 26*f3478392SPeter Maydell 27*f3478392SPeter MaydellThe ``-audiodev`` argument is now the preferred way to specify audio 28*f3478392SPeter Maydellbackend settings instead of environment variables. To ease migration to 29*f3478392SPeter Maydellthe new format, the ``-audiodev-help`` option can be used to convert 30*f3478392SPeter Maydellthe current values of the environment variables to ``-audiodev`` options. 31*f3478392SPeter Maydell 32*f3478392SPeter MaydellCreating sound card devices and vnc without ``audiodev=`` property (since 4.2) 33*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 34*f3478392SPeter Maydell 35*f3478392SPeter MaydellWhen not using the deprecated legacy audio config, each sound card 36*f3478392SPeter Maydellshould specify an ``audiodev=`` property. Additionally, when using 37*f3478392SPeter Maydellvnc, you should specify an ``audiodev=`` property if you plan to 38*f3478392SPeter Maydelltransmit audio through the VNC protocol. 39*f3478392SPeter Maydell 40*f3478392SPeter MaydellCreating sound card devices using ``-soundhw`` (since 5.1) 41*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 42*f3478392SPeter Maydell 43*f3478392SPeter MaydellSound card devices should be created using ``-device`` instead. The 44*f3478392SPeter Maydellnames are the same for most devices. The exceptions are ``hda`` which 45*f3478392SPeter Maydellneeds two devices (``-device intel-hda -device hda-duplex``) and 46*f3478392SPeter Maydell``pcspk`` which can be activated using ``-machine 47*f3478392SPeter Maydellpcspk-audiodev=<name>``. 48*f3478392SPeter Maydell 49*f3478392SPeter Maydell``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) 50*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 51*f3478392SPeter Maydell 52*f3478392SPeter Maydell``tty`` and ``parport`` are aliases that will be removed. Instead, the 53*f3478392SPeter Maydellactual backend names ``serial`` and ``parallel`` should be used. 54*f3478392SPeter Maydell 55*f3478392SPeter MaydellShort-form boolean options (since 6.0) 56*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''' 57*f3478392SPeter Maydell 58*f3478392SPeter MaydellBoolean options such as ``share=on``/``share=off`` could be written 59*f3478392SPeter Maydellin short form as ``share`` and ``noshare``. This is now deprecated 60*f3478392SPeter Maydelland will cause a warning. 61*f3478392SPeter Maydell 62*f3478392SPeter Maydell``delay`` option for socket character devices (since 6.0) 63*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 64*f3478392SPeter Maydell 65*f3478392SPeter MaydellThe replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 66*f3478392SPeter Maydellrather than ``delay=off``. 67*f3478392SPeter Maydell 68*f3478392SPeter Maydell``--enable-fips`` (since 6.0) 69*f3478392SPeter Maydell''''''''''''''''''''''''''''' 70*f3478392SPeter Maydell 71*f3478392SPeter MaydellThis option restricts usage of certain cryptographic algorithms when 72*f3478392SPeter Maydellthe host is operating in FIPS mode. 73*f3478392SPeter Maydell 74*f3478392SPeter MaydellIf FIPS compliance is required, QEMU should be built with the ``libgcrypt`` 75*f3478392SPeter Maydelllibrary enabled as a cryptography provider. 76*f3478392SPeter Maydell 77*f3478392SPeter MaydellNeither the ``nettle`` library, or the built-in cryptography provider are 78*f3478392SPeter Maydellsupported on FIPS enabled hosts. 79*f3478392SPeter Maydell 80*f3478392SPeter Maydell``-writeconfig`` (since 6.0) 81*f3478392SPeter Maydell''''''''''''''''''''''''''''' 82*f3478392SPeter Maydell 83*f3478392SPeter MaydellThe ``-writeconfig`` option is not able to serialize the entire contents 84*f3478392SPeter Maydellof the QEMU command line. It is thus considered a failed experiment 85*f3478392SPeter Maydelland deprecated, with no current replacement. 86*f3478392SPeter Maydell 87*f3478392SPeter MaydellUserspace local APIC with KVM (x86, since 6.0) 88*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''' 89*f3478392SPeter Maydell 90*f3478392SPeter MaydellUsing ``-M kernel-irqchip=off`` with x86 machine types that include a local 91*f3478392SPeter MaydellAPIC is deprecated. The ``split`` setting is supported, as is using 92*f3478392SPeter Maydell``-M kernel-irqchip=off`` with the ISA PC machine type. 93*f3478392SPeter Maydell 94*f3478392SPeter Maydellhexadecimal sizes with scaling multipliers (since 6.0) 95*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''' 96*f3478392SPeter Maydell 97*f3478392SPeter MaydellInput parameters that take a size value should only use a size suffix 98*f3478392SPeter Maydell(such as 'k' or 'M') when the base is written in decimal, and not when 99*f3478392SPeter Maydellthe value is hexadecimal. That is, '0x20M' is deprecated, and should 100*f3478392SPeter Maydellbe written either as '32M' or as '0x2000000'. 101*f3478392SPeter Maydell 102*f3478392SPeter Maydell``-spice password=string`` (since 6.0) 103*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''' 104*f3478392SPeter Maydell 105*f3478392SPeter MaydellThis option is insecure because the SPICE password remains visible in 106*f3478392SPeter Maydellthe process listing. This is replaced by the new ``password-secret`` 107*f3478392SPeter Maydelloption which lets the password be securely provided on the command 108*f3478392SPeter Maydellline using a ``secret`` object instance. 109*f3478392SPeter Maydell 110*f3478392SPeter Maydell``opened`` property of ``rng-*`` objects (since 6.0.0) 111*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''' 112*f3478392SPeter Maydell 113*f3478392SPeter MaydellThe only effect of specifying ``opened=on`` in the command line or QMP 114*f3478392SPeter Maydell``object-add`` is that the device is opened immediately, possibly before all 115*f3478392SPeter Maydellother options have been processed. This will either have no effect (if 116*f3478392SPeter Maydell``opened`` was the last option) or cause errors. The property is therefore 117*f3478392SPeter Maydelluseless and should not be specified. 118*f3478392SPeter Maydell 119*f3478392SPeter Maydell``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0.0) 120*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 121*f3478392SPeter Maydell 122*f3478392SPeter MaydellThe only effect of specifying ``loaded=on`` in the command line or QMP 123*f3478392SPeter Maydell``object-add`` is that the secret is loaded immediately, possibly before all 124*f3478392SPeter Maydellother options have been processed. This will either have no effect (if 125*f3478392SPeter Maydell``loaded`` was the last option) or cause options to be effectively ignored as 126*f3478392SPeter Maydellif they were not given. The property is therefore useless and should not be 127*f3478392SPeter Maydellspecified. 128*f3478392SPeter Maydell 129*f3478392SPeter Maydell``-display sdl,window_close=...`` (since 6.1) 130*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''' 131*f3478392SPeter Maydell 132*f3478392SPeter MaydellUse ``-display sdl,window-close=...`` instead (i.e. with a minus instead of 133*f3478392SPeter Maydellan underscore between "window" and "close"). 134*f3478392SPeter Maydell 135*f3478392SPeter Maydell``-no-quit`` (since 6.1) 136*f3478392SPeter Maydell'''''''''''''''''''''''' 137*f3478392SPeter Maydell 138*f3478392SPeter MaydellThe ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which 139*f3478392SPeter Maydellshould be used instead. 140*f3478392SPeter Maydell 141*f3478392SPeter Maydell 142*f3478392SPeter MaydellQEMU Machine Protocol (QMP) commands 143*f3478392SPeter Maydell------------------------------------ 144*f3478392SPeter Maydell 145*f3478392SPeter Maydell``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0) 146*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 147*f3478392SPeter Maydell 148*f3478392SPeter MaydellUse argument ``id`` instead. 149*f3478392SPeter Maydell 150*f3478392SPeter Maydell``eject`` argument ``device`` (since 2.8.0) 151*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''' 152*f3478392SPeter Maydell 153*f3478392SPeter MaydellUse argument ``id`` instead. 154*f3478392SPeter Maydell 155*f3478392SPeter Maydell``blockdev-change-medium`` argument ``device`` (since 2.8.0) 156*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 157*f3478392SPeter Maydell 158*f3478392SPeter MaydellUse argument ``id`` instead. 159*f3478392SPeter Maydell 160*f3478392SPeter Maydell``block_set_io_throttle`` argument ``device`` (since 2.8.0) 161*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 162*f3478392SPeter Maydell 163*f3478392SPeter MaydellUse argument ``id`` instead. 164*f3478392SPeter Maydell 165*f3478392SPeter Maydell``blockdev-add`` empty string argument ``backing`` (since 2.10.0) 166*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 167*f3478392SPeter Maydell 168*f3478392SPeter MaydellUse argument value ``null`` instead. 169*f3478392SPeter Maydell 170*f3478392SPeter Maydell``block-commit`` arguments ``base`` and ``top`` (since 3.1.0) 171*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 172*f3478392SPeter Maydell 173*f3478392SPeter MaydellUse arguments ``base-node`` and ``top-node`` instead. 174*f3478392SPeter Maydell 175*f3478392SPeter Maydell``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 176*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 177*f3478392SPeter Maydell 178*f3478392SPeter MaydellUse the more generic commands ``block-export-add`` and ``block-export-del`` 179*f3478392SPeter Maydellinstead. As part of this deprecation, where ``nbd-server-add`` used a 180*f3478392SPeter Maydellsingle ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 181*f3478392SPeter Maydell 182*f3478392SPeter MaydellSystem accelerators 183*f3478392SPeter Maydell------------------- 184*f3478392SPeter Maydell 185*f3478392SPeter MaydellMIPS ``Trap-and-Emul`` KVM support (since 6.0) 186*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''' 187*f3478392SPeter Maydell 188*f3478392SPeter MaydellThe MIPS ``Trap-and-Emul`` KVM host and guest support has been removed 189*f3478392SPeter Maydellfrom Linux upstream kernel, declare it deprecated. 190*f3478392SPeter Maydell 191*f3478392SPeter MaydellSystem emulator CPUS 192*f3478392SPeter Maydell-------------------- 193*f3478392SPeter Maydell 194*f3478392SPeter Maydell``Icelake-Client`` CPU Model (since 5.2.0) 195*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''' 196*f3478392SPeter Maydell 197*f3478392SPeter Maydell``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU 198*f3478392SPeter MaydellModels instead. 199*f3478392SPeter Maydell 200*f3478392SPeter MaydellMIPS ``I7200`` CPU Model (since 5.2) 201*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''' 202*f3478392SPeter Maydell 203*f3478392SPeter MaydellThe ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 204*f3478392SPeter Maydell(the ISA has never been upstreamed to a compiler toolchain). Therefore 205*f3478392SPeter Maydellthis CPU is also deprecated. 206*f3478392SPeter Maydell 207*f3478392SPeter MaydellSystem emulator machines 208*f3478392SPeter Maydell------------------------ 209*f3478392SPeter Maydell 210*f3478392SPeter MaydellRaspberry Pi ``raspi2`` and ``raspi3`` machines (since 5.2) 211*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 212*f3478392SPeter Maydell 213*f3478392SPeter MaydellThe Raspberry Pi machines come in various models (A, A+, B, B+). To be able 214*f3478392SPeter Maydellto distinguish which model QEMU is implementing, the ``raspi2`` and ``raspi3`` 215*f3478392SPeter Maydellmachines have been renamed ``raspi2b`` and ``raspi3b``. 216*f3478392SPeter Maydell 217*f3478392SPeter MaydellAspeed ``swift-bmc`` machine (since 6.1) 218*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''' 219*f3478392SPeter Maydell 220*f3478392SPeter MaydellThis machine is deprecated because we have enough AST2500 based OpenPOWER 221*f3478392SPeter Maydellmachines. It can be easily replaced by the ``witherspoon-bmc`` or the 222*f3478392SPeter Maydell``romulus-bmc`` machines. 223*f3478392SPeter Maydell 224*f3478392SPeter MaydellBackend options 225*f3478392SPeter Maydell--------------- 226*f3478392SPeter Maydell 227*f3478392SPeter MaydellUsing non-persistent backing file with pmem=on (since 6.1) 228*f3478392SPeter Maydell'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 229*f3478392SPeter Maydell 230*f3478392SPeter MaydellThis option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 231*f3478392SPeter Maydelldevice. However enabling ``memory-backend-file.pmem`` option, when backing file 232*f3478392SPeter Maydellis (a) not DAX capable or (b) not on a filesystem that support direct mapping 233*f3478392SPeter Maydellof persistent memory, is not safe and may lead to data loss or corruption in case 234*f3478392SPeter Maydellof host crash. 235*f3478392SPeter MaydellOptions are: 236*f3478392SPeter Maydell 237*f3478392SPeter Maydell - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 238*f3478392SPeter Maydell (without persistence guaranties) with backing file on non DAX storage 239*f3478392SPeter Maydell - move backing file to NVDIMM storage and keep ``pmem=on`` 240*f3478392SPeter Maydell (to have NVDIMM with persistence guaranties). 241*f3478392SPeter Maydell 242*f3478392SPeter MaydellDevice options 243*f3478392SPeter Maydell-------------- 244*f3478392SPeter Maydell 245*f3478392SPeter MaydellEmulated device options 246*f3478392SPeter Maydell''''''''''''''''''''''' 247*f3478392SPeter Maydell 248*f3478392SPeter Maydell``-device virtio-blk,scsi=on|off`` (since 5.0.0) 249*f3478392SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 250*f3478392SPeter Maydell 251*f3478392SPeter MaydellThe virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 252*f3478392SPeter Maydelland later do not support it because the virtio-scsi device was introduced for 253*f3478392SPeter Maydellfull SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 254*f3478392SPeter Maydell 255*f3478392SPeter MaydellNote this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 256*f3478392SPeter Maydellalias. 257*f3478392SPeter Maydell 258*f3478392SPeter MaydellBlock device options 259*f3478392SPeter Maydell'''''''''''''''''''' 260*f3478392SPeter Maydell 261*f3478392SPeter Maydell``"backing": ""`` (since 2.12.0) 262*f3478392SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 263*f3478392SPeter Maydell 264*f3478392SPeter MaydellIn order to prevent QEMU from automatically opening an image's backing 265*f3478392SPeter Maydellchain, use ``"backing": null`` instead. 266*f3478392SPeter Maydell 267*f3478392SPeter Maydell``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0) 268*f3478392SPeter Maydell^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269*f3478392SPeter Maydell 270*f3478392SPeter MaydellOptions for ``rbd`` should be specified according to its runtime options, 271*f3478392SPeter Maydelllike other block drivers. Legacy parsing of keyvalue pair encoded 272*f3478392SPeter Maydellfilenames is useful to open images with the old format for backing files; 273*f3478392SPeter MaydellThese image files should be updated to use the current format. 274*f3478392SPeter Maydell 275*f3478392SPeter MaydellExample of legacy encoding:: 276*f3478392SPeter Maydell 277*f3478392SPeter Maydell json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 278*f3478392SPeter Maydell 279*f3478392SPeter MaydellThe above, converted to the current supported format:: 280*f3478392SPeter Maydell 281*f3478392SPeter Maydell json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 282*f3478392SPeter Maydell 283*f3478392SPeter Maydelllinux-user mode CPUs 284*f3478392SPeter Maydell-------------------- 285*f3478392SPeter Maydell 286*f3478392SPeter Maydell``ppc64abi32`` CPUs (since 5.2.0) 287*f3478392SPeter Maydell''''''''''''''''''''''''''''''''' 288*f3478392SPeter Maydell 289*f3478392SPeter MaydellThe ``ppc64abi32`` architecture has a number of issues which regularly 290*f3478392SPeter Maydelltrip up our CI testing and is suspected to be quite broken. For that 291*f3478392SPeter Maydellreason the maintainers strongly suspect no one actually uses it. 292*f3478392SPeter Maydell 293*f3478392SPeter MaydellMIPS ``I7200`` CPU (since 5.2) 294*f3478392SPeter Maydell'''''''''''''''''''''''''''''' 295*f3478392SPeter Maydell 296*f3478392SPeter MaydellThe ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated 297*f3478392SPeter Maydell(the ISA has never been upstreamed to a compiler toolchain). Therefore 298*f3478392SPeter Maydellthis CPU is also deprecated. 299*f3478392SPeter Maydell 300*f3478392SPeter MaydellRelated binaries 301*f3478392SPeter Maydell---------------- 302*f3478392SPeter Maydell 303*f3478392SPeter MaydellBackwards compatibility 304*f3478392SPeter Maydell----------------------- 305*f3478392SPeter Maydell 306*f3478392SPeter MaydellRunnability guarantee of CPU models (since 4.1.0) 307*f3478392SPeter Maydell''''''''''''''''''''''''''''''''''''''''''''''''' 308*f3478392SPeter Maydell 309*f3478392SPeter MaydellPrevious versions of QEMU never changed existing CPU models in 310*f3478392SPeter Maydellways that introduced additional host software or hardware 311*f3478392SPeter Maydellrequirements to the VM. This allowed management software to 312*f3478392SPeter Maydellsafely change the machine type of an existing VM without 313*f3478392SPeter Maydellintroducing new requirements ("runnability guarantee"). This 314*f3478392SPeter Maydellprevented CPU models from being updated to include CPU 315*f3478392SPeter Maydellvulnerability mitigations, leaving guests vulnerable in the 316*f3478392SPeter Maydelldefault configuration. 317*f3478392SPeter Maydell 318*f3478392SPeter MaydellThe CPU model runnability guarantee won't apply anymore to 319*f3478392SPeter Maydellexisting CPU models. Management software that needs runnability 320*f3478392SPeter Maydellguarantees must resolve the CPU model aliases using the 321*f3478392SPeter Maydell``alias-of`` field returned by the ``query-cpu-definitions`` QMP 322*f3478392SPeter Maydellcommand. 323*f3478392SPeter Maydell 324*f3478392SPeter MaydellWhile those guarantees are kept, the return value of 325*f3478392SPeter Maydell``query-cpu-definitions`` will have existing CPU model aliases 326*f3478392SPeter Maydellpoint to a version that doesn't break runnability guarantees 327*f3478392SPeter Maydell(specifically, version 1 of those CPU models). In future QEMU 328*f3478392SPeter Maydellversions, aliases will point to newer CPU model versions 329*f3478392SPeter Maydelldepending on the machine type, so management software must 330*f3478392SPeter Maydellresolve CPU model aliases before starting a virtual machine. 331*f3478392SPeter Maydell 332*f3478392SPeter MaydellGuest Emulator ISAs 333*f3478392SPeter Maydell------------------- 334*f3478392SPeter Maydell 335*f3478392SPeter MaydellnanoMIPS ISA 336*f3478392SPeter Maydell'''''''''''' 337*f3478392SPeter Maydell 338*f3478392SPeter MaydellThe ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. 339*f3478392SPeter MaydellAs it is hard to generate binaries for it, declare it deprecated. 340