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 Short-form boolean options (since 6.0)
43 ''''''''''''''''''''''''''''''''''''''
45 Boolean options such as ``share=on``/``share=off`` could be written
46 in short form as ``share`` and ``noshare``. This is now deprecated
47 and will cause a warning.
49 ``delay`` option for socket character devices (since 6.0)
50 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
52 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
53 rather than ``delay=off``.
55 ``-spice password=string`` (since 6.0)
56 ''''''''''''''''''''''''''''''''''''''
58 This option is insecure because the SPICE password remains visible in
59 the process listing. This is replaced by the new ``password-secret``
60 option which lets the password be securely provided on the command
61 line using a ``secret`` object instance.
63 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
64 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
66 Specified CPU topology parameters must be greater than zero.
68 In the SMP configuration, users should either provide a CPU topology
69 parameter with a reasonable value (greater than zero) or just omit it
70 and QEMU will compute the missing value.
72 However, historically it was implicitly allowed for users to provide
73 a parameter with zero value, which is meaningless and could also possibly
74 cause unexpected results in the -smp parsing. So support for this kind of
75 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
76 be removed in the near future, users have to ensure that all the topology
77 members described with -smp are greater than zero.
79 Plugin argument passing through ``arg=<string>`` (since 6.1)
80 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
82 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
83 command-line less readable, especially when the argument itself consist of a
84 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
85 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
86 as short-form boolean values, and passed to plugins as ``arg_name=on``.
87 However, short-form booleans are deprecated and full explicit ``arg_name=on``
90 ``-drive if=none`` for the sifive_u OTP device (since 6.2)
91 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
93 Using ``-drive if=none`` to configure the OTP device of the sifive_u
94 RISC-V machine is deprecated. Use ``-drive if=pflash`` instead.
97 QEMU Machine Protocol (QMP) commands
98 ------------------------------------
100 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
101 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
103 Use argument ``id`` instead.
105 ``eject`` argument ``device`` (since 2.8)
106 '''''''''''''''''''''''''''''''''''''''''
108 Use argument ``id`` instead.
110 ``blockdev-change-medium`` argument ``device`` (since 2.8)
111 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
113 Use argument ``id`` instead.
115 ``block_set_io_throttle`` argument ``device`` (since 2.8)
116 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
118 Use argument ``id`` instead.
120 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
121 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
123 Use argument value ``null`` instead.
125 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
126 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
128 Use arguments ``base-node`` and ``top-node`` instead.
130 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
131 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
133 Use the more generic commands ``block-export-add`` and ``block-export-del``
134 instead. As part of this deprecation, where ``nbd-server-add`` used a
135 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
137 ``query-qmp-schema`` return value member ``values`` (since 6.2)
138 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
140 Member ``values`` in return value elements with meta-type ``enum`` is
141 deprecated. Use ``members`` instead.
143 ``drive-backup`` (since 6.2)
144 ''''''''''''''''''''''''''''
146 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
147 This change primarily separates the creation/opening process of the backup
148 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
149 same arguments as ``drive-backup``, except the ``format`` and ``mode``
150 options are removed in favor of using explicit ``blockdev-create`` and
151 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
154 Incorrectly typed ``device_add`` arguments (since 6.2)
155 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
157 Due to shortcomings in the internal implementation of ``device_add``, QEMU
158 incorrectly accepts certain invalid arguments: Any object or list arguments are
159 silently ignored. Other argument types are not checked, but an implicit
160 conversion happens, so that e.g. string values can be assigned to integer
161 device properties or vice versa.
163 This is a bug in QEMU that will be fixed in the future so that previously
164 accepted incorrect commands will return an error. Users should make sure that
165 all arguments passed to ``device_add`` are consistent with the documented
171 MIPS ``Trap-and-Emul`` KVM support (since 6.0)
172 ''''''''''''''''''''''''''''''''''''''''''''''
174 The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed
175 from Linux upstream kernel, declare it deprecated.
183 As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of
184 MIPS moved out of support making it hard to maintain our
185 cross-compilation CI tests of the architecture. As we no longer have
186 CI coverage support may bitrot away before the deprecation process
187 completes. The little endian variants of MIPS (both 32 and 64 bit) are
188 still a supported host architecture.
190 QEMU API (QAPI) events
191 ----------------------
193 ``MEM_UNPLUG_ERROR`` (since 6.2)
194 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
196 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
199 System emulator machines
200 ------------------------
202 Arm ``virt`` machine ``dtb-kaslr-seed`` property
203 ''''''''''''''''''''''''''''''''''''''''''''''''
205 The ``dtb-kaslr-seed`` property on the ``virt`` board has been
206 deprecated; use the new name ``dtb-randomness`` instead. The new name
207 better reflects the way this property affects all random data within
208 the device tree blob, not just the ``kaslr-seed`` node.
210 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0)
211 '''''''''''''''''''''''''''''''''''''''''''''''''''''
213 These old machine types are quite neglected nowadays and thus might have
214 various pitfalls with regards to live migration. Use a newer machine type
221 Using non-persistent backing file with pmem=on (since 6.1)
222 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
224 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
225 device. However enabling ``memory-backend-file.pmem`` option, when backing file
226 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
227 of persistent memory, is not safe and may lead to data loss or corruption in case
231 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
232 (without persistence guaranties) with backing file on non DAX storage
233 - move backing file to NVDIMM storage and keep ``pmem=on``
234 (to have NVDIMM with persistence guaranties).
239 Emulated device options
240 '''''''''''''''''''''''
242 ``-device virtio-blk,scsi=on|off`` (since 5.0)
243 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
246 and later do not support it because the virtio-scsi device was introduced for
247 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
249 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
252 ``-device sga`` (since 6.2)
253 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
255 The ``sga`` device loads an option ROM for x86 targets which enables
256 SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards
257 contains native support for this feature and thus use of the option
258 ROM approach is obsolete. The native SeaBIOS support can be activated
259 by using ``-machine graphics=off``.
261 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
262 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
264 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
265 identifier that is not globally unique. If an EUI-64 identifier is required, the
266 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
268 ``-device nvme,use-intel-id=on|off`` (since 7.1)
269 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
271 The ``nvme`` device originally used a PCI Vendor/Device Identifier combination
272 from Intel that was not properly allocated. Since version 5.2, the controller
273 has used a properly allocated identifier. Deprecate the ``use-intel-id``
274 machine compatibility parameter.
280 ``"backing": ""`` (since 2.12)
281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
283 In order to prevent QEMU from automatically opening an image's backing
284 chain, use ``"backing": null`` instead.
286 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
287 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
289 Options for ``rbd`` should be specified according to its runtime options,
290 like other block drivers. Legacy parsing of keyvalue pair encoded
291 filenames is useful to open images with the old format for backing files;
292 These image files should be updated to use the current format.
294 Example of legacy encoding::
296 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
298 The above, converted to the current supported format::
300 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
302 Backwards compatibility
303 -----------------------
305 Runnability guarantee of CPU models (since 4.1)
306 '''''''''''''''''''''''''''''''''''''''''''''''
308 Previous versions of QEMU never changed existing CPU models in
309 ways that introduced additional host software or hardware
310 requirements to the VM. This allowed management software to
311 safely change the machine type of an existing VM without
312 introducing new requirements ("runnability guarantee"). This
313 prevented CPU models from being updated to include CPU
314 vulnerability mitigations, leaving guests vulnerable in the
315 default configuration.
317 The CPU model runnability guarantee won't apply anymore to
318 existing CPU models. Management software that needs runnability
319 guarantees must resolve the CPU model aliases using the
320 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
323 While those guarantees are kept, the return value of
324 ``query-cpu-definitions`` will have existing CPU model aliases
325 point to a version that doesn't break runnability guarantees
326 (specifically, version 1 of those CPU models). In future QEMU
327 versions, aliases will point to newer CPU model versions
328 depending on the machine type, so management software must
329 resolve CPU model aliases before starting a virtual machine.
337 There is a new Rust implementation of ``virtiofsd`` at
338 ``https://gitlab.com/virtio-fs/virtiofsd``;
339 since this is now marked stable, new development should be done on that
340 rather than the existing C version in the QEMU tree.
341 The C version will still accept fixes and patches that
342 are already in development for the moment, but will eventually
343 be deleted from this tree.
344 New deployments should use the Rust version, and existing systems
345 should consider moving to it. The command line and feature set
346 is very close and moving should be simple.
352 ``--blacklist`` command line option (since 7.2)
353 '''''''''''''''''''''''''''''''''''''''''''''''
355 ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better
356 wording for what this option does). The short form ``-b`` still stays
357 the same and thus is the preferred way for scripts that should run with
358 both, older and future versions of QEMU.
360 ``blacklist`` config file option (since 7.2)
361 ''''''''''''''''''''''''''''''''''''''''''''
363 The ``blacklist`` config file option has been renamed to ``block-rpcs``
364 (to be in sync with the renaming of the corresponding command line