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