xref: /qemu/docs/about/deprecated.rst (revision a443c3e2)
1.. _Deprecated features:
2
3Deprecated features
4===================
5
6In general features are intended to be supported indefinitely once
7introduced into QEMU. In the event that a feature needs to be removed,
8it will be listed in this section. The feature will remain functional for the
9release in which it was deprecated and one further release. After these two
10releases, the feature is liable to be removed. Deprecated features may also
11generate warnings on the console when QEMU starts up, or if activated via a
12monitor command, however, this is not a mandatory requirement.
13
14Prior to the 2.10.0 release there was no official policy on how
15long features would be deprecated prior to their removal, nor
16any documented list of which features were deprecated. Thus
17any features deprecated prior to 2.10.0 will be treated as if
18they were first deprecated in the 2.10.0 release.
19
20What follows is a list of all features currently marked as
21deprecated.
22
23System emulator command line arguments
24--------------------------------------
25
26``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
27'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
28
29The ``-audiodev`` argument is now the preferred way to specify audio
30backend settings instead of environment variables.  To ease migration to
31the new format, the ``-audiodev-help`` option can be used to convert
32the current values of the environment variables to ``-audiodev`` options.
33
34Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
35''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
36
37When not using the deprecated legacy audio config, each sound card
38should specify an ``audiodev=`` property.  Additionally, when using
39vnc, you should specify an ``audiodev=`` property if you plan to
40transmit audio through the VNC protocol.
41
42Creating sound card devices using ``-soundhw`` (since 5.1)
43''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
44
45Sound card devices should be created using ``-device`` instead.  The
46names are the same for most devices.  The exceptions are ``hda`` which
47needs two devices (``-device intel-hda -device hda-duplex``) and
48``pcspk`` which can be activated using ``-machine
49pcspk-audiodev=<name>``.
50
51``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0)
52''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
53
54``tty`` and ``parport`` are aliases that will be removed. Instead, the
55actual backend names ``serial`` and ``parallel`` should be used.
56
57Short-form boolean options (since 6.0)
58''''''''''''''''''''''''''''''''''''''
59
60Boolean options such as ``share=on``/``share=off`` could be written
61in short form as ``share`` and ``noshare``.  This is now deprecated
62and will cause a warning.
63
64``delay`` option for socket character devices (since 6.0)
65'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
66
67The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
68rather than ``delay=off``.
69
70``--enable-fips`` (since 6.0)
71'''''''''''''''''''''''''''''
72
73This option restricts usage of certain cryptographic algorithms when
74the host is operating in FIPS mode.
75
76If FIPS compliance is required, QEMU should be built with the ``libgcrypt``
77library enabled as a cryptography provider.
78
79Neither the ``nettle`` library, or the built-in cryptography provider are
80supported on FIPS enabled hosts.
81
82``-writeconfig`` (since 6.0)
83'''''''''''''''''''''''''''''
84
85The ``-writeconfig`` option is not able to serialize the entire contents
86of the QEMU command line.  It is thus considered a failed experiment
87and deprecated, with no current replacement.
88
89Userspace local APIC with KVM (x86, since 6.0)
90''''''''''''''''''''''''''''''''''''''''''''''
91
92Using ``-M kernel-irqchip=off`` with x86 machine types that include a local
93APIC is deprecated.  The ``split`` setting is supported, as is using
94``-M kernel-irqchip=off`` with the ISA PC machine type.
95
96hexadecimal sizes with scaling multipliers (since 6.0)
97''''''''''''''''''''''''''''''''''''''''''''''''''''''
98
99Input 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
101the value is hexadecimal.  That is, '0x20M' is deprecated, and should
102be written either as '32M' or as '0x2000000'.
103
104``-spice password=string`` (since 6.0)
105''''''''''''''''''''''''''''''''''''''
106
107This option is insecure because the SPICE password remains visible in
108the process listing. This is replaced by the new ``password-secret``
109option which lets the password be securely provided on the command
110line using a ``secret`` object instance.
111
112``opened`` property of ``rng-*`` objects (since 6.0)
113''''''''''''''''''''''''''''''''''''''''''''''''''''
114
115The 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
117other options have been processed.  This will either have no effect (if
118``opened`` was the last option) or cause errors.  The property is therefore
119useless and should not be specified.
120
121``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0)
122''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
123
124The 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
126other 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
128if they were not given.  The property is therefore useless and should not be
129specified.
130
131``-display sdl,window_close=...`` (since 6.1)
132'''''''''''''''''''''''''''''''''''''''''''''
133
134Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
135an underscore between "window" and "close").
136
137``-no-quit`` (since 6.1)
138''''''''''''''''''''''''
139
140The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which
141should be used instead.
142
143``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2)
144''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
145
146Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead.
147
148``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2)
149''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
150
151Use ``-display sdl,grab-mod=rctrl`` instead.
152
153``-sdl`` (since 6.2)
154''''''''''''''''''''
155
156Use ``-display sdl`` instead.
157
158``-curses`` (since 6.2)
159'''''''''''''''''''''''
160
161Use ``-display curses`` instead.
162
163``-smp`` ("parameter=0" SMP configurations) (since 6.2)
164'''''''''''''''''''''''''''''''''''''''''''''''''''''''
165
166Specified CPU topology parameters must be greater than zero.
167
168In the SMP configuration, users should either provide a CPU topology
169parameter with a reasonable value (greater than zero) or just omit it
170and QEMU will compute the missing value.
171
172However, historically it was implicitly allowed for users to provide
173a parameter with zero value, which is meaningless and could also possibly
174cause unexpected results in the -smp parsing. So support for this kind of
175configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
176be removed in the near future, users have to ensure that all the topology
177members described with -smp are greater than zero.
178
179Plugin argument passing through ``arg=<string>`` (since 6.1)
180''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
181
182Passing TCG plugins arguments through ``arg=`` is redundant is makes the
183command-line less readable, especially when the argument itself consist of a
184name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
185Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
186as short-form boolean values, and passed to plugins as ``arg_name=on``.
187However, short-form booleans are deprecated and full explicit ``arg_name=on``
188form is preferred.
189
190
191QEMU Machine Protocol (QMP) commands
192------------------------------------
193
194``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
195'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
196
197Use argument ``id`` instead.
198
199``eject`` argument ``device`` (since 2.8)
200'''''''''''''''''''''''''''''''''''''''''
201
202Use argument ``id`` instead.
203
204``blockdev-change-medium`` argument ``device`` (since 2.8)
205''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
206
207Use argument ``id`` instead.
208
209``block_set_io_throttle`` argument ``device`` (since 2.8)
210'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
211
212Use argument ``id`` instead.
213
214``blockdev-add`` empty string argument ``backing`` (since 2.10)
215'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
216
217Use argument value ``null`` instead.
218
219``block-commit`` arguments ``base`` and ``top`` (since 3.1)
220'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
221
222Use arguments ``base-node`` and ``top-node`` instead.
223
224``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
225''''''''''''''''''''''''''''''''''''''''''''''''''''''''
226
227Use the more generic commands ``block-export-add`` and ``block-export-del``
228instead.  As part of this deprecation, where ``nbd-server-add`` used a
229single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
230
231``query-qmp-schema`` return value member ``values`` (since 6.2)
232'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
233
234Member ``values`` in return value elements with meta-type ``enum`` is
235deprecated.  Use ``members`` instead.
236
237System accelerators
238-------------------
239
240MIPS ``Trap-and-Emul`` KVM support (since 6.0)
241''''''''''''''''''''''''''''''''''''''''''''''
242
243The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
244from Linux upstream kernel, declare it deprecated.
245
246System emulator CPUS
247--------------------
248
249``Icelake-Client`` CPU Model (since 5.2)
250''''''''''''''''''''''''''''''''''''''''
251
252``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
253Models instead.
254
255MIPS ``I7200`` CPU Model (since 5.2)
256''''''''''''''''''''''''''''''''''''
257
258The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
259(the ISA has never been upstreamed to a compiler toolchain). Therefore
260this CPU is also deprecated.
261
262
263QEMU API (QAPI) events
264----------------------
265
266``MEM_UNPLUG_ERROR`` (since 6.2)
267''''''''''''''''''''''''''''''''''''''''''''''''''''''''
268
269Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
270
271
272System emulator machines
273------------------------
274
275Aspeed ``swift-bmc`` machine (since 6.1)
276''''''''''''''''''''''''''''''''''''''''
277
278This machine is deprecated because we have enough AST2500 based OpenPOWER
279machines. It can be easily replaced by the ``witherspoon-bmc`` or the
280``romulus-bmc`` machines.
281
282Backend options
283---------------
284
285Using non-persistent backing file with pmem=on (since 6.1)
286''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
287
288This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
289device. However enabling ``memory-backend-file.pmem`` option, when backing file
290is (a) not DAX capable or (b) not on a filesystem that support direct mapping
291of persistent memory, is not safe and may lead to data loss or corruption in case
292of host crash.
293Options are:
294
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).
299
300Device options
301--------------
302
303Emulated device options
304'''''''''''''''''''''''
305
306``-device virtio-blk,scsi=on|off`` (since 5.0)
307^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
308
309The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
310and later do not support it because the virtio-scsi device was introduced for
311full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
312
313Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
314alias.
315
316Block device options
317''''''''''''''''''''
318
319``"backing": ""`` (since 2.12)
320^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
321
322In order to prevent QEMU from automatically opening an image's backing
323chain, use ``"backing": null`` instead.
324
325``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
326^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328Options for ``rbd`` should be specified according to its runtime options,
329like other block drivers.  Legacy parsing of keyvalue pair encoded
330filenames is useful to open images with the old format for backing files;
331These image files should be updated to use the current format.
332
333Example of legacy encoding::
334
335  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
336
337The above, converted to the current supported format::
338
339  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
340
341linux-user mode CPUs
342--------------------
343
344``ppc64abi32`` CPUs (since 5.2)
345'''''''''''''''''''''''''''''''
346
347The ``ppc64abi32`` architecture has a number of issues which regularly
348trip up our CI testing and is suspected to be quite broken. For that
349reason the maintainers strongly suspect no one actually uses it.
350
351MIPS ``I7200`` CPU (since 5.2)
352''''''''''''''''''''''''''''''
353
354The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
355(the ISA has never been upstreamed to a compiler toolchain). Therefore
356this CPU is also deprecated.
357
358Related binaries
359----------------
360
361Backwards compatibility
362-----------------------
363
364Runnability guarantee of CPU models (since 4.1)
365'''''''''''''''''''''''''''''''''''''''''''''''
366
367Previous versions of QEMU never changed existing CPU models in
368ways that introduced additional host software or hardware
369requirements to the VM.  This allowed management software to
370safely change the machine type of an existing VM without
371introducing new requirements ("runnability guarantee").  This
372prevented CPU models from being updated to include CPU
373vulnerability mitigations, leaving guests vulnerable in the
374default configuration.
375
376The CPU model runnability guarantee won't apply anymore to
377existing CPU models.  Management software that needs runnability
378guarantees must resolve the CPU model aliases using the
379``alias-of`` field returned by the ``query-cpu-definitions`` QMP
380command.
381
382While those guarantees are kept, the return value of
383``query-cpu-definitions`` will have existing CPU model aliases
384point to a version that doesn't break runnability guarantees
385(specifically, version 1 of those CPU models).  In future QEMU
386versions, aliases will point to newer CPU model versions
387depending on the machine type, so management software must
388resolve CPU model aliases before starting a virtual machine.
389
390Guest Emulator ISAs
391-------------------
392
393nanoMIPS ISA
394''''''''''''
395
396The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
397As it is hard to generate binaries for it, declare it deprecated.
398