4 In general features are intended to be supported indefinitely once
5 introduced into QEMU. In the event that a feature needs to be removed,
6 it will be listed in this section. The feature will remain functional
7 for 2 releases prior to actual removal. Deprecated features may also
8 generate warnings on the console when QEMU starts up, or if activated
9 via a monitor command, however, this is not a mandatory requirement.
11 Prior to the 2.10.0 release there was no official policy on how
12 long features would be deprecated prior to their removal, nor
13 any documented list of which features were deprecated. Thus
14 any features deprecated prior to 2.10.0 will be treated as if
15 they were first deprecated in the 2.10.0 release.
17 What follows is a list of all features currently marked as
20 System emulator command line arguments
21 --------------------------------------
23 ``-machine enforce-config-section=on|off`` (since 3.1)
24 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
26 The ``enforce-config-section`` parameter is replaced by the
27 ``-global migration.send-configuration={on|off}`` option.
29 ``-no-kvm`` (since 1.3.0)
30 '''''''''''''''''''''''''
32 The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
34 ``-usbdevice`` (since 2.10.0)
35 '''''''''''''''''''''''''''''
37 The ``-usbdevice DEV`` argument is now a synonym for setting
38 the ``-device usb-DEV`` argument instead. The deprecated syntax
39 would automatically enable USB support on the machine type.
40 If using the new syntax, USB support must be explicitly
41 enabled via the ``-machine usb=on`` argument.
43 ``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
44 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
46 The 'file' driver for drives is no longer appropriate for character or host
47 devices and will only accept regular files (S_IFREG). The correct driver
48 for these file types is 'host_cdrom' or 'host_device' as appropriate.
50 ``-smp`` (invalid topologies) (since 3.1)
51 '''''''''''''''''''''''''''''''''''''''''
53 CPU topology properties should describe whole machine topology including
56 However, historically it was possible to start QEMU with an incorrect topology
57 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
58 which could lead to an incorrect topology enumeration by the guest.
59 Support for invalid topologies will be removed, the user must ensure
60 topologies described with -smp include all possible cpus, i.e.
61 *sockets* * *cores* * *threads* = *maxcpus*.
63 ``-vnc acl`` (since 4.0.0)
64 ''''''''''''''''''''''''''
66 The ``acl`` option to the ``-vnc`` argument has been replaced
67 by the ``tls-authz`` and ``sasl-authz`` options.
69 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
70 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
72 The ``-audiodev`` argument is now the preferred way to specify audio
73 backend settings instead of environment variables. To ease migration to
74 the new format, the ``-audiodev-help`` option can be used to convert
75 the current values of the environment variables to ``-audiodev`` options.
77 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
78 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
80 When not using the deprecated legacy audio config, each sound card
81 should specify an ``audiodev=`` property. Additionally, when using
82 vnc, you should specify an ``audiodev=`` propery if you plan to
83 transmit audio through the VNC protocol.
85 ``-mon ...,control=readline,pretty=on|off`` (since 4.1)
86 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
88 The ``pretty=on|off`` switch has no effect for HMP monitors, but is
89 silently ignored. Using the switch with HMP monitors will become an
92 ``-realtime`` (since 4.1)
93 '''''''''''''''''''''''''
95 The ``-realtime mlock=on|off`` argument has been replaced by the
96 ``-overcommit mem-lock=on|off`` argument.
98 ``-numa`` node (without memory specified) (since 4.1)
99 '''''''''''''''''''''''''''''''''''''''''''''''''''''
101 Splitting RAM by default between NUMA nodes has the same issues as ``mem``
102 parameter described above with the difference that the role of the user plays
103 QEMU using implicit generic or board specific splitting rule.
104 Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
105 it's supported by used machine type) to define mapping explictly instead.
107 ``-mem-path`` fallback to RAM (since 4.1)
108 '''''''''''''''''''''''''''''''''''''''''
110 Currently if guest RAM allocation from file pointed by ``mem-path``
111 fails, QEMU falls back to allocating from RAM, which might result
112 in unpredictable behavior since the backing file specified by the user
113 is ignored. In the future, users will be responsible for making sure
114 the backing storage specified with ``-mem-path`` can actually provide
115 the guest RAM configured with ``-m`` and QEMU will fail to start up if
116 RAM allocation is unsuccessful.
118 RISC-V ``-bios`` (since 5.1)
119 ''''''''''''''''''''''''''''
121 QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
122 RISC-V virt machine and sifive_u machine. QEMU 4.1 had no changes to the
123 default behaviour to avoid breakages.
125 QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default``.
127 QEMU 5.1 has three options:
128 1. ``-bios default`` - This is the current default behavior if no -bios option
129 is included. This option will load the default OpenSBI firmware automatically.
130 The firmware is included with the QEMU release and no user interaction is
131 required. All a user needs to do is specify the kernel they want to boot
132 with the -kernel option
133 2. ``-bios none`` - QEMU will not automatically load any firmware. It is up
134 to the user to load all the images they need.
135 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
137 ``-tb-size`` option (since 5.0)
138 '''''''''''''''''''''''''''''''
140 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
141 block cache, ``-accel tcg,tb-size=``. The new syntax deprecates the
142 previously available ``-tb-size`` option.
144 ``-show-cursor`` option (since 5.0)
145 '''''''''''''''''''''''''''''''''''
147 Use ``-display sdl,show-cursor=on`` or
148 ``-display gtk,show-cursor=on`` instead.
150 ``Configuring floppies with ``-global``
151 '''''''''''''''''''''''''''''''''''''''
153 Use ``-device floppy,...`` instead:
156 -global isa-fdc.driveA=...
157 -global sysbus-fdc.driveA=...
158 -global SUNW,fdtwo.drive=...
163 -device floppy,unit=0,drive=...
168 -global isa-fdc.driveB=...
169 -global sysbus-fdc.driveB=...
174 -device floppy,unit=1,drive=...
176 ``-drive`` with bogus interface type
177 ''''''''''''''''''''''''''''''''''''
179 Drives with interface types other than ``if=none`` are for onboard
180 devices. It is possible to use drives the board doesn't pick up with
181 -device. This usage is now deprecated. Use ``if=none`` instead.
184 QEMU Machine Protocol (QMP) commands
185 ------------------------------------
187 ``change`` (since 2.5.0)
188 ''''''''''''''''''''''''
190 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
192 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0)
193 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
195 Use argument ``id`` instead.
197 ``eject`` argument ``device`` (since 2.8.0)
198 '''''''''''''''''''''''''''''''''''''''''''
200 Use argument ``id`` instead.
202 ``blockdev-change-medium`` argument ``device`` (since 2.8.0)
203 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
205 Use argument ``id`` instead.
207 ``block_set_io_throttle`` argument ``device`` (since 2.8.0)
208 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
210 Use argument ``id`` instead.
212 ``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
213 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
215 Use ``migrate-set-parameters`` instead.
217 ``query-named-block-nodes`` result ``encryption_key_missing`` (since 2.10.0)
218 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
222 ``query-block`` result ``inserted.encryption_key_missing`` (since 2.10.0)
223 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
227 ``blockdev-add`` empty string argument ``backing`` (since 2.10.0)
228 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
230 Use argument value ``null`` instead.
232 ``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
233 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
235 Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
237 ``block-commit`` arguments ``base`` and ``top`` (since 3.1.0)
238 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
240 Use arguments ``base-node`` and ``top-node`` instead.
242 ``object-add`` option ``props`` (since 5.0)
243 '''''''''''''''''''''''''''''''''''''''''''
245 Specify the properties for the object as top-level arguments instead.
247 ``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (since 4.0)
248 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
250 The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
251 these commands is deprecated. Two new boolean fields, ``recording`` and
252 ``busy`` effectively replace it.
254 ``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
255 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
257 The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
258 the query-block command is itself now deprecated. The ``dirty-bitmaps``
259 field of the ``BlockDeviceInfo`` struct should be used instead, which is the
260 type of the ``inserted`` field in query-block replies, as well as the
261 type of array items in query-named-block-nodes.
263 Since the ``dirty-bitmaps`` field is optionally present in both the old and
264 new locations, clients must use introspection to learn where to anticipate
265 the field if/when it does appear in command output.
267 ``query-cpus`` (since 2.12.0)
268 '''''''''''''''''''''''''''''
270 The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
272 ``query-cpus-fast`` ``arch`` output member (since 3.0.0)
273 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
275 The ``arch`` output member of the ``query-cpus-fast`` command is
276 replaced by the ``target`` output member.
278 ``cpu-add`` (since 4.0)
279 '''''''''''''''''''''''
281 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
282 documentation of ``query-hotpluggable-cpus`` for additional
285 ``query-events`` (since 4.0)
286 ''''''''''''''''''''''''''''
288 The ``query-events`` command has been superseded by the more powerful
289 and accurate ``query-qmp-schema`` command.
291 chardev client socket with ``wait`` option (since 4.0)
292 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
294 Character devices creating sockets in client mode should not specify
295 the 'wait' field, which is only applicable to sockets in server mode
297 Human Monitor Protocol (HMP) commands
298 -------------------------------------
300 ``cpu-add`` (since 4.0)
301 '''''''''''''''''''''''
303 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
304 documentation of ``query-hotpluggable-cpus`` for additional details.
306 ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
307 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
309 The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
310 ``acl_remove`` commands are deprecated with no replacement. Authorization
311 for VNC should be performed using the pluggable QAuthZ objects.
316 ``compat`` property of server class POWER CPUs (since 5.0)
317 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
319 The ``compat`` property used to set backwards compatibility modes for
320 the processor has been deprecated. The ``max-cpu-compat`` property of
321 the ``pseries`` machine type should be used instead.
323 KVM guest support on 32-bit Arm hosts (since 5.0)
324 '''''''''''''''''''''''''''''''''''''''''''''''''
326 The Linux kernel has dropped support for allowing 32-bit Arm systems
327 to host KVM guests as of the 5.7 kernel. Accordingly, QEMU is deprecating
328 its support for this configuration and will remove it in a future version.
329 Running 32-bit guests on a 64-bit Arm host remains supported.
331 System emulator devices
332 -----------------------
334 ``ide-drive`` (since 4.2)
335 '''''''''''''''''''''''''
337 The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
338 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
340 ``scsi-disk`` (since 4.2)
341 '''''''''''''''''''''''''
343 The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
344 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
346 System emulator machines
347 ------------------------
349 mips ``r4k`` platform (since 5.0)
350 '''''''''''''''''''''''''''''''''
352 This machine type is very old and unmaintained. Users should use the ``malta``
353 machine type instead.
355 mips ``fulong2e`` machine (since 5.1)
356 '''''''''''''''''''''''''''''''''''''
358 This machine has been renamed ``fuloong2e``.
360 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
361 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
363 These machine types are very old and likely can not be used for live migration
364 from old QEMU versions anymore. A newer machine type should be used instead.
369 Emulated device options
370 '''''''''''''''''''''''
372 ``-device virtio-blk,scsi=on|off`` (since 5.0.0)
373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
375 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
376 and later do not support it because the virtio-scsi device was introduced for
377 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
379 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
385 ``"backing": ""`` (since 2.12.0)
386 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
388 In order to prevent QEMU from automatically opening an image's backing
389 chain, use ``"backing": null`` instead.
391 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
392 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
394 Options for ``rbd`` should be specified according to its runtime options,
395 like other block drivers. Legacy parsing of keyvalue pair encoded
396 filenames is useful to open images with the old format for backing files;
397 These image files should be updated to use the current format.
399 Example of legacy encoding::
401 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
403 The above, converted to the current supported format::
405 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
410 ``tilegx`` CPUs (since 5.1.0)
411 '''''''''''''''''''''''''''''
413 The ``tilegx`` guest CPU support (which was only implemented in
414 linux-user mode) is deprecated and will be removed in a future version
415 of QEMU. Support for this CPU was removed from the upstream Linux
416 kernel in 2018, and has also been dropped from glibc.
421 ``qemu-img convert -n -o`` (since 4.2.0)
422 ''''''''''''''''''''''''''''''''''''''''
424 All options specified in ``-o`` are image creation options, so
425 they have no effect when used with ``-n`` to skip image creation.
426 Silently ignored options can be confusing, so this combination of
427 options will be made an error in future versions.
429 Backwards compatibility
430 -----------------------
432 Runnability guarantee of CPU models (since 4.1.0)
433 '''''''''''''''''''''''''''''''''''''''''''''''''
435 Previous versions of QEMU never changed existing CPU models in
436 ways that introduced additional host software or hardware
437 requirements to the VM. This allowed management software to
438 safely change the machine type of an existing VM without
439 introducing new requirements ("runnability guarantee"). This
440 prevented CPU models from being updated to include CPU
441 vulnerability mitigations, leaving guests vulnerable in the
442 default configuration.
444 The CPU model runnability guarantee won't apply anymore to
445 existing CPU models. Management software that needs runnability
446 guarantees must resolve the CPU model aliases using te
447 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
450 While those guarantees are kept, the return value of
451 ``query-cpu-definitions`` will have existing CPU model aliases
452 point to a version that doesn't break runnability guarantees
453 (specifically, version 1 of those CPU models). In future QEMU
454 versions, aliases will point to newer CPU model versions
455 depending on the machine type, so management software must
456 resolve CPU model aliases before starting a virtual machine.
459 Recently removed features
460 =========================
462 What follows is a record of recently removed, formerly deprecated
463 features that serves as a record for users who have encountered
464 trouble after a recent upgrade.
466 System emulator command line arguments
467 --------------------------------------
469 ``-net ...,name=``\ *name* (removed in 5.1)
470 '''''''''''''''''''''''''''''''''''''''''''
472 The ``name`` parameter of the ``-net`` option was a synonym
473 for the ``id`` parameter, which should now be used instead.
475 QEMU Machine Protocol (QMP) commands
476 ------------------------------------
478 ``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
479 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
481 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
482 are automatically loaded from qcow2 images.
484 Human Monitor Protocol (HMP) commands
485 -------------------------------------
487 The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
488 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
490 The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
491 'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
496 RISC-V ISA privledge specification version 1.09.1 (removed in 5.1)
497 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
499 The RISC-V ISA privledge specification version 1.09.1 has been removed.
500 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
501 should be used instead of the 1.09.1 version.
506 RISC-V ISA Specific CPUs (removed in 5.1)
507 '''''''''''''''''''''''''''''''''''''''''
509 The RISC-V cpus with the ISA version in the CPU name have been removed. The
510 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
511 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
512 option when using the ``rv32`` or ``rv64`` CPUs.
514 RISC-V no MMU CPUs (removed in 5.1)
515 '''''''''''''''''''''''''''''''''''
517 The RISC-V no MMU cpus have been removed. The two CPUs: ``rv32imacu-nommu`` and
518 ``rv64imacu-nommu`` can no longer be used. Instead the MMU status can be specified
519 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
521 System emulator machines
522 ------------------------
524 ``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1)
525 '''''''''''''''''''''''''''''''''''''''''''''''''''''
527 The version specific Spike machines have been removed in favour of the
528 generic ``spike`` machine. If you need to specify an older version of the RISC-V
529 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument.
534 ``qemu-nbd --partition`` (removed in 5.0.0)
535 '''''''''''''''''''''''''''''''''''''''''''
537 The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
538 could only handle MBR partitions, and never correctly handled logical
539 partitions beyond partition 5. Exporting a partition can still be
540 done by utilizing the ``--image-opts`` option with a raw blockdev
541 using the ``offset`` and ``size`` parameters layered on top of
542 any other existing blockdev. For example, if partition 1 is 100MiB
543 long starting at 1MiB, the old command::
545 qemu-nbd -t -P 1 -f qcow2 file.qcow2
547 can be rewritten as::
549 qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
554 ``-numa node,mem=``\ *size* (removed in 5.1)
555 ''''''''''''''''''''''''''''''''''''''''''''
557 The parameter ``mem`` of ``-numa node`` was used to assign a part of
558 guest RAM to a NUMA node. But when using it, it's impossible to manage a specified
559 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
560 so the guest ends up with the fake NUMA configuration with suboptiomal performance.
561 However since 2014 there is an alternative way to assign RAM to a NUMA node
562 using parameter ``memdev``, which does the same as ``mem`` and adds
563 means to actually manage node RAM on the host side. Use parameter ``memdev``
564 with *memory-backend-ram* backend as replacement for parameter ``mem``
565 to achieve the same fake NUMA effect or a properly configured
566 *memory-backend-file* backend to actually benefit from NUMA configuration.
567 New machine versions (since 5.1) will not accept the option but it will still
568 work with old machine types. User can check the QAPI schema to see if the legacy
569 option is supported by looking at MachineInfo::numa-mem-supported property.