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