docs/about/deprecated.rst

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