docs/system/removed-features.rst

   1
   2 Removed features
   3 ================
   4
   5 What follows is a record of recently removed, formerly deprecated
   6 features that serves as a record for users who have encountered
   7 trouble after a recent upgrade.
   8
   9 System emulator command line arguments
  10 --------------------------------------
  11
  12 ``-net ...,name=``\ *name* (removed in 5.1)
  13 '''''''''''''''''''''''''''''''''''''''''''
  14
  15 The ``name`` parameter of the ``-net`` option was a synonym
  16 for the ``id`` parameter, which should now be used instead.
  17
  18 ``-no-kvm`` (removed in 5.2)
  19 ''''''''''''''''''''''''''''
  20
  21 The ``-no-kvm`` argument was a synonym for setting ``-machine accel=tcg``.
  22
  23 ``-realtime`` (removed in 6.0)
  24 ''''''''''''''''''''''''''''''
  25
  26 The ``-realtime mlock=on|off`` argument has been replaced by the
  27 ``-overcommit mem-lock=on|off`` argument.
  28
  29 ``-show-cursor`` option (removed in 6.0)
  30 ''''''''''''''''''''''''''''''''''''''''
  31
  32 Use ``-display sdl,show-cursor=on``, ``-display gtk,show-cursor=on``
  33 or ``-display default,show-cursor=on`` instead.
  34
  35 ``-tb-size`` option (removed in 6.0)
  36 ''''''''''''''''''''''''''''''''''''
  37
  38 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
  39 block cache, ``-accel tcg,tb-size=``.
  40
  41 ``-usbdevice audio`` (removed in 6.0)
  42 '''''''''''''''''''''''''''''''''''''
  43
  44 This option lacked the possibility to specify an audio backend device.
  45 Use ``-device usb-audio`` now instead (and specify a corresponding USB
  46 host controller or ``-usb`` if necessary).
  47
  48 ``-vnc acl`` (removed in 6.0)
  49 '''''''''''''''''''''''''''''
  50
  51 The ``acl`` option to the ``-vnc`` argument has been replaced
  52 by the ``tls-authz`` and ``sasl-authz`` options.
  53
  54 ``-mon ...,control=readline,pretty=on|off`` (removed in 6.0)
  55 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  56
  57 The ``pretty=on|off`` switch has no effect for HMP monitors and
  58 its use is rejected.
  59
  60 ``-drive file=json:{...{'driver':'file'}}`` (removed 6.0)
  61 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
  62
  63 The 'file' driver for drives is no longer appropriate for character or host
  64 devices and will only accept regular files (S_IFREG). The correct driver
  65 for these file types is 'host_cdrom' or 'host_device' as appropriate.
  66
  67 Floppy controllers' drive properties (removed in 6.0)
  68 '''''''''''''''''''''''''''''''''''''''''''''''''''''
  69
  70 Use ``-device floppy,...`` instead.  When configuring onboard floppy
  71 controllers
  72 ::
  73
  74     -global isa-fdc.driveA=...
  75     -global sysbus-fdc.driveA=...
  76     -global SUNW,fdtwo.drive=...
  77
  78 become
  79 ::
  80
  81     -device floppy,unit=0,drive=...
  82
  83 and
  84 ::
  85
  86     -global isa-fdc.driveB=...
  87     -global sysbus-fdc.driveB=...
  88
  89 become
  90 ::
  91
  92     -device floppy,unit=1,drive=...
  93
  94 When plugging in a floppy controller
  95 ::
  96
  97     -device isa-fdc,...,driveA=...
  98
  99 becomes
 100 ::
 101
 102     -device isa-fdc,...
 103     -device floppy,unit=0,drive=...
 104
 105 and
 106 ::
 107
 108     -device isa-fdc,...,driveB=...
 109
 110 becomes
 111 ::
 112
 113     -device isa-fdc,...
 114     -device floppy,unit=1,drive=...
 115
 116 ``-drive`` with bogus interface type (removed in 6.0)
 117 '''''''''''''''''''''''''''''''''''''''''''''''''''''
 118
 119 Drives with interface types other than ``if=none`` are for onboard
 120 devices.  Drives the board doesn't pick up can no longer be used with
 121 -device.  Use ``if=none`` instead.
 122
 123 ``-usbdevice ccid`` (removed in 6.0)
 124 '''''''''''''''''''''''''''''''''''''
 125
 126 This option was undocumented and not used in the field.
 127 Use `-device usb-ccid`` instead.
 128
 129
 130 QEMU Machine Protocol (QMP) commands
 131 ------------------------------------
 132
 133 ``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2.0)
 134 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 135
 136 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
 137 are automatically loaded from qcow2 images.
 138
 139 ``cpu-add`` (removed in 5.2)
 140 ''''''''''''''''''''''''''''
 141
 142 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
 143 documentation of ``query-hotpluggable-cpus`` for additional details.
 144
 145 ``change`` (removed in 6.0)
 146 '''''''''''''''''''''''''''
 147
 148 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
 149
 150 ``query-events`` (removed in 6.0)
 151 '''''''''''''''''''''''''''''''''
 152
 153 The ``query-events`` command has been superseded by the more powerful
 154 and accurate ``query-qmp-schema`` command.
 155
 156 ``migrate_set_cache_size`` and ``query-migrate-cache-size`` (removed in 6.0)
 157 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 158
 159 Use ``migrate_set_parameter`` and ``info migrate_parameters`` instead.
 160
 161 ``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
 162 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 163
 164 Use ``migrate_set_parameter`` instead.
 165
 166 ``query-cpus`` (removed in 6.0)
 167 '''''''''''''''''''''''''''''''
 168
 169 The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
 170
 171 ``query-cpus-fast`` ``arch`` output member (removed in 6.0)
 172 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 173
 174 The ``arch`` output member of the ``query-cpus-fast`` command is
 175 replaced by the ``target`` output member.
 176
 177 chardev client socket with ``wait`` option (removed in 6.0)
 178 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 179
 180 Character devices creating sockets in client mode should not specify
 181 the 'wait' field, which is only applicable to sockets in server mode
 182
 183 ``query-named-block-nodes`` result ``encryption_key_missing`` (removed in 6.0)
 184 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 185
 186 Removed with no replacement.
 187
 188 ``query-block`` result ``inserted.encryption_key_missing`` (removed in 6.0)
 189 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 190
 191 Removed with no replacement.
 192
 193 ``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (removed in 6.0)
 194 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 195
 196 The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
 197 these commands is removed. Two new boolean fields, ``recording`` and
 198 ``busy`` effectively replace it.
 199
 200 ``query-block`` result field ``dirty-bitmaps`` (removed in 6.0)
 201 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 202
 203 The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
 204 the query-block command is itself now removed. The ``dirty-bitmaps``
 205 field of the ``BlockDeviceInfo`` struct should be used instead, which is the
 206 type of the ``inserted`` field in query-block replies, as well as the
 207 type of array items in query-named-block-nodes.
 208
 209 ``object-add`` option ``props`` (removed in 6.0)
 210 ''''''''''''''''''''''''''''''''''''''''''''''''
 211
 212 Specify the properties for the object as top-level arguments instead.
 213
 214 Human Monitor Protocol (HMP) commands
 215 -------------------------------------
 216
 217 The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
 218 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 219
 220 The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
 221 'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
 222
 223 ``cpu-add`` (removed in 5.2)
 224 ''''''''''''''''''''''''''''
 225
 226 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
 227 documentation of ``query-hotpluggable-cpus`` for additional details.
 228
 229 ``change vnc TARGET`` (removed in 6.0)
 230 ''''''''''''''''''''''''''''''''''''''
 231
 232 No replacement.  The ``change vnc password`` and ``change DEVICE MEDIUM``
 233 commands are not affected.
 234
 235 ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (removed in 6.0)
 236 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 237
 238 The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
 239 ``acl_remove`` commands were removed with no replacement. Authorization
 240 for VNC should be performed using the pluggable QAuthZ objects.
 241
 242 ``migrate-set-cache-size`` and ``info migrate-cache-size`` (removed in 6.0)
 243 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 244
 245 Use ``migrate-set-parameters`` and ``info migrate-parameters`` instead.
 246
 247 ``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
 248 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 249
 250 Use ``migrate-set-parameters`` instead.
 251
 252 Guest Emulator ISAs
 253 -------------------
 254
 255 RISC-V ISA privilege specification version 1.09.1 (removed in 5.1)
 256 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 257
 258 The RISC-V ISA privilege specification version 1.09.1 has been removed.
 259 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
 260 should be used instead of the 1.09.1 version.
 261
 262 System emulator CPUS
 263 --------------------
 264
 265 KVM guest support on 32-bit Arm hosts (removed in 5.2)
 266 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
 267
 268 The Linux kernel has dropped support for allowing 32-bit Arm systems
 269 to host KVM guests as of the 5.7 kernel. Accordingly, QEMU is deprecating
 270 its support for this configuration and will remove it in a future version.
 271 Running 32-bit guests on a 64-bit Arm host remains supported.
 272
 273 RISC-V ISA Specific CPUs (removed in 5.1)
 274 '''''''''''''''''''''''''''''''''''''''''
 275
 276 The RISC-V cpus with the ISA version in the CPU name have been removed. The
 277 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
 278 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
 279 option when using the ``rv32`` or ``rv64`` CPUs.
 280
 281 RISC-V no MMU CPUs (removed in 5.1)
 282 '''''''''''''''''''''''''''''''''''
 283
 284 The RISC-V no MMU cpus have been removed. The two CPUs: ``rv32imacu-nommu`` and
 285 ``rv64imacu-nommu`` can no longer be used. Instead the MMU status can be specified
 286 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
 287
 288 ``compat`` property of server class POWER CPUs (removed in 6.0)
 289 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 290
 291 The ``max-cpu-compat`` property of the ``pseries`` machine type should be used
 292 instead.
 293
 294 ``moxie`` CPU (removed in 6.1)
 295 ''''''''''''''''''''''''''''''
 296
 297 Nobody was using this CPU emulation in QEMU, and there were no test images
 298 available to make sure that the code is still working, so it has been removed
 299 without replacement.
 300
 301 ``lm32`` CPUs (removed in 6.1.0)
 302 ''''''''''''''''''''''''''''''''
 303
 304 The only public user of this architecture was the milkymist project,
 305 which has been dead for years; there was never an upstream Linux
 306 port.  Removed without replacement.
 307
 308 ``unicore32`` CPUs (since 6.1.0)
 309 ''''''''''''''''''''''''''''''''
 310
 311 Support for this CPU was removed from the upstream Linux kernel, and
 312 there is no available upstream toolchain to build binaries for it.
 313 Removed without replacement.
 314
 315 System emulator machines
 316 ------------------------
 317
 318 ``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
 319 '''''''''''''''''''''''''''''''''''''''''''''''''''''
 320
 321 The version specific Spike machines have been removed in favour of the
 322 generic ``spike`` machine. If you need to specify an older version of the RISC-V
 323 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument.
 324
 325 mips ``r4k`` platform (removed in 5.2)
 326 ''''''''''''''''''''''''''''''''''''''
 327
 328 This machine type was very old and unmaintained. Users should use the ``malta``
 329 machine type instead.
 330
 331 mips ``fulong2e`` machine alias (removed in 6.0)
 332 ''''''''''''''''''''''''''''''''''''''''''''''''
 333
 334 This machine has been renamed ``fuloong2e``.
 335
 336 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (removed in 6.0)
 337 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 338
 339 These machine types were very old and likely could not be used for live
 340 migration from old QEMU versions anymore. Use a newer machine type instead.
 341
 342
 343 linux-user mode CPUs
 344 --------------------
 345
 346 ``tilegx`` CPUs (removed in 6.0)
 347 ''''''''''''''''''''''''''''''''
 348
 349 The ``tilegx`` guest CPU support has been removed without replacement. It was
 350 only implemented in linux-user mode, but support for this CPU was removed from
 351 the upstream Linux kernel in 2018, and it has also been dropped from glibc, so
 352 there is no new Linux development taking place with this architecture. For
 353 running the old binaries, you can use older versions of QEMU.
 354
 355 System emulator devices
 356 -----------------------
 357
 358 ``ide-drive`` (removed in 6.0)
 359 ''''''''''''''''''''''''''''''
 360
 361 The 'ide-drive' device has been removed. Users should use 'ide-hd' or
 362 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
 363
 364 ``scsi-disk`` (removed in 6.0)
 365 ''''''''''''''''''''''''''''''
 366
 367 The 'scsi-disk' device has been removed. Users should use 'scsi-hd' or
 368 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
 369
 370 Related binaries
 371 ----------------
 372
 373 ``qemu-nbd --partition`` (removed in 5.0)
 374 '''''''''''''''''''''''''''''''''''''''''
 375
 376 The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
 377 could only handle MBR partitions, and never correctly handled logical
 378 partitions beyond partition 5.  Exporting a partition can still be
 379 done by utilizing the ``--image-opts`` option with a raw blockdev
 380 using the ``offset`` and ``size`` parameters layered on top of
 381 any other existing blockdev. For example, if partition 1 is 100MiB
 382 long starting at 1MiB, the old command::
 383
 384   qemu-nbd -t -P 1 -f qcow2 file.qcow2
 385
 386 can be rewritten as::
 387
 388   qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
 389
 390 ``qemu-img convert -n -o`` (removed in 5.1)
 391 '''''''''''''''''''''''''''''''''''''''''''
 392
 393 All options specified in ``-o`` are image creation options, so
 394 they are now rejected when used with ``-n`` to skip image creation.
 395
 396
 397 ``qemu-img create -b bad file $size`` (removed in 5.1)
 398 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
 399
 400 When creating an image with a backing file that could not be opened,
 401 ``qemu-img create`` used to issue a warning about the failure but
 402 proceed with the image creation if an explicit size was provided.
 403 However, as the ``-u`` option exists for this purpose, it is safer to
 404 enforce that any failure to open the backing image (including if the
 405 backing file is missing or an incorrect format was specified) is an
 406 error when ``-u`` is not used.
 407
 408 Command line options
 409 --------------------
 410
 411 ``-smp`` (invalid topologies) (removed 5.2)
 412 '''''''''''''''''''''''''''''''''''''''''''
 413
 414 CPU topology properties should describe whole machine topology including
 415 possible CPUs.
 416
 417 However, historically it was possible to start QEMU with an incorrect topology
 418 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
 419 which could lead to an incorrect topology enumeration by the guest.
 420 Support for invalid topologies is removed, the user must ensure
 421 topologies described with -smp include all possible cpus, i.e.
 422 *sockets* * *cores* * *threads* = *maxcpus*.
 423
 424 ``-numa`` node (without memory specified) (removed 5.2)
 425 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 426
 427 Splitting RAM by default between NUMA nodes had the same issues as ``mem``
 428 parameter with the difference that the role of the user plays QEMU using
 429 implicit generic or board specific splitting rule.
 430 Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
 431 it's supported by used machine type) to define mapping explicitly instead.
 432 Users of existing VMs, wishing to preserve the same RAM distribution, should
 433 configure it explicitly using ``-numa node,memdev`` options. Current RAM
 434 distribution can be retrieved using HMP command ``info numa`` and if separate
 435 memory devices (pc|nv-dimm) are present use ``info memory-device`` and subtract
 436 device memory from output of ``info numa``.
 437
 438 ``-numa node,mem=``\ *size* (removed in 5.1)
 439 ''''''''''''''''''''''''''''''''''''''''''''
 440
 441 The parameter ``mem`` of ``-numa node`` was used to assign a part of
 442 guest RAM to a NUMA node. But when using it, it's impossible to manage a specified
 443 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
 444 so the guest ends up with the fake NUMA configuration with suboptiomal performance.
 445 However since 2014 there is an alternative way to assign RAM to a NUMA node
 446 using parameter ``memdev``, which does the same as ``mem`` and adds
 447 means to actually manage node RAM on the host side. Use parameter ``memdev``
 448 with *memory-backend-ram* backend as replacement for parameter ``mem``
 449 to achieve the same fake NUMA effect or a properly configured
 450 *memory-backend-file* backend to actually benefit from NUMA configuration.
 451 New machine versions (since 5.1) will not accept the option but it will still
 452 work with old machine types. User can check the QAPI schema to see if the legacy
 453 option is supported by looking at MachineInfo::numa-mem-supported property.
 454
 455 ``-mem-path`` fallback to RAM (removed in 5.0)
 456 ''''''''''''''''''''''''''''''''''''''''''''''
 457
 458 If guest RAM allocation from file pointed by ``mem-path`` failed,
 459 QEMU was falling back to allocating from RAM, which might have resulted
 460 in unpredictable behavior since the backing file specified by the user
 461 as ignored. Currently, users are responsible for making sure the backing storage
 462 specified with ``-mem-path`` can actually provide the guest RAM configured with
 463 ``-m`` and QEMU fails to start up if RAM allocation is unsuccessful.
 464
 465 ``-smp`` (invalid topologies) (removed 5.2)
 466 '''''''''''''''''''''''''''''''''''''''''''
 467
 468 CPU topology properties should describe whole machine topology including
 469 possible CPUs.
 470
 471 However, historically it was possible to start QEMU with an incorrect topology
 472 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
 473 which could lead to an incorrect topology enumeration by the guest.
 474 Support for invalid topologies is removed, the user must ensure
 475 topologies described with -smp include all possible cpus, i.e.
 476 *sockets* * *cores* * *threads* = *maxcpus*.
 477
 478 ``-machine enforce-config-section=on|off`` (removed 5.2)
 479 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 480
 481 The ``enforce-config-section`` property was replaced by the
 482 ``-global migration.send-configuration={on|off}`` option.
 483
 484 Block devices
 485 -------------
 486
 487 VXHS backend (removed in 5.1)
 488 '''''''''''''''''''''''''''''
 489
 490 The VXHS code did not compile since v2.12.0. It was removed in 5.1.
 491
 492 ``sheepdog`` driver (removed in 6.0)
 493 ''''''''''''''''''''''''''''''''''''
 494
 495 The corresponding upstream server project is no longer maintained.
 496 Users are recommended to switch to an alternative distributed block
 497 device driver such as RBD.