1
2Removed features
3================
4
5What follows is a record of recently removed, formerly deprecated
6features that serves as a record for users who have encountered
7trouble after a recent upgrade.
8
9System emulator command line arguments
10--------------------------------------
11
12``-net ...,name=``\ *name* (removed in 5.1)
13'''''''''''''''''''''''''''''''''''''''''''
14
15The ``name`` parameter of the ``-net`` option was a synonym
16for the ``id`` parameter, which should now be used instead.
17
18``-no-kvm`` (removed in 5.2)
19''''''''''''''''''''''''''''
20
21The ``-no-kvm`` argument was a synonym for setting ``-machine accel=tcg``.
22
23``-realtime`` (removed in 6.0)
24''''''''''''''''''''''''''''''
25
26The ``-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
32Use ``-display sdl,show-cursor=on``, ``-display gtk,show-cursor=on``
33or ``-display default,show-cursor=on`` instead.
34
35``-tb-size`` option (removed in 6.0)
36''''''''''''''''''''''''''''''''''''
37
38QEMU 5.0 introduced an alternative syntax to specify the size of the translation
39block cache, ``-accel tcg,tb-size=``.
40
41``-usbdevice audio`` (removed in 6.0)
42'''''''''''''''''''''''''''''''''''''
43
44This option lacked the possibility to specify an audio backend device.
45Use ``-device usb-audio`` now instead (and specify a corresponding USB
46host controller or ``-usb`` if necessary).
47
48``-vnc acl`` (removed in 6.0)
49'''''''''''''''''''''''''''''
50
51The ``acl`` option to the ``-vnc`` argument has been replaced
52by the ``tls-authz`` and ``sasl-authz`` options.
53
54``-mon ...,control=readline,pretty=on|off`` (removed in 6.0)
55''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
56
57The ``pretty=on|off`` switch has no effect for HMP monitors and
58its use is rejected.
59
60``-drive file=json:{...{'driver':'file'}}`` (removed 6.0)
61'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
62
63The 'file' driver for drives is no longer appropriate for character or host
64devices and will only accept regular files (S_IFREG). The correct driver
65for these file types is 'host_cdrom' or 'host_device' as appropriate.
66
67Floppy controllers' drive properties (removed in 6.0)
68'''''''''''''''''''''''''''''''''''''''''''''''''''''
69
70Use ``-device floppy,...`` instead.  When configuring onboard floppy
71controllers
72::
73
74    -global isa-fdc.driveA=...
75    -global sysbus-fdc.driveA=...
76    -global SUNW,fdtwo.drive=...
77
78become
79::
80
81    -device floppy,unit=0,drive=...
82
83and
84::
85
86    -global isa-fdc.driveB=...
87    -global sysbus-fdc.driveB=...
88
89become
90::
91
92    -device floppy,unit=1,drive=...
93
94When plugging in a floppy controller
95::
96
97    -device isa-fdc,...,driveA=...
98
99becomes
100::
101
102    -device isa-fdc,...
103    -device floppy,unit=0,drive=...
104
105and
106::
107
108    -device isa-fdc,...,driveB=...
109
110becomes
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
119Drives with interface types other than ``if=none`` are for onboard
120devices.  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
126This option was undocumented and not used in the field.
127Use `-device usb-ccid`` instead.
128
129RISC-V firmware not booted by default (removed in 5.1)
130''''''''''''''''''''''''''''''''''''''''''''''''''''''
131
132QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default``
133for the RISC-V ``virt`` machine and ``sifive_u`` machine.
134
135QEMU Machine Protocol (QMP) commands
136------------------------------------
137
138``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2.0)
139''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
140
141The "autoload" parameter has been ignored since 2.12.0. All bitmaps
142are automatically loaded from qcow2 images.
143
144``cpu-add`` (removed in 5.2)
145''''''''''''''''''''''''''''
146
147Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
148documentation of ``query-hotpluggable-cpus`` for additional details.
149
150``change`` (removed in 6.0)
151'''''''''''''''''''''''''''
152
153Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
154
155``query-events`` (removed in 6.0)
156'''''''''''''''''''''''''''''''''
157
158The ``query-events`` command has been superseded by the more powerful
159and accurate ``query-qmp-schema`` command.
160
161``migrate_set_cache_size`` and ``query-migrate-cache-size`` (removed in 6.0)
162''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
163
164Use ``migrate_set_parameter`` and ``info migrate_parameters`` instead.
165
166``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
167'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
168
169Use ``migrate_set_parameter`` instead.
170
171``query-cpus`` (removed in 6.0)
172'''''''''''''''''''''''''''''''
173
174The ``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
179The ``arch`` output member of the ``query-cpus-fast`` command is
180replaced by the ``target`` output member.
181
182chardev client socket with ``wait`` option (removed in 6.0)
183'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
184
185Character devices creating sockets in client mode should not specify
186the '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
191Removed with no replacement.
192
193``query-block`` result ``inserted.encryption_key_missing`` (removed in 6.0)
194'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
195
196Removed with no replacement.
197
198``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (removed in 6.0)
199'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
200
201The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
202these 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
208The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
209the query-block command is itself now removed. The ``dirty-bitmaps``
210field of the ``BlockDeviceInfo`` struct should be used instead, which is the
211type of the ``inserted`` field in query-block replies, as well as the
212type of array items in query-named-block-nodes.
213
214``object-add`` option ``props`` (removed in 6.0)
215''''''''''''''''''''''''''''''''''''''''''''''''
216
217Specify the properties for the object as top-level arguments instead.
218
219Human Monitor Protocol (HMP) commands
220-------------------------------------
221
222The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
223'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
224
225The ``[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
231Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
232documentation of ``query-hotpluggable-cpus`` for additional details.
233
234``change vnc TARGET`` (removed in 6.0)
235''''''''''''''''''''''''''''''''''''''
236
237No replacement.  The ``change vnc password`` and ``change DEVICE MEDIUM``
238commands are not affected.
239
240``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (removed in 6.0)
241'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
242
243The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
244``acl_remove`` commands were removed with no replacement. Authorization
245for 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
250Use ``migrate-set-parameters`` and ``info migrate-parameters`` instead.
251
252``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0)
253'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
254
255Use ``migrate-set-parameters`` instead.
256
257``info cpustats`` (removed in 6.1)
258''''''''''''''''''''''''''''''''''
259
260This command didn't produce any output already. Removed with no replacement.
261
262Guest Emulator ISAs
263-------------------
264
265RISC-V ISA privilege specification version 1.09.1 (removed in 5.1)
266''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
267
268The RISC-V ISA privilege specification version 1.09.1 has been removed.
269QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
270should be used instead of the 1.09.1 version.
271
272System emulator CPUS
273--------------------
274
275KVM guest support on 32-bit Arm hosts (removed in 5.2)
276''''''''''''''''''''''''''''''''''''''''''''''''''''''
277
278The Linux kernel has dropped support for allowing 32-bit Arm systems
279to host KVM guests as of the 5.7 kernel. Accordingly, QEMU is deprecating
280its support for this configuration and will remove it in a future version.
281Running 32-bit guests on a 64-bit Arm host remains supported.
282
283RISC-V ISA Specific CPUs (removed in 5.1)
284'''''''''''''''''''''''''''''''''''''''''
285
286The RISC-V cpus with the ISA version in the CPU name have been removed. The
287four 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``
289option when using the ``rv32`` or ``rv64`` CPUs.
290
291RISC-V no MMU CPUs (removed in 5.1)
292'''''''''''''''''''''''''''''''''''
293
294The 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
296via 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
301The ``max-cpu-compat`` property of the ``pseries`` machine type should be used
302instead.
303
304``moxie`` CPU (removed in 6.1)
305''''''''''''''''''''''''''''''
306
307Nobody was using this CPU emulation in QEMU, and there were no test images
308available to make sure that the code is still working, so it has been removed
309without replacement.
310
311``lm32`` CPUs (removed in 6.1.0)
312''''''''''''''''''''''''''''''''
313
314The only public user of this architecture was the milkymist project,
315which has been dead for years; there was never an upstream Linux
316port.  Removed without replacement.
317
318``unicore32`` CPUs (since 6.1.0)
319''''''''''''''''''''''''''''''''
320
321Support for this CPU was removed from the upstream Linux kernel, and
322there is no available upstream toolchain to build binaries for it.
323Removed without replacement.
324
325System emulator machines
326------------------------
327
328``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
329'''''''''''''''''''''''''''''''''''''''''''''''''''''
330
331The version specific Spike machines have been removed in favour of the
332generic ``spike`` machine. If you need to specify an older version of the RISC-V
333spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument.
334
335mips ``r4k`` platform (removed in 5.2)
336''''''''''''''''''''''''''''''''''''''
337
338This machine type was very old and unmaintained. Users should use the ``malta``
339machine type instead.
340
341mips ``fulong2e`` machine alias (removed in 6.0)
342''''''''''''''''''''''''''''''''''''''''''''''''
343
344This 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
349These machine types were very old and likely could not be used for live
350migration from old QEMU versions anymore. Use a newer machine type instead.
351
352
353linux-user mode CPUs
354--------------------
355
356``tilegx`` CPUs (removed in 6.0)
357''''''''''''''''''''''''''''''''
358
359The ``tilegx`` guest CPU support has been removed without replacement. It was
360only implemented in linux-user mode, but support for this CPU was removed from
361the upstream Linux kernel in 2018, and it has also been dropped from glibc, so
362there is no new Linux development taking place with this architecture. For
363running the old binaries, you can use older versions of QEMU.
364
365System emulator devices
366-----------------------
367
368``ide-drive`` (removed in 6.0)
369''''''''''''''''''''''''''''''
370
371The '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
377The '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
380Related binaries
381----------------
382
383``qemu-nbd --partition`` (removed in 5.0)
384'''''''''''''''''''''''''''''''''''''''''
385
386The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
387could only handle MBR partitions, and never correctly handled logical
388partitions beyond partition 5.  Exporting a partition can still be
389done by utilizing the ``--image-opts`` option with a raw blockdev
390using the ``offset`` and ``size`` parameters layered on top of
391any other existing blockdev. For example, if partition 1 is 100MiB
392long starting at 1MiB, the old command::
393
394  qemu-nbd -t -P 1 -f qcow2 file.qcow2
395
396can 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
403All options specified in ``-o`` are image creation options, so
404they 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
410When 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
412proceed with the image creation if an explicit size was provided.
413However, as the ``-u`` option exists for this purpose, it is safer to
414enforce that any failure to open the backing image (including if the
415backing file is missing or an incorrect format was specified) is an
416error when ``-u`` is not used.
417
418Command line options
419--------------------
420
421``-smp`` (invalid topologies) (removed 5.2)
422'''''''''''''''''''''''''''''''''''''''''''
423
424CPU topology properties should describe whole machine topology including
425possible CPUs.
426
427However, historically it was possible to start QEMU with an incorrect topology
428where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
429which could lead to an incorrect topology enumeration by the guest.
430Support for invalid topologies is removed, the user must ensure
431topologies 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
437Splitting RAM by default between NUMA nodes had the same issues as ``mem``
438parameter with the difference that the role of the user plays QEMU using
439implicit generic or board specific splitting rule.
440Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
441it's supported by used machine type) to define mapping explicitly instead.
442Users of existing VMs, wishing to preserve the same RAM distribution, should
443configure it explicitly using ``-numa node,memdev`` options. Current RAM
444distribution can be retrieved using HMP command ``info numa`` and if separate
445memory devices (pc|nv-dimm) are present use ``info memory-device`` and subtract
446device memory from output of ``info numa``.
447
448``-numa node,mem=``\ *size* (removed in 5.1)
449''''''''''''''''''''''''''''''''''''''''''''
450
451The parameter ``mem`` of ``-numa node`` was used to assign a part of
452guest RAM to a NUMA node. But when using it, it's impossible to manage a specified
453RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
454so the guest ends up with the fake NUMA configuration with suboptiomal performance.
455However since 2014 there is an alternative way to assign RAM to a NUMA node
456using parameter ``memdev``, which does the same as ``mem`` and adds
457means to actually manage node RAM on the host side. Use parameter ``memdev``
458with *memory-backend-ram* backend as replacement for parameter ``mem``
459to achieve the same fake NUMA effect or a properly configured
460*memory-backend-file* backend to actually benefit from NUMA configuration.
461New machine versions (since 5.1) will not accept the option but it will still
462work with old machine types. User can check the QAPI schema to see if the legacy
463option is supported by looking at MachineInfo::numa-mem-supported property.
464
465``-mem-path`` fallback to RAM (removed in 5.0)
466''''''''''''''''''''''''''''''''''''''''''''''
467
468If guest RAM allocation from file pointed by ``mem-path`` failed,
469QEMU was falling back to allocating from RAM, which might have resulted
470in unpredictable behavior since the backing file specified by the user
471as ignored. Currently, users are responsible for making sure the backing storage
472specified 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
478CPU topology properties should describe whole machine topology including
479possible CPUs.
480
481However, historically it was possible to start QEMU with an incorrect topology
482where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
483which could lead to an incorrect topology enumeration by the guest.
484Support for invalid topologies is removed, the user must ensure
485topologies 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
491The ``enforce-config-section`` property was replaced by the
492``-global migration.send-configuration={on|off}`` option.
493
494qemu-img amend to adjust backing file (removed in 6.1)
495''''''''''''''''''''''''''''''''''''''''''''''''''''''
496
497The use of ``qemu-img amend`` to modify the name or format of a qcow2
498backing image was never fully documented or tested, and interferes
499with other amend operations that need access to the original backing
500image (such as deciding whether a v3 zero cluster may be left
501unallocated when converting to a v2 image).  Any changes to the
502backing chain should be performed with ``qemu-img rebase -u`` either
503before or after the remaining changes being performed by amend, as
504appropriate.
505
506qemu-img backing file without format (removed in 6.1)
507'''''''''''''''''''''''''''''''''''''''''''''''''''''
508
509The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img
510convert`` to create or modify an image that depends on a backing file
511now requires that an explicit backing format be provided.  This is
512for safety: if QEMU probes a different format than what you thought,
513the data presented to the guest will be corrupt; similarly, presenting
514a raw image to a guest allows a potential security exploit if a future
515probe sees a non-raw image based on guest writes.
516
517To avoid creating unsafe backing chains, you must pass ``-o
518backing_fmt=`` (or the shorthand ``-F`` during create) to specify the
519intended backing format.  You may use ``qemu-img rebase -u`` to
520retroactively add a backing format to an existing image.  However, be
521aware that there are already potential security risks to blindly using
522``qemu-img info`` to probe the format of an untrusted backing image,
523when deciding what format to add into an existing image.
524
525Block devices
526-------------
527
528VXHS backend (removed in 5.1)
529'''''''''''''''''''''''''''''
530
531The VXHS code did not compile since v2.12.0. It was removed in 5.1.
532
533``sheepdog`` driver (removed in 6.0)
534''''''''''''''''''''''''''''''''''''
535
536The corresponding upstream server project is no longer maintained.
537Users are recommended to switch to an alternative distributed block
538device driver such as RBD.
539