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 System emulator machines
 302 ------------------------
 303
 304 ``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
 305 '''''''''''''''''''''''''''''''''''''''''''''''''''''
 306
 307 The version specific Spike machines have been removed in favour of the
 308 generic ``spike`` machine. If you need to specify an older version of the RISC-V
 309 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument.
 310
 311 mips ``r4k`` platform (removed in 5.2)
 312 ''''''''''''''''''''''''''''''''''''''
 313
 314 This machine type was very old and unmaintained. Users should use the ``malta``
 315 machine type instead.
 316
 317 mips ``fulong2e`` machine alias (removed in 6.0)
 318 ''''''''''''''''''''''''''''''''''''''''''''''''
 319
 320 This machine has been renamed ``fuloong2e``.
 321
 322 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (removed in 6.0)
 323 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 324
 325 These machine types were very old and likely could not be used for live
 326 migration from old QEMU versions anymore. Use a newer machine type instead.
 327
 328
 329 linux-user mode CPUs
 330 --------------------
 331
 332 ``tilegx`` CPUs (removed in 6.0)
 333 ''''''''''''''''''''''''''''''''
 334
 335 The ``tilegx`` guest CPU support has been removed without replacement. It was
 336 only implemented in linux-user mode, but support for this CPU was removed from
 337 the upstream Linux kernel in 2018, and it has also been dropped from glibc, so
 338 there is no new Linux development taking place with this architecture. For
 339 running the old binaries, you can use older versions of QEMU.
 340
 341 System emulator devices
 342 -----------------------
 343
 344 ``ide-drive`` (removed in 6.0)
 345 ''''''''''''''''''''''''''''''
 346
 347 The 'ide-drive' device has been removed. Users should use 'ide-hd' or
 348 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
 349
 350 ``scsi-disk`` (removed in 6.0)
 351 ''''''''''''''''''''''''''''''
 352
 353 The 'scsi-disk' device has been removed. Users should use 'scsi-hd' or
 354 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
 355
 356 Related binaries
 357 ----------------
 358
 359 ``qemu-nbd --partition`` (removed in 5.0)
 360 '''''''''''''''''''''''''''''''''''''''''
 361
 362 The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
 363 could only handle MBR partitions, and never correctly handled logical
 364 partitions beyond partition 5.  Exporting a partition can still be
 365 done by utilizing the ``--image-opts`` option with a raw blockdev
 366 using the ``offset`` and ``size`` parameters layered on top of
 367 any other existing blockdev. For example, if partition 1 is 100MiB
 368 long starting at 1MiB, the old command::
 369
 370   qemu-nbd -t -P 1 -f qcow2 file.qcow2
 371
 372 can be rewritten as::
 373
 374   qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
 375
 376 ``qemu-img convert -n -o`` (removed in 5.1)
 377 '''''''''''''''''''''''''''''''''''''''''''
 378
 379 All options specified in ``-o`` are image creation options, so
 380 they are now rejected when used with ``-n`` to skip image creation.
 381
 382
 383 ``qemu-img create -b bad file $size`` (removed in 5.1)
 384 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
 385
 386 When creating an image with a backing file that could not be opened,
 387 ``qemu-img create`` used to issue a warning about the failure but
 388 proceed with the image creation if an explicit size was provided.
 389 However, as the ``-u`` option exists for this purpose, it is safer to
 390 enforce that any failure to open the backing image (including if the
 391 backing file is missing or an incorrect format was specified) is an
 392 error when ``-u`` is not used.
 393
 394 Command line options
 395 --------------------
 396
 397 ``-smp`` (invalid topologies) (removed 5.2)
 398 '''''''''''''''''''''''''''''''''''''''''''
 399
 400 CPU topology properties should describe whole machine topology including
 401 possible CPUs.
 402
 403 However, historically it was possible to start QEMU with an incorrect topology
 404 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
 405 which could lead to an incorrect topology enumeration by the guest.
 406 Support for invalid topologies is removed, the user must ensure
 407 topologies described with -smp include all possible cpus, i.e.
 408 *sockets* * *cores* * *threads* = *maxcpus*.
 409
 410 ``-numa`` node (without memory specified) (removed 5.2)
 411 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
 412
 413 Splitting RAM by default between NUMA nodes had the same issues as ``mem``
 414 parameter with the difference that the role of the user plays QEMU using
 415 implicit generic or board specific splitting rule.
 416 Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
 417 it's supported by used machine type) to define mapping explicitly instead.
 418 Users of existing VMs, wishing to preserve the same RAM distribution, should
 419 configure it explicitly using ``-numa node,memdev`` options. Current RAM
 420 distribution can be retrieved using HMP command ``info numa`` and if separate
 421 memory devices (pc|nv-dimm) are present use ``info memory-device`` and subtract
 422 device memory from output of ``info numa``.
 423
 424 ``-numa node,mem=``\ *size* (removed in 5.1)
 425 ''''''''''''''''''''''''''''''''''''''''''''
 426
 427 The parameter ``mem`` of ``-numa node`` was used to assign a part of
 428 guest RAM to a NUMA node. But when using it, it's impossible to manage a specified
 429 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
 430 so the guest ends up with the fake NUMA configuration with suboptiomal performance.
 431 However since 2014 there is an alternative way to assign RAM to a NUMA node
 432 using parameter ``memdev``, which does the same as ``mem`` and adds
 433 means to actually manage node RAM on the host side. Use parameter ``memdev``
 434 with *memory-backend-ram* backend as replacement for parameter ``mem``
 435 to achieve the same fake NUMA effect or a properly configured
 436 *memory-backend-file* backend to actually benefit from NUMA configuration.
 437 New machine versions (since 5.1) will not accept the option but it will still
 438 work with old machine types. User can check the QAPI schema to see if the legacy
 439 option is supported by looking at MachineInfo::numa-mem-supported property.
 440
 441 ``-mem-path`` fallback to RAM (removed in 5.0)
 442 ''''''''''''''''''''''''''''''''''''''''''''''
 443
 444 If guest RAM allocation from file pointed by ``mem-path`` failed,
 445 QEMU was falling back to allocating from RAM, which might have resulted
 446 in unpredictable behavior since the backing file specified by the user
 447 as ignored. Currently, users are responsible for making sure the backing storage
 448 specified with ``-mem-path`` can actually provide the guest RAM configured with
 449 ``-m`` and QEMU fails to start up if RAM allocation is unsuccessful.
 450
 451 ``-smp`` (invalid topologies) (removed 5.2)
 452 '''''''''''''''''''''''''''''''''''''''''''
 453
 454 CPU topology properties should describe whole machine topology including
 455 possible CPUs.
 456
 457 However, historically it was possible to start QEMU with an incorrect topology
 458 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
 459 which could lead to an incorrect topology enumeration by the guest.
 460 Support for invalid topologies is removed, the user must ensure
 461 topologies described with -smp include all possible cpus, i.e.
 462 *sockets* * *cores* * *threads* = *maxcpus*.
 463
 464 ``-machine enforce-config-section=on|off`` (removed 5.2)
 465 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 466
 467 The ``enforce-config-section`` property was replaced by the
 468 ``-global migration.send-configuration={on|off}`` option.
 469
 470 Block devices
 471 -------------
 472
 473 VXHS backend (removed in 5.1)
 474 '''''''''''''''''''''''''''''
 475
 476 The VXHS code did not compile since v2.12.0. It was removed in 5.1.
 477
 478 ``sheepdog`` driver (removed in 6.0)
 479 ''''''''''''''''''''''''''''''''''''
 480
 481 The corresponding upstream server project is no longer maintained.
 482 Users are recommended to switch to an alternative distributed block
 483 device driver such as RBD.