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.
9 System emulator command line arguments
10 --------------------------------------
12 ``-net ...,name=``\ *name* (removed in 5.1)
13 '''''''''''''''''''''''''''''''''''''''''''
15 The ``name`` parameter of the ``-net`` option was a synonym
16 for the ``id`` parameter, which should now be used instead.
18 ``-no-kvm`` (removed in 5.2)
19 ''''''''''''''''''''''''''''
21 The ``-no-kvm`` argument was a synonym for setting ``-machine accel=tcg``.
23 ``-realtime`` (removed in 6.0)
24 ''''''''''''''''''''''''''''''
26 The ``-realtime mlock=on|off`` argument has been replaced by the
27 ``-overcommit mem-lock=on|off`` argument.
29 ``-show-cursor`` option (removed in 6.0)
30 ''''''''''''''''''''''''''''''''''''''''
32 Use ``-display sdl,show-cursor=on``, ``-display gtk,show-cursor=on``
33 or ``-display default,show-cursor=on`` instead.
35 ``-tb-size`` option (removed in 6.0)
36 ''''''''''''''''''''''''''''''''''''
38 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
39 block cache, ``-accel tcg,tb-size=``.
41 ``-usbdevice audio`` (removed in 6.0)
42 '''''''''''''''''''''''''''''''''''''
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).
48 ``-vnc acl`` (removed in 6.0)
49 '''''''''''''''''''''''''''''
51 The ``acl`` option to the ``-vnc`` argument has been replaced
52 by the ``tls-authz`` and ``sasl-authz`` options.
54 ``-mon ...,control=readline,pretty=on|off`` (removed in 6.0)
55 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
57 The ``pretty=on|off`` switch has no effect for HMP monitors and
60 ``-drive file=json:{...{'driver':'file'}}`` (removed 6.0)
61 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
67 Floppy controllers' drive properties (removed in 6.0)
68 '''''''''''''''''''''''''''''''''''''''''''''''''''''
70 Use ``-device floppy,...`` instead. When configuring onboard floppy
74 -global isa-fdc.driveA=...
75 -global sysbus-fdc.driveA=...
76 -global SUNW,fdtwo.drive=...
81 -device floppy,unit=0,drive=...
86 -global isa-fdc.driveB=...
87 -global sysbus-fdc.driveB=...
92 -device floppy,unit=1,drive=...
94 When plugging in a floppy controller
97 -device isa-fdc,...,driveA=...
103 -device floppy,unit=0,drive=...
108 -device isa-fdc,...,driveB=...
114 -device floppy,unit=1,drive=...
116 ``-drive`` with bogus interface type (removed in 6.0)
117 '''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
123 ``-usbdevice ccid`` (removed in 6.0)
124 '''''''''''''''''''''''''''''''''''''
126 This option was undocumented and not used in the field.
127 Use `-device usb-ccid`` instead.
130 QEMU Machine Protocol (QMP) commands
131 ------------------------------------
133 ``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2.0)
134 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
136 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
137 are automatically loaded from qcow2 images.
139 ``cpu-add`` (removed in 5.2)
140 ''''''''''''''''''''''''''''
142 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
143 documentation of ``query-hotpluggable-cpus`` for additional details.
145 ``change`` (removed in 6.0)
146 '''''''''''''''''''''''''''
148 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
150 ``query-events`` (removed in 6.0)
151 '''''''''''''''''''''''''''''''''
153 The ``query-events`` command has been superseded by the more powerful
154 and accurate ``query-qmp-schema`` command.
156 ``migrate_set_cache_size`` and ``query-migrate-cache-size`` (removed in 6.0)
157 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
159 Use ``migrate_set_parameter`` and ``info migrate_parameters`` instead.
161 ``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
162 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
164 Use ``migrate_set_parameter`` instead.
166 ``query-cpus`` (removed in 6.0)
167 '''''''''''''''''''''''''''''''
169 The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
171 ``query-cpus-fast`` ``arch`` output member (removed in 6.0)
172 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
174 The ``arch`` output member of the ``query-cpus-fast`` command is
175 replaced by the ``target`` output member.
177 chardev client socket with ``wait`` option (removed in 6.0)
178 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
180 Character devices creating sockets in client mode should not specify
181 the 'wait' field, which is only applicable to sockets in server mode
183 ``query-named-block-nodes`` result ``encryption_key_missing`` (removed in 6.0)
184 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
186 Removed with no replacement.
188 ``query-block`` result ``inserted.encryption_key_missing`` (removed in 6.0)
189 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
191 Removed with no replacement.
193 ``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (removed in 6.0)
194 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
200 ``query-block`` result field ``dirty-bitmaps`` (removed in 6.0)
201 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
209 ``object-add`` option ``props`` (removed in 6.0)
210 ''''''''''''''''''''''''''''''''''''''''''''''''
212 Specify the properties for the object as top-level arguments instead.
214 Human Monitor Protocol (HMP) commands
215 -------------------------------------
217 The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
218 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
220 The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
221 'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
223 ``cpu-add`` (removed in 5.2)
224 ''''''''''''''''''''''''''''
226 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
227 documentation of ``query-hotpluggable-cpus`` for additional details.
229 ``change vnc TARGET`` (removed in 6.0)
230 ''''''''''''''''''''''''''''''''''''''
232 No replacement. The ``change vnc password`` and ``change DEVICE MEDIUM``
233 commands are not affected.
235 ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (removed in 6.0)
236 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
242 ``migrate-set-cache-size`` and ``info migrate-cache-size`` (removed in 6.0)
243 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
245 Use ``migrate-set-parameters`` and ``info migrate-parameters`` instead.
247 ``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
248 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
250 Use ``migrate-set-parameters`` instead.
255 RISC-V ISA privilege specification version 1.09.1 (removed in 5.1)
256 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
265 KVM guest support on 32-bit Arm hosts (removed in 5.2)
266 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
273 RISC-V ISA Specific CPUs (removed in 5.1)
274 '''''''''''''''''''''''''''''''''''''''''
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.
281 RISC-V no MMU CPUs (removed in 5.1)
282 '''''''''''''''''''''''''''''''''''
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.
288 ``compat`` property of server class POWER CPUs (removed in 6.0)
289 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
291 The ``max-cpu-compat`` property of the ``pseries`` machine type should be used
294 ``moxie`` CPU (removed in 6.1)
295 ''''''''''''''''''''''''''''''
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
301 ``lm32`` CPUs (removed in 6.1.0)
302 ''''''''''''''''''''''''''''''''
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.
308 ``unicore32`` CPUs (since 6.1.0)
309 ''''''''''''''''''''''''''''''''
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.
315 System emulator machines
316 ------------------------
318 ``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
319 '''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
325 mips ``r4k`` platform (removed in 5.2)
326 ''''''''''''''''''''''''''''''''''''''
328 This machine type was very old and unmaintained. Users should use the ``malta``
329 machine type instead.
331 mips ``fulong2e`` machine alias (removed in 6.0)
332 ''''''''''''''''''''''''''''''''''''''''''''''''
334 This machine has been renamed ``fuloong2e``.
336 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (removed in 6.0)
337 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
346 ``tilegx`` CPUs (removed in 6.0)
347 ''''''''''''''''''''''''''''''''
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.
355 System emulator devices
356 -----------------------
358 ``ide-drive`` (removed in 6.0)
359 ''''''''''''''''''''''''''''''
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.
364 ``scsi-disk`` (removed in 6.0)
365 ''''''''''''''''''''''''''''''
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.
373 ``qemu-nbd --partition`` (removed in 5.0)
374 '''''''''''''''''''''''''''''''''''''''''
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::
384 qemu-nbd -t -P 1 -f qcow2 file.qcow2
386 can be rewritten as::
388 qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
390 ``qemu-img convert -n -o`` (removed in 5.1)
391 '''''''''''''''''''''''''''''''''''''''''''
393 All options specified in ``-o`` are image creation options, so
394 they are now rejected when used with ``-n`` to skip image creation.
397 ``qemu-img create -b bad file $size`` (removed in 5.1)
398 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
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.
411 ``-smp`` (invalid topologies) (removed 5.2)
412 '''''''''''''''''''''''''''''''''''''''''''
414 CPU topology properties should describe whole machine topology including
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*.
424 ``-numa`` node (without memory specified) (removed 5.2)
425 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
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``.
438 ``-numa node,mem=``\ *size* (removed in 5.1)
439 ''''''''''''''''''''''''''''''''''''''''''''
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.
455 ``-mem-path`` fallback to RAM (removed in 5.0)
456 ''''''''''''''''''''''''''''''''''''''''''''''
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.
465 ``-smp`` (invalid topologies) (removed 5.2)
466 '''''''''''''''''''''''''''''''''''''''''''
468 CPU topology properties should describe whole machine topology including
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*.
478 ``-machine enforce-config-section=on|off`` (removed 5.2)
479 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
481 The ``enforce-config-section`` property was replaced by the
482 ``-global migration.send-configuration={on|off}`` option.
487 VXHS backend (removed in 5.1)
488 '''''''''''''''''''''''''''''
490 The VXHS code did not compile since v2.12.0. It was removed in 5.1.
492 ``sheepdog`` driver (removed in 6.0)
493 ''''''''''''''''''''''''''''''''''''
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.