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