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.
330 Using non-persistent backing file with pmem=on (since 6.1)
331 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
333 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
334 device. However enabling ``memory-backend-file.pmem`` option, when backing file
335 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
336 of persistent memory, is not safe and may lead to data loss or corruption in case
340 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
341 (without persistence guaranties) with backing file on non DAX storage
342 - move backing file to NVDIMM storage and keep ``pmem=on``
343 (to have NVDIMM with persistence guaranties).
348 Emulated device options
349 '''''''''''''''''''''''
351 ``-device virtio-blk,scsi=on|off`` (since 5.0)
352 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
354 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
355 and later do not support it because the virtio-scsi device was introduced for
356 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
358 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
361 ``-device sga`` (since 6.2)
362 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
364 The ``sga`` device loads an option ROM for x86 targets which enables
365 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
366 contains native support for this feature and thus use of the option
367 ROM approach is obsolete. The native SeaBIOS support can be activated
368 by using ``-machine graphics=off``.
374 ``"backing": ""`` (since 2.12)
375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
377 In order to prevent QEMU from automatically opening an image's backing
378 chain, use ``"backing": null`` instead.
380 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383 Options for ``rbd`` should be specified according to its runtime options,
384 like other block drivers. Legacy parsing of keyvalue pair encoded
385 filenames is useful to open images with the old format for backing files;
386 These image files should be updated to use the current format.
388 Example of legacy encoding::
390 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
392 The above, converted to the current supported format::
394 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
399 MIPS ``I7200`` CPU (since 5.2)
400 ''''''''''''''''''''''''''''''
402 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
403 (the ISA has never been upstreamed to a compiler toolchain). Therefore
404 this CPU is also deprecated.
406 Backwards compatibility
407 -----------------------
409 Runnability guarantee of CPU models (since 4.1)
410 '''''''''''''''''''''''''''''''''''''''''''''''
412 Previous versions of QEMU never changed existing CPU models in
413 ways that introduced additional host software or hardware
414 requirements to the VM. This allowed management software to
415 safely change the machine type of an existing VM without
416 introducing new requirements ("runnability guarantee"). This
417 prevented CPU models from being updated to include CPU
418 vulnerability mitigations, leaving guests vulnerable in the
419 default configuration.
421 The CPU model runnability guarantee won't apply anymore to
422 existing CPU models. Management software that needs runnability
423 guarantees must resolve the CPU model aliases using the
424 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
427 While those guarantees are kept, the return value of
428 ``query-cpu-definitions`` will have existing CPU model aliases
429 point to a version that doesn't break runnability guarantees
430 (specifically, version 1 of those CPU models). In future QEMU
431 versions, aliases will point to newer CPU model versions
432 depending on the machine type, so management software must
433 resolve CPU model aliases before starting a virtual machine.
441 The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
442 As it is hard to generate binaries for it, declare it deprecated.
450 There is a new Rust implementation of ``virtiofsd`` at
451 ``https://gitlab.com/virtio-fs/virtiofsd``;
452 since this is now marked stable, new development should be done on that
453 rather than the existing C version in the QEMU tree.
454 The C version will still accept fixes and patches that
455 are already in development for the moment, but will eventually
456 be deleted from this tree.
457 New deployments should use the Rust version, and existing systems
458 should consider moving to it. The command line and feature set
459 is very close and moving should be simple.