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 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
164 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
166 Specified CPU topology parameters must be greater than zero.
168 In the SMP configuration, users should either provide a CPU topology
169 parameter with a reasonable value (greater than zero) or just omit it
170 and QEMU will compute the missing value.
172 However, historically it was implicitly allowed for users to provide
173 a parameter with zero value, which is meaningless and could also possibly
174 cause unexpected results in the -smp parsing. So support for this kind of
175 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
176 be removed in the near future, users have to ensure that all the topology
177 members described with -smp are greater than zero.
179 Plugin argument passing through ``arg=<string>`` (since 6.1)
180 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
182 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
183 command-line less readable, especially when the argument itself consist of a
184 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
185 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
186 as short-form boolean values, and passed to plugins as ``arg_name=on``.
187 However, short-form booleans are deprecated and full explicit ``arg_name=on``
191 QEMU Machine Protocol (QMP) commands
192 ------------------------------------
194 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
195 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
197 Use argument ``id`` instead.
199 ``eject`` argument ``device`` (since 2.8)
200 '''''''''''''''''''''''''''''''''''''''''
202 Use argument ``id`` instead.
204 ``blockdev-change-medium`` argument ``device`` (since 2.8)
205 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
207 Use argument ``id`` instead.
209 ``block_set_io_throttle`` argument ``device`` (since 2.8)
210 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
212 Use argument ``id`` instead.
214 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
215 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
217 Use argument value ``null`` instead.
219 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
220 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
222 Use arguments ``base-node`` and ``top-node`` instead.
224 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
225 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
227 Use the more generic commands ``block-export-add`` and ``block-export-del``
228 instead. As part of this deprecation, where ``nbd-server-add`` used a
229 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
231 ``query-qmp-schema`` return value member ``values`` (since 6.2)
232 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
234 Member ``values`` in return value elements with meta-type ``enum`` is
235 deprecated. Use ``members`` instead.
240 MIPS ``Trap-and-Emul`` KVM support (since 6.0)
241 ''''''''''''''''''''''''''''''''''''''''''''''
243 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
244 from Linux upstream kernel, declare it deprecated.
249 ``Icelake-Client`` CPU Model (since 5.2)
250 ''''''''''''''''''''''''''''''''''''''''
252 ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
255 MIPS ``I7200`` CPU Model (since 5.2)
256 ''''''''''''''''''''''''''''''''''''
258 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
259 (the ISA has never been upstreamed to a compiler toolchain). Therefore
260 this CPU is also deprecated.
263 QEMU API (QAPI) events
264 ----------------------
266 ``MEM_UNPLUG_ERROR`` (since 6.2)
267 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
269 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
272 System emulator machines
273 ------------------------
275 Aspeed ``swift-bmc`` machine (since 6.1)
276 ''''''''''''''''''''''''''''''''''''''''
278 This machine is deprecated because we have enough AST2500 based OpenPOWER
279 machines. It can be easily replaced by the ``witherspoon-bmc`` or the
280 ``romulus-bmc`` machines.
285 Using non-persistent backing file with pmem=on (since 6.1)
286 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
288 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
289 device. However enabling ``memory-backend-file.pmem`` option, when backing file
290 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
291 of persistent memory, is not safe and may lead to data loss or corruption in case
295 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
296 (without persistence guaranties) with backing file on non DAX storage
297 - move backing file to NVDIMM storage and keep ``pmem=on``
298 (to have NVDIMM with persistence guaranties).
303 Emulated device options
304 '''''''''''''''''''''''
306 ``-device virtio-blk,scsi=on|off`` (since 5.0)
307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
310 and later do not support it because the virtio-scsi device was introduced for
311 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
313 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
319 ``"backing": ""`` (since 2.12)
320 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
322 In order to prevent QEMU from automatically opening an image's backing
323 chain, use ``"backing": null`` instead.
325 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
326 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
328 Options for ``rbd`` should be specified according to its runtime options,
329 like other block drivers. Legacy parsing of keyvalue pair encoded
330 filenames is useful to open images with the old format for backing files;
331 These image files should be updated to use the current format.
333 Example of legacy encoding::
335 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
337 The above, converted to the current supported format::
339 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
344 ``ppc64abi32`` CPUs (since 5.2)
345 '''''''''''''''''''''''''''''''
347 The ``ppc64abi32`` architecture has a number of issues which regularly
348 trip up our CI testing and is suspected to be quite broken. For that
349 reason the maintainers strongly suspect no one actually uses it.
351 MIPS ``I7200`` CPU (since 5.2)
352 ''''''''''''''''''''''''''''''
354 The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
355 (the ISA has never been upstreamed to a compiler toolchain). Therefore
356 this CPU is also deprecated.
361 Backwards compatibility
362 -----------------------
364 Runnability guarantee of CPU models (since 4.1)
365 '''''''''''''''''''''''''''''''''''''''''''''''
367 Previous versions of QEMU never changed existing CPU models in
368 ways that introduced additional host software or hardware
369 requirements to the VM. This allowed management software to
370 safely change the machine type of an existing VM without
371 introducing new requirements ("runnability guarantee"). This
372 prevented CPU models from being updated to include CPU
373 vulnerability mitigations, leaving guests vulnerable in the
374 default configuration.
376 The CPU model runnability guarantee won't apply anymore to
377 existing CPU models. Management software that needs runnability
378 guarantees must resolve the CPU model aliases using the
379 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
382 While those guarantees are kept, the return value of
383 ``query-cpu-definitions`` will have existing CPU model aliases
384 point to a version that doesn't break runnability guarantees
385 (specifically, version 1 of those CPU models). In future QEMU
386 versions, aliases will point to newer CPU model versions
387 depending on the machine type, so management software must
388 resolve CPU model aliases before starting a virtual machine.
396 The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
397 As it is hard to generate binaries for it, declare it deprecated.