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