docs/about/deprecated.rst

   1 .. _Deprecated features:
   2
   3 Deprecated features
   4 ===================
   5
   6 In general features are intended to be supported indefinitely once
   7 introduced into QEMU. In the event that a feature needs to be removed,
   8 it will be listed in this section. The feature will remain functional for the
   9 release in which it was deprecated and one further release. After these two
  10 releases, the feature is liable to be removed. Deprecated features may also
  11 generate warnings on the console when QEMU starts up, or if activated via a
  12 monitor command, however, this is not a mandatory requirement.
  13
  14 Prior to the 2.10.0 release there was no official policy on how
  15 long features would be deprecated prior to their removal, nor
  16 any documented list of which features were deprecated. Thus
  17 any features deprecated prior to 2.10.0 will be treated as if
  18 they were first deprecated in the 2.10.0 release.
  19
  20 What follows is a list of all features currently marked as
  21 deprecated.
  22
  23 System emulator command line arguments
  24 --------------------------------------
  25
  26 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
  27 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  28
  29 The ``-audiodev`` argument is now the preferred way to specify audio
  30 backend settings instead of environment variables.  To ease migration to
  31 the new format, the ``-audiodev-help`` option can be used to convert
  32 the current values of the environment variables to ``-audiodev`` options.
  33
  34 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
  35 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  36
  37 When not using the deprecated legacy audio config, each sound card
  38 should specify an ``audiodev=`` property.  Additionally, when using
  39 vnc, you should specify an ``audiodev=`` property if you plan to
  40 transmit audio through the VNC protocol.
  41
  42 Creating sound card devices using ``-soundhw`` (since 5.1)
  43 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  44
  45 Sound card devices should be created using ``-device`` instead.  The
  46 names are the same for most devices.  The exceptions are ``hda`` which
  47 needs two devices (``-device intel-hda -device hda-duplex``) and
  48 ``pcspk`` which can be activated using ``-machine
  49 pcspk-audiodev=<name>``.
  50
  51 ``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0)
  52 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  53
  54 ``tty`` and ``parport`` are aliases that will be removed. Instead, the
  55 actual backend names ``serial`` and ``parallel`` should be used.
  56
  57 Short-form boolean options (since 6.0)
  58 ''''''''''''''''''''''''''''''''''''''
  59
  60 Boolean options such as ``share=on``/``share=off`` could be written
  61 in short form as ``share`` and ``noshare``.  This is now deprecated
  62 and will cause a warning.
  63
  64 ``delay`` option for socket character devices (since 6.0)
  65 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  66
  67 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
  68 rather than ``delay=off``.
  69
  70 ``-writeconfig`` (since 6.0)
  71 '''''''''''''''''''''''''''''
  72
  73 The ``-writeconfig`` option is not able to serialize the entire contents
  74 of the QEMU command line.  It is thus considered a failed experiment
  75 and deprecated, with no current replacement.
  76
  77 Userspace local APIC with KVM (x86, since 6.0)
  78 ''''''''''''''''''''''''''''''''''''''''''''''
  79
  80 Using ``-M kernel-irqchip=off`` with x86 machine types that include a local
  81 APIC is deprecated.  The ``split`` setting is supported, as is using
  82 ``-M kernel-irqchip=off`` with the ISA PC machine type.
  83
  84 hexadecimal sizes with scaling multipliers (since 6.0)
  85 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
  86
  87 Input parameters that take a size value should only use a size suffix
  88 (such as 'k' or 'M') when the base is written in decimal, and not when
  89 the value is hexadecimal.  That is, '0x20M' is deprecated, and should
  90 be written either as '32M' or as '0x2000000'.
  91
  92 ``-spice password=string`` (since 6.0)
  93 ''''''''''''''''''''''''''''''''''''''
  94
  95 This option is insecure because the SPICE password remains visible in
  96 the process listing. This is replaced by the new ``password-secret``
  97 option which lets the password be securely provided on the command
  98 line using a ``secret`` object instance.
  99
 100 ``opened`` property of ``rng-*`` objects (since 6.0)
 101 ''''''''''''''''''''''''''''''''''''''''''''''''''''
 102
 103 The only effect of specifying ``opened=on`` in the command line or QMP
 104 ``object-add`` is that the device is opened immediately, possibly before all
 105 other options have been processed.  This will either have no effect (if
 106 ``opened`` was the last option) or cause errors.  The property is therefore
 107 useless and should not be specified.
 108
 109 ``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0)
 110 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 111
 112 The only effect of specifying ``loaded=on`` in the command line or QMP
 113 ``object-add`` is that the secret is loaded immediately, possibly before all
 114 other options have been processed.  This will either have no effect (if
 115 ``loaded`` was the last option) or cause options to be effectively ignored as
 116 if they were not given.  The property is therefore useless and should not be
 117 specified.
 118
 119 ``-display sdl,window_close=...`` (since 6.1)
 120 '''''''''''''''''''''''''''''''''''''''''''''
 121
 122 Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
 123 an underscore between "window" and "close").
 124
 125 ``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2)
 126 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 127
 128 Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead.
 129
 130 ``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2)
 131 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 132
 133 Use ``-display sdl,grab-mod=rctrl`` instead.
 134
 135 ``-sdl`` (since 6.2)
 136 ''''''''''''''''''''
 137
 138 Use ``-display sdl`` instead.
 139
 140 ``-curses`` (since 6.2)
 141 '''''''''''''''''''''''
 142
 143 Use ``-display curses`` instead.
 144
 145 ``-watchdog`` (since 6.2)
 146 '''''''''''''''''''''''''
 147
 148 Use ``-device`` instead.
 149
 150 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
 151 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 152
 153 Specified CPU topology parameters must be greater than zero.
 154
 155 In the SMP configuration, users should either provide a CPU topology
 156 parameter with a reasonable value (greater than zero) or just omit it
 157 and QEMU will compute the missing value.
 158
 159 However, historically it was implicitly allowed for users to provide
 160 a parameter with zero value, which is meaningless and could also possibly
 161 cause unexpected results in the -smp parsing. So support for this kind of
 162 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
 163 be removed in the near future, users have to ensure that all the topology
 164 members described with -smp are greater than zero.
 165
 166 Plugin argument passing through ``arg=<string>`` (since 6.1)
 167 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 168
 169 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
 170 command-line less readable, especially when the argument itself consist of a
 171 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
 172 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
 173 as short-form boolean values, and passed to plugins as ``arg_name=on``.
 174 However, short-form booleans are deprecated and full explicit ``arg_name=on``
 175 form is preferred.
 176
 177 ``-drive if=none`` for the sifive_u OTP device (since 6.2)
 178 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 179
 180 Using ``-drive if=none`` to configure the OTP device of the sifive_u
 181 RISC-V machine is deprecated. Use ``-drive if=pflash`` instead.
 182
 183
 184 QEMU Machine Protocol (QMP) commands
 185 ------------------------------------
 186
 187 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
 188 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 189
 190 Use argument ``id`` instead.
 191
 192 ``eject`` argument ``device`` (since 2.8)
 193 '''''''''''''''''''''''''''''''''''''''''
 194
 195 Use argument ``id`` instead.
 196
 197 ``blockdev-change-medium`` argument ``device`` (since 2.8)
 198 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 199
 200 Use argument ``id`` instead.
 201
 202 ``block_set_io_throttle`` argument ``device`` (since 2.8)
 203 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 204
 205 Use argument ``id`` instead.
 206
 207 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
 208 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 209
 210 Use argument value ``null`` instead.
 211
 212 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
 213 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 214
 215 Use arguments ``base-node`` and ``top-node`` instead.
 216
 217 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
 218 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 219
 220 Use the more generic commands ``block-export-add`` and ``block-export-del``
 221 instead.  As part of this deprecation, where ``nbd-server-add`` used a
 222 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
 223
 224 ``query-qmp-schema`` return value member ``values`` (since 6.2)
 225 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 226
 227 Member ``values`` in return value elements with meta-type ``enum`` is
 228 deprecated.  Use ``members`` instead.
 229
 230 ``drive-backup`` (since 6.2)
 231 ''''''''''''''''''''''''''''
 232
 233 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
 234 This change primarily separates the creation/opening process of the backup
 235 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
 236 same arguments as ``drive-backup``, except the ``format`` and ``mode``
 237 options are removed in favor of using explicit ``blockdev-create`` and
 238 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
 239 details.
 240
 241 Incorrectly typed ``device_add`` arguments (since 6.2)
 242 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
 243
 244 Due to shortcomings in the internal implementation of ``device_add``, QEMU
 245 incorrectly accepts certain invalid arguments: Any object or list arguments are
 246 silently ignored. Other argument types are not checked, but an implicit
 247 conversion happens, so that e.g. string values can be assigned to integer
 248 device properties or vice versa.
 249
 250 This is a bug in QEMU that will be fixed in the future so that previously
 251 accepted incorrect commands will return an error. Users should make sure that
 252 all arguments passed to ``device_add`` are consistent with the documented
 253 property types.
 254
 255 ``query-sgx`` return value member ``section-size`` (since 7.0)
 256 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 257
 258 Member ``section-size`` in return value elements with meta-type ``uint64`` is
 259 deprecated.  Use ``sections`` instead.
 260
 261
 262 ``query-sgx-capabilities`` return value member ``section-size`` (since 7.0)
 263 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 264
 265 Member ``section-size`` in return value elements with meta-type ``uint64`` is
 266 deprecated.  Use ``sections`` instead.
 267
 268 System accelerators
 269 -------------------
 270
 271 MIPS ``Trap-and-Emul`` KVM support (since 6.0)
 272 ''''''''''''''''''''''''''''''''''''''''''''''
 273
 274 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
 275 from Linux upstream kernel, declare it deprecated.
 276
 277 System emulator CPUS
 278 --------------------
 279
 280 ``Icelake-Client`` CPU Model (since 5.2)
 281 ''''''''''''''''''''''''''''''''''''''''
 282
 283 ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
 284 Models instead.
 285
 286 MIPS ``I7200`` CPU Model (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
 294 QEMU API (QAPI) events
 295 ----------------------
 296
 297 ``MEM_UNPLUG_ERROR`` (since 6.2)
 298 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 299
 300 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
 301
 302
 303 System emulator machines
 304 ------------------------
 305
 306 PPC 405 ``taihu`` machine (since 7.0)
 307 '''''''''''''''''''''''''''''''''''''
 308
 309 The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar,
 310 except for some external periphery. However, the periphery of the ``taihu``
 311 machine is hardly emulated at all (e.g. neither the LCD nor the USB part had
 312 been implemented), so there is not much value added by this board. Use the
 313 ``ref405ep`` machine instead.
 314
 315 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0)
 316 '''''''''''''''''''''''''''''''''''''''''''''''''''''
 317
 318 These old machine types are quite neglected nowadays and thus might have
 319 various pitfalls with regards to live migration. Use a newer machine type
 320 instead.
 321
 322
 323 Backend options
 324 ---------------
 325
 326 Using non-persistent backing file with pmem=on (since 6.1)
 327 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 328
 329 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
 330 device. However enabling ``memory-backend-file.pmem`` option, when backing file
 331 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
 332 of persistent memory, is not safe and may lead to data loss or corruption in case
 333 of host crash.
 334 Options are:
 335
 336     - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
 337       (without persistence guaranties) with backing file on non DAX storage
 338     - move backing file to NVDIMM storage and keep ``pmem=on``
 339       (to have NVDIMM with persistence guaranties).
 340
 341 Device options
 342 --------------
 343
 344 Emulated device options
 345 '''''''''''''''''''''''
 346
 347 ``-device virtio-blk,scsi=on|off`` (since 5.0)
 348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 349
 350 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
 351 and later do not support it because the virtio-scsi device was introduced for
 352 full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
 353
 354 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
 355 alias.
 356
 357 ``-device sga`` (since 6.2)
 358 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 359
 360 The ``sga`` device loads an option ROM for x86 targets which enables
 361 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
 362 contains native support for this feature and thus use of the option
 363 ROM approach is obsolete. The native SeaBIOS support can be activated
 364 by using ``-machine graphics=off``.
 365
 366
 367 Block device options
 368 ''''''''''''''''''''
 369
 370 ``"backing": ""`` (since 2.12)
 371 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 372
 373 In order to prevent QEMU from automatically opening an image's backing
 374 chain, use ``"backing": null`` instead.
 375
 376 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
 377 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 378
 379 Options for ``rbd`` should be specified according to its runtime options,
 380 like other block drivers.  Legacy parsing of keyvalue pair encoded
 381 filenames is useful to open images with the old format for backing files;
 382 These image files should be updated to use the current format.
 383
 384 Example of legacy encoding::
 385
 386   json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
 387
 388 The above, converted to the current supported format::
 389
 390   json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
 391
 392 linux-user mode CPUs
 393 --------------------
 394
 395 MIPS ``I7200`` CPU (since 5.2)
 396 ''''''''''''''''''''''''''''''
 397
 398 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
 399 (the ISA has never been upstreamed to a compiler toolchain). Therefore
 400 this CPU is also deprecated.
 401
 402 Backwards compatibility
 403 -----------------------
 404
 405 Runnability guarantee of CPU models (since 4.1)
 406 '''''''''''''''''''''''''''''''''''''''''''''''
 407
 408 Previous versions of QEMU never changed existing CPU models in
 409 ways that introduced additional host software or hardware
 410 requirements to the VM.  This allowed management software to
 411 safely change the machine type of an existing VM without
 412 introducing new requirements ("runnability guarantee").  This
 413 prevented CPU models from being updated to include CPU
 414 vulnerability mitigations, leaving guests vulnerable in the
 415 default configuration.
 416
 417 The CPU model runnability guarantee won't apply anymore to
 418 existing CPU models.  Management software that needs runnability
 419 guarantees must resolve the CPU model aliases using the
 420 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
 421 command.
 422
 423 While those guarantees are kept, the return value of
 424 ``query-cpu-definitions`` will have existing CPU model aliases
 425 point to a version that doesn't break runnability guarantees
 426 (specifically, version 1 of those CPU models).  In future QEMU
 427 versions, aliases will point to newer CPU model versions
 428 depending on the machine type, so management software must
 429 resolve CPU model aliases before starting a virtual machine.
 430
 431 Guest Emulator ISAs
 432 -------------------
 433
 434 nanoMIPS ISA
 435 ''''''''''''
 436
 437 The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
 438 As it is hard to generate binaries for it, declare it deprecated.
 439
 440 Tools
 441 -----
 442
 443 virtiofsd
 444 '''''''''
 445
 446 There is a new Rust implementation of ``virtiofsd`` at
 447 ``https://gitlab.com/virtio-fs/virtiofsd``;
 448 since this is now marked stable, new development should be done on that
 449 rather than the existing C version in the QEMU tree.
 450 The C version will still accept fixes and patches that
 451 are already in development for the moment, but will eventually
 452 be deleted from this tree.
 453 New deployments should use the Rust version, and existing systems
 454 should consider moving to it.  The command line and feature set
 455 is very close and moving should be simple.