1 .. _Deprecated features:
6 In general features are intended to be supported indefinitely once
7 introduced into QEMU. In the event that a feature needs to be removed,
8 it will be listed in this section. The feature will remain functional for the
9 release in which it was deprecated and one further release. After these two
10 releases, the feature is liable to be removed. Deprecated features may also
11 generate warnings on the console when QEMU starts up, or if activated via a
12 monitor command, however, this is not a mandatory requirement.
14 Prior to the 2.10.0 release there was no official policy on how
15 long features would be deprecated prior to their removal, nor
16 any documented list of which features were deprecated. Thus
17 any features deprecated prior to 2.10.0 will be treated as if
18 they were first deprecated in the 2.10.0 release.
20 What follows is a list of all features currently marked as
23 System emulator command line arguments
24 --------------------------------------
26 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
27 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
29 The ``-audiodev`` argument is now the preferred way to specify audio
30 backend settings instead of environment variables. To ease migration to
31 the new format, the ``-audiodev-help`` option can be used to convert
32 the current values of the environment variables to ``-audiodev`` options.
34 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
35 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
37 When not using the deprecated legacy audio config, each sound card
38 should specify an ``audiodev=`` property. Additionally, when using
39 vnc, you should specify an ``audiodev=`` property if you plan to
40 transmit audio through the VNC protocol.
42 Creating sound card devices using ``-soundhw`` (since 5.1)
43 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
45 Sound card devices should be created using ``-device`` instead. The
46 names are the same for most devices. The exceptions are ``hda`` which
47 needs two devices (``-device intel-hda -device hda-duplex``) and
48 ``pcspk`` which can be activated using ``-machine
49 pcspk-audiodev=<name>``.
51 ``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0)
52 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
54 ``tty`` and ``parport`` are aliases that will be removed. Instead, the
55 actual backend names ``serial`` and ``parallel`` should be used.
57 Short-form boolean options (since 6.0)
58 ''''''''''''''''''''''''''''''''''''''
60 Boolean options such as ``share=on``/``share=off`` could be written
61 in short form as ``share`` and ``noshare``. This is now deprecated
62 and will cause a warning.
64 ``delay`` option for socket character devices (since 6.0)
65 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
67 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
68 rather than ``delay=off``.
70 ``--enable-fips`` (since 6.0)
71 '''''''''''''''''''''''''''''
73 This option restricts usage of certain cryptographic algorithms when
74 the host is operating in FIPS mode.
76 If FIPS compliance is required, QEMU should be built with the ``libgcrypt``
77 library enabled as a cryptography provider.
79 Neither the ``nettle`` library, or the built-in cryptography provider are
80 supported on FIPS enabled hosts.
82 ``-writeconfig`` (since 6.0)
83 '''''''''''''''''''''''''''''
85 The ``-writeconfig`` option is not able to serialize the entire contents
86 of the QEMU command line. It is thus considered a failed experiment
87 and deprecated, with no current replacement.
89 Userspace local APIC with KVM (x86, since 6.0)
90 ''''''''''''''''''''''''''''''''''''''''''''''
92 Using ``-M kernel-irqchip=off`` with x86 machine types that include a local
93 APIC is deprecated. The ``split`` setting is supported, as is using
94 ``-M kernel-irqchip=off`` with the ISA PC machine type.
96 hexadecimal sizes with scaling multipliers (since 6.0)
97 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
99 Input parameters that take a size value should only use a size suffix
100 (such as 'k' or 'M') when the base is written in decimal, and not when
101 the value is hexadecimal. That is, '0x20M' is deprecated, and should
102 be written either as '32M' or as '0x2000000'.
104 ``-spice password=string`` (since 6.0)
105 ''''''''''''''''''''''''''''''''''''''
107 This option is insecure because the SPICE password remains visible in
108 the process listing. This is replaced by the new ``password-secret``
109 option which lets the password be securely provided on the command
110 line using a ``secret`` object instance.
112 ``opened`` property of ``rng-*`` objects (since 6.0)
113 ''''''''''''''''''''''''''''''''''''''''''''''''''''
115 The only effect of specifying ``opened=on`` in the command line or QMP
116 ``object-add`` is that the device is opened immediately, possibly before all
117 other options have been processed. This will either have no effect (if
118 ``opened`` was the last option) or cause errors. The property is therefore
119 useless and should not be specified.
121 ``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0)
122 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
124 The only effect of specifying ``loaded=on`` in the command line or QMP
125 ``object-add`` is that the secret is loaded immediately, possibly before all
126 other options have been processed. This will either have no effect (if
127 ``loaded`` was the last option) or cause options to be effectively ignored as
128 if they were not given. The property is therefore useless and should not be
131 ``-display sdl,window_close=...`` (since 6.1)
132 '''''''''''''''''''''''''''''''''''''''''''''
134 Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
135 an underscore between "window" and "close").
137 ``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2)
138 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
140 Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead.
142 ``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2)
143 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
145 Use ``-display sdl,grab-mod=rctrl`` instead.
150 Use ``-display sdl`` instead.
152 ``-curses`` (since 6.2)
153 '''''''''''''''''''''''
155 Use ``-display curses`` instead.
157 ``-watchdog`` (since 6.2)
158 '''''''''''''''''''''''''
160 Use ``-device`` instead.
162 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
163 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
165 Specified CPU topology parameters must be greater than zero.
167 In the SMP configuration, users should either provide a CPU topology
168 parameter with a reasonable value (greater than zero) or just omit it
169 and QEMU will compute the missing value.
171 However, historically it was implicitly allowed for users to provide
172 a parameter with zero value, which is meaningless and could also possibly
173 cause unexpected results in the -smp parsing. So support for this kind of
174 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
175 be removed in the near future, users have to ensure that all the topology
176 members described with -smp are greater than zero.
178 Plugin argument passing through ``arg=<string>`` (since 6.1)
179 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
181 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
182 command-line less readable, especially when the argument itself consist of a
183 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
184 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
185 as short-form boolean values, and passed to plugins as ``arg_name=on``.
186 However, short-form booleans are deprecated and full explicit ``arg_name=on``
189 ``-drive if=none`` for the sifive_u OTP device (since 6.2)
190 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
192 Using ``-drive if=none`` to configure the OTP device of the sifive_u
193 RISC-V machine is deprecated. Use ``-drive if=pflash`` instead.
196 QEMU Machine Protocol (QMP) commands
197 ------------------------------------
199 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
200 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
202 Use argument ``id`` instead.
204 ``eject`` argument ``device`` (since 2.8)
205 '''''''''''''''''''''''''''''''''''''''''
207 Use argument ``id`` instead.
209 ``blockdev-change-medium`` argument ``device`` (since 2.8)
210 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
212 Use argument ``id`` instead.
214 ``block_set_io_throttle`` argument ``device`` (since 2.8)
215 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
217 Use argument ``id`` instead.
219 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
220 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
222 Use argument value ``null`` instead.
224 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
225 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
227 Use arguments ``base-node`` and ``top-node`` instead.
229 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
230 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
232 Use the more generic commands ``block-export-add`` and ``block-export-del``
233 instead. As part of this deprecation, where ``nbd-server-add`` used a
234 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
236 ``query-qmp-schema`` return value member ``values`` (since 6.2)
237 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
239 Member ``values`` in return value elements with meta-type ``enum`` is
240 deprecated. Use ``members`` instead.
242 ``drive-backup`` (since 6.2)
243 ''''''''''''''''''''''''''''
245 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
246 This change primarily separates the creation/opening process of the backup
247 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
248 same arguments as ``drive-backup``, except the ``format`` and ``mode``
249 options are removed in favor of using explicit ``blockdev-create`` and
250 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
253 Incorrectly typed ``device_add`` arguments (since 6.2)
254 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
256 Due to shortcomings in the internal implementation of ``device_add``, QEMU
257 incorrectly accepts certain invalid arguments: Any object or list arguments are
258 silently ignored. Other argument types are not checked, but an implicit
259 conversion happens, so that e.g. string values can be assigned to integer
260 device properties or vice versa.
262 This is a bug in QEMU that will be fixed in the future so that previously
263 accepted incorrect commands will return an error. Users should make sure that
264 all arguments passed to ``device_add`` are consistent with the documented
267 ``query-sgx`` return value member ``section-size`` (since 7.0)
268 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
270 Member ``section-size`` in return value elements with meta-type ``uint64`` is
271 deprecated. Use ``sections`` instead.
274 ``query-sgx-capabilities`` return value member ``section-size`` (since 7.0)
275 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
277 Member ``section-size`` in return value elements with meta-type ``uint64`` is
278 deprecated. Use ``sections`` instead.
283 MIPS ``Trap-and-Emul`` KVM support (since 6.0)
284 ''''''''''''''''''''''''''''''''''''''''''''''
286 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
287 from Linux upstream kernel, declare it deprecated.
292 ``Icelake-Client`` CPU Model (since 5.2)
293 ''''''''''''''''''''''''''''''''''''''''
295 ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
298 MIPS ``I7200`` CPU Model (since 5.2)
299 ''''''''''''''''''''''''''''''''''''
301 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
302 (the ISA has never been upstreamed to a compiler toolchain). Therefore
303 this CPU is also deprecated.
306 QEMU API (QAPI) events
307 ----------------------
309 ``MEM_UNPLUG_ERROR`` (since 6.2)
310 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
312 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
315 System emulator machines
316 ------------------------
318 PPC 405 ``taihu`` machine (since 7.0)
319 '''''''''''''''''''''''''''''''''''''
321 The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar,
322 except for some external periphery. However, the periphery of the ``taihu``
323 machine is hardly emulated at all (e.g. neither the LCD nor the USB part had
324 been implemented), so there is not much value added by this board. Use the
325 ``ref405ep`` machine instead.
327 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0)
328 '''''''''''''''''''''''''''''''''''''''''''''''''''''
330 These old machine types are quite neglected nowadays and thus might have
331 various pitfalls with regards to live migration. Use a newer machine type
338 Using non-persistent backing file with pmem=on (since 6.1)
339 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
341 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
342 device. However enabling ``memory-backend-file.pmem`` option, when backing file
343 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
344 of persistent memory, is not safe and may lead to data loss or corruption in case
348 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
349 (without persistence guaranties) with backing file on non DAX storage
350 - move backing file to NVDIMM storage and keep ``pmem=on``
351 (to have NVDIMM with persistence guaranties).
356 Emulated device options
357 '''''''''''''''''''''''
359 ``-device virtio-blk,scsi=on|off`` (since 5.0)
360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
362 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
363 and later do not support it because the virtio-scsi device was introduced for
364 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
366 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
369 ``-device sga`` (since 6.2)
370 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
372 The ``sga`` device loads an option ROM for x86 targets which enables
373 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
374 contains native support for this feature and thus use of the option
375 ROM approach is obsolete. The native SeaBIOS support can be activated
376 by using ``-machine graphics=off``.
382 ``"backing": ""`` (since 2.12)
383 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
385 In order to prevent QEMU from automatically opening an image's backing
386 chain, use ``"backing": null`` instead.
388 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
391 Options for ``rbd`` should be specified according to its runtime options,
392 like other block drivers. Legacy parsing of keyvalue pair encoded
393 filenames is useful to open images with the old format for backing files;
394 These image files should be updated to use the current format.
396 Example of legacy encoding::
398 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
400 The above, converted to the current supported format::
402 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
407 MIPS ``I7200`` CPU (since 5.2)
408 ''''''''''''''''''''''''''''''
410 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
411 (the ISA has never been upstreamed to a compiler toolchain). Therefore
412 this CPU is also deprecated.
414 Backwards compatibility
415 -----------------------
417 Runnability guarantee of CPU models (since 4.1)
418 '''''''''''''''''''''''''''''''''''''''''''''''
420 Previous versions of QEMU never changed existing CPU models in
421 ways that introduced additional host software or hardware
422 requirements to the VM. This allowed management software to
423 safely change the machine type of an existing VM without
424 introducing new requirements ("runnability guarantee"). This
425 prevented CPU models from being updated to include CPU
426 vulnerability mitigations, leaving guests vulnerable in the
427 default configuration.
429 The CPU model runnability guarantee won't apply anymore to
430 existing CPU models. Management software that needs runnability
431 guarantees must resolve the CPU model aliases using the
432 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
435 While those guarantees are kept, the return value of
436 ``query-cpu-definitions`` will have existing CPU model aliases
437 point to a version that doesn't break runnability guarantees
438 (specifically, version 1 of those CPU models). In future QEMU
439 versions, aliases will point to newer CPU model versions
440 depending on the machine type, so management software must
441 resolve CPU model aliases before starting a virtual machine.
449 The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
450 As it is hard to generate binaries for it, declare it deprecated.
458 There is a new Rust implementation of ``virtiofsd`` at
459 ``https://gitlab.com/virtio-fs/virtiofsd``;
460 since this is now marked stable, new development should be done on that
461 rather than the existing C version in the QEMU tree.
462 The C version will still accept fixes and patches that
463 are already in development for the moment, but will eventually
464 be deleted from this tree.
465 New deployments should use the Rust version, and existing systems
466 should consider moving to it. The command line and feature set
467 is very close and moving should be simple.