xref: /openbmc/qemu/docs/about/deprecated.rst (revision 7e6055c9)
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``-watchdog`` (since 6.2)
164'''''''''''''''''''''''''
165
166Use ``-device`` instead.
167
168``-smp`` ("parameter=0" SMP configurations) (since 6.2)
169'''''''''''''''''''''''''''''''''''''''''''''''''''''''
170
171Specified CPU topology parameters must be greater than zero.
172
173In the SMP configuration, users should either provide a CPU topology
174parameter with a reasonable value (greater than zero) or just omit it
175and QEMU will compute the missing value.
176
177However, historically it was implicitly allowed for users to provide
178a parameter with zero value, which is meaningless and could also possibly
179cause unexpected results in the -smp parsing. So support for this kind of
180configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
181be removed in the near future, users have to ensure that all the topology
182members described with -smp are greater than zero.
183
184Plugin argument passing through ``arg=<string>`` (since 6.1)
185''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
186
187Passing TCG plugins arguments through ``arg=`` is redundant is makes the
188command-line less readable, especially when the argument itself consist of a
189name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
190Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
191as short-form boolean values, and passed to plugins as ``arg_name=on``.
192However, short-form booleans are deprecated and full explicit ``arg_name=on``
193form is preferred.
194
195
196QEMU Machine Protocol (QMP) commands
197------------------------------------
198
199``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
200'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
201
202Use argument ``id`` instead.
203
204``eject`` argument ``device`` (since 2.8)
205'''''''''''''''''''''''''''''''''''''''''
206
207Use argument ``id`` instead.
208
209``blockdev-change-medium`` argument ``device`` (since 2.8)
210''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
211
212Use argument ``id`` instead.
213
214``block_set_io_throttle`` argument ``device`` (since 2.8)
215'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
216
217Use argument ``id`` instead.
218
219``blockdev-add`` empty string argument ``backing`` (since 2.10)
220'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
221
222Use argument value ``null`` instead.
223
224``block-commit`` arguments ``base`` and ``top`` (since 3.1)
225'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
226
227Use arguments ``base-node`` and ``top-node`` instead.
228
229``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
230''''''''''''''''''''''''''''''''''''''''''''''''''''''''
231
232Use the more generic commands ``block-export-add`` and ``block-export-del``
233instead.  As part of this deprecation, where ``nbd-server-add`` used a
234single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
235
236``query-qmp-schema`` return value member ``values`` (since 6.2)
237'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
238
239Member ``values`` in return value elements with meta-type ``enum`` is
240deprecated.  Use ``members`` instead.
241
242System accelerators
243-------------------
244
245MIPS ``Trap-and-Emul`` KVM support (since 6.0)
246''''''''''''''''''''''''''''''''''''''''''''''
247
248The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
249from Linux upstream kernel, declare it deprecated.
250
251System emulator CPUS
252--------------------
253
254``Icelake-Client`` CPU Model (since 5.2)
255''''''''''''''''''''''''''''''''''''''''
256
257``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU
258Models instead.
259
260MIPS ``I7200`` CPU Model (since 5.2)
261''''''''''''''''''''''''''''''''''''
262
263The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
264(the ISA has never been upstreamed to a compiler toolchain). Therefore
265this CPU is also deprecated.
266
267
268QEMU API (QAPI) events
269----------------------
270
271``MEM_UNPLUG_ERROR`` (since 6.2)
272''''''''''''''''''''''''''''''''''''''''''''''''''''''''
273
274Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
275
276
277System emulator machines
278------------------------
279
280Aspeed ``swift-bmc`` machine (since 6.1)
281''''''''''''''''''''''''''''''''''''''''
282
283This machine is deprecated because we have enough AST2500 based OpenPOWER
284machines. It can be easily replaced by the ``witherspoon-bmc`` or the
285``romulus-bmc`` machines.
286
287Backend options
288---------------
289
290Using non-persistent backing file with pmem=on (since 6.1)
291''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
292
293This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
294device. However enabling ``memory-backend-file.pmem`` option, when backing file
295is (a) not DAX capable or (b) not on a filesystem that support direct mapping
296of persistent memory, is not safe and may lead to data loss or corruption in case
297of host crash.
298Options are:
299
300    - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
301      (without persistence guaranties) with backing file on non DAX storage
302    - move backing file to NVDIMM storage and keep ``pmem=on``
303      (to have NVDIMM with persistence guaranties).
304
305Device options
306--------------
307
308Emulated device options
309'''''''''''''''''''''''
310
311``-device virtio-blk,scsi=on|off`` (since 5.0)
312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
313
314The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
315and later do not support it because the virtio-scsi device was introduced for
316full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
317
318Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
319alias.
320
321``-device sga`` (since 6.2)
322^^^^^^^^^^^^^^^^^^^^^^^^^^^
323
324The ``sga`` device loads an option ROM for x86 targets which enables
325SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
326contains native support for this feature and thus use of the option
327ROM approach is obsolete. The native SeaBIOS support can be activated
328by using ``-machine graphics=off``.
329
330
331Block device options
332''''''''''''''''''''
333
334``"backing": ""`` (since 2.12)
335^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
336
337In order to prevent QEMU from automatically opening an image's backing
338chain, use ``"backing": null`` instead.
339
340``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
341^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
342
343Options for ``rbd`` should be specified according to its runtime options,
344like other block drivers.  Legacy parsing of keyvalue pair encoded
345filenames is useful to open images with the old format for backing files;
346These image files should be updated to use the current format.
347
348Example of legacy encoding::
349
350  json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
351
352The above, converted to the current supported format::
353
354  json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
355
356linux-user mode CPUs
357--------------------
358
359``ppc64abi32`` CPUs (since 5.2)
360'''''''''''''''''''''''''''''''
361
362The ``ppc64abi32`` architecture has a number of issues which regularly
363trip up our CI testing and is suspected to be quite broken. For that
364reason the maintainers strongly suspect no one actually uses it.
365
366MIPS ``I7200`` CPU (since 5.2)
367''''''''''''''''''''''''''''''
368
369The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated
370(the ISA has never been upstreamed to a compiler toolchain). Therefore
371this CPU is also deprecated.
372
373Backwards compatibility
374-----------------------
375
376Runnability guarantee of CPU models (since 4.1)
377'''''''''''''''''''''''''''''''''''''''''''''''
378
379Previous versions of QEMU never changed existing CPU models in
380ways that introduced additional host software or hardware
381requirements to the VM.  This allowed management software to
382safely change the machine type of an existing VM without
383introducing new requirements ("runnability guarantee").  This
384prevented CPU models from being updated to include CPU
385vulnerability mitigations, leaving guests vulnerable in the
386default configuration.
387
388The CPU model runnability guarantee won't apply anymore to
389existing CPU models.  Management software that needs runnability
390guarantees must resolve the CPU model aliases using the
391``alias-of`` field returned by the ``query-cpu-definitions`` QMP
392command.
393
394While those guarantees are kept, the return value of
395``query-cpu-definitions`` will have existing CPU model aliases
396point to a version that doesn't break runnability guarantees
397(specifically, version 1 of those CPU models).  In future QEMU
398versions, aliases will point to newer CPU model versions
399depending on the machine type, so management software must
400resolve CPU model aliases before starting a virtual machine.
401
402Guest Emulator ISAs
403-------------------
404
405nanoMIPS ISA
406''''''''''''
407
408The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain.
409As it is hard to generate binaries for it, declare it deprecated.
410