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 ``-no-quit`` (since 6.1)
138 ''''''''''''''''''''''''
140 The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which
141 should be used instead.
143 ``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2)
144 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
146 Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead.
148 ``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2)
149 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
151 Use ``-display sdl,grab-mod=rctrl`` instead.
156 Use ``-display sdl`` instead.
158 ``-curses`` (since 6.2)
159 '''''''''''''''''''''''
161 Use ``-display curses`` instead.
163 ``-watchdog`` (since 6.2)
164 '''''''''''''''''''''''''
166 Use ``-device`` instead.
168 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
169 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
171 Specified CPU topology parameters must be greater than zero.
173 In the SMP configuration, users should either provide a CPU topology
174 parameter with a reasonable value (greater than zero) or just omit it
175 and QEMU will compute the missing value.
177 However, historically it was implicitly allowed for users to provide
178 a parameter with zero value, which is meaningless and could also possibly
179 cause unexpected results in the -smp parsing. So support for this kind of
180 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
181 be removed in the near future, users have to ensure that all the topology
182 members described with -smp are greater than zero.
184 Plugin argument passing through ``arg=<string>`` (since 6.1)
185 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
187 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
188 command-line less readable, especially when the argument itself consist of a
189 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
190 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
191 as short-form boolean values, and passed to plugins as ``arg_name=on``.
192 However, short-form booleans are deprecated and full explicit ``arg_name=on``
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
256 MIPS ``Trap-and-Emul`` KVM support (since 6.0)
257 ''''''''''''''''''''''''''''''''''''''''''''''
259 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
260 from Linux upstream kernel, declare it deprecated.
265 ``Icelake-Client`` CPU Model (since 5.2)
266 ''''''''''''''''''''''''''''''''''''''''
268 ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
271 MIPS ``I7200`` CPU Model (since 5.2)
272 ''''''''''''''''''''''''''''''''''''
274 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
275 (the ISA has never been upstreamed to a compiler toolchain). Therefore
276 this CPU is also deprecated.
279 QEMU API (QAPI) events
280 ----------------------
282 ``MEM_UNPLUG_ERROR`` (since 6.2)
283 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
285 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
288 System emulator machines
289 ------------------------
291 Aspeed ``swift-bmc`` machine (since 6.1)
292 ''''''''''''''''''''''''''''''''''''''''
294 This machine is deprecated because we have enough AST2500 based OpenPOWER
295 machines. It can be easily replaced by the ``witherspoon-bmc`` or the
296 ``romulus-bmc`` machines.
301 Using non-persistent backing file with pmem=on (since 6.1)
302 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
304 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
305 device. However enabling ``memory-backend-file.pmem`` option, when backing file
306 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
307 of persistent memory, is not safe and may lead to data loss or corruption in case
311 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
312 (without persistence guaranties) with backing file on non DAX storage
313 - move backing file to NVDIMM storage and keep ``pmem=on``
314 (to have NVDIMM with persistence guaranties).
319 Emulated device options
320 '''''''''''''''''''''''
322 ``-device virtio-blk,scsi=on|off`` (since 5.0)
323 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
325 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
326 and later do not support it because the virtio-scsi device was introduced for
327 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
329 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
332 ``-device sga`` (since 6.2)
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
335 The ``sga`` device loads an option ROM for x86 targets which enables
336 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
337 contains native support for this feature and thus use of the option
338 ROM approach is obsolete. The native SeaBIOS support can be activated
339 by using ``-machine graphics=off``.
345 ``"backing": ""`` (since 2.12)
346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
348 In order to prevent QEMU from automatically opening an image's backing
349 chain, use ``"backing": null`` instead.
351 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
352 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
354 Options for ``rbd`` should be specified according to its runtime options,
355 like other block drivers. Legacy parsing of keyvalue pair encoded
356 filenames is useful to open images with the old format for backing files;
357 These image files should be updated to use the current format.
359 Example of legacy encoding::
361 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
363 The above, converted to the current supported format::
365 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
370 ``ppc64abi32`` CPUs (since 5.2)
371 '''''''''''''''''''''''''''''''
373 The ``ppc64abi32`` architecture has a number of issues which regularly
374 trip up our CI testing and is suspected to be quite broken. For that
375 reason the maintainers strongly suspect no one actually uses it.
377 MIPS ``I7200`` CPU (since 5.2)
378 ''''''''''''''''''''''''''''''
380 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
381 (the ISA has never been upstreamed to a compiler toolchain). Therefore
382 this CPU is also deprecated.
384 Backwards compatibility
385 -----------------------
387 Runnability guarantee of CPU models (since 4.1)
388 '''''''''''''''''''''''''''''''''''''''''''''''
390 Previous versions of QEMU never changed existing CPU models in
391 ways that introduced additional host software or hardware
392 requirements to the VM. This allowed management software to
393 safely change the machine type of an existing VM without
394 introducing new requirements ("runnability guarantee"). This
395 prevented CPU models from being updated to include CPU
396 vulnerability mitigations, leaving guests vulnerable in the
397 default configuration.
399 The CPU model runnability guarantee won't apply anymore to
400 existing CPU models. Management software that needs runnability
401 guarantees must resolve the CPU model aliases using the
402 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
405 While those guarantees are kept, the return value of
406 ``query-cpu-definitions`` will have existing CPU model aliases
407 point to a version that doesn't break runnability guarantees
408 (specifically, version 1 of those CPU models). In future QEMU
409 versions, aliases will point to newer CPU model versions
410 depending on the machine type, so management software must
411 resolve CPU model aliases before starting a virtual machine.
419 The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
420 As it is hard to generate binaries for it, declare it deprecated.