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
26 ``gprof`` builds (since 8.0)
27 ''''''''''''''''''''''''''''
29 The ``--enable-gprof`` configure setting relies on compiler
30 instrumentation to gather its data which can distort the generated
31 profile. As other non-instrumenting tools are available that give a
32 more holistic view of the system with non-instrumented binaries we are
33 deprecating the build option and no longer defend it in CI. The
34 ``--enable-gcov`` build option remains for analysis test case
37 System emulator command line arguments
38 --------------------------------------
40 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
41 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
43 The ``-audiodev`` argument is now the preferred way to specify audio
44 backend settings instead of environment variables. To ease migration to
45 the new format, the ``-audiodev-help`` option can be used to convert
46 the current values of the environment variables to ``-audiodev`` options.
48 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
49 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
51 When not using the deprecated legacy audio config, each sound card
52 should specify an ``audiodev=`` property. Additionally, when using
53 vnc, you should specify an ``audiodev=`` property if you plan to
54 transmit audio through the VNC protocol.
56 Short-form boolean options (since 6.0)
57 ''''''''''''''''''''''''''''''''''''''
59 Boolean options such as ``share=on``/``share=off`` could be written
60 in short form as ``share`` and ``noshare``. This is now deprecated
61 and will cause a warning.
63 ``delay`` option for socket character devices (since 6.0)
64 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
66 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
67 rather than ``delay=off``.
69 ``-smp`` ("parameter=0" SMP configurations) (since 6.2)
70 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
72 Specified CPU topology parameters must be greater than zero.
74 In the SMP configuration, users should either provide a CPU topology
75 parameter with a reasonable value (greater than zero) or just omit it
76 and QEMU will compute the missing value.
78 However, historically it was implicitly allowed for users to provide
79 a parameter with zero value, which is meaningless and could also possibly
80 cause unexpected results in the -smp parsing. So support for this kind of
81 configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will
82 be removed in the near future, users have to ensure that all the topology
83 members described with -smp are greater than zero.
85 Plugin argument passing through ``arg=<string>`` (since 6.1)
86 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
88 Passing TCG plugins arguments through ``arg=`` is redundant is makes the
89 command-line less readable, especially when the argument itself consist of a
90 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
91 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
92 as short-form boolean values, and passed to plugins as ``arg_name=on``.
93 However, short-form booleans are deprecated and full explicit ``arg_name=on``
96 ``-no-hpet`` (since 8.0)
97 ''''''''''''''''''''''''
99 The HPET setting has been turned into a machine property.
100 Use ``-machine hpet=off`` instead.
102 ``-no-acpi`` (since 8.0)
103 ''''''''''''''''''''''''
105 The ``-no-acpi`` setting has been turned into a machine property.
106 Use ``-machine acpi=off`` instead.
108 ``-accel hax`` (since 8.0)
109 ''''''''''''''''''''''''''
111 The HAXM project has been retired (see https://github.com/intel/haxm#status).
112 Use "whpx" (on Windows) or "hvf" (on macOS) instead.
115 QEMU Machine Protocol (QMP) commands
116 ------------------------------------
118 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
119 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
121 Use argument ``id`` instead.
123 ``eject`` argument ``device`` (since 2.8)
124 '''''''''''''''''''''''''''''''''''''''''
126 Use argument ``id`` instead.
128 ``blockdev-change-medium`` argument ``device`` (since 2.8)
129 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
131 Use argument ``id`` instead.
133 ``block_set_io_throttle`` argument ``device`` (since 2.8)
134 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
136 Use argument ``id`` instead.
138 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
139 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
141 Use argument value ``null`` instead.
143 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
144 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
146 Use arguments ``base-node`` and ``top-node`` instead.
148 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
149 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
151 Use the more generic commands ``block-export-add`` and ``block-export-del``
152 instead. As part of this deprecation, where ``nbd-server-add`` used a
153 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
155 ``query-qmp-schema`` return value member ``values`` (since 6.2)
156 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
158 Member ``values`` in return value elements with meta-type ``enum`` is
159 deprecated. Use ``members`` instead.
161 ``drive-backup`` (since 6.2)
162 ''''''''''''''''''''''''''''
164 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
165 This change primarily separates the creation/opening process of the backup
166 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
167 same arguments as ``drive-backup``, except the ``format`` and ``mode``
168 options are removed in favor of using explicit ``blockdev-create`` and
169 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
172 Incorrectly typed ``device_add`` arguments (since 6.2)
173 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
175 Due to shortcomings in the internal implementation of ``device_add``, QEMU
176 incorrectly accepts certain invalid arguments: Any object or list arguments are
177 silently ignored. Other argument types are not checked, but an implicit
178 conversion happens, so that e.g. string values can be assigned to integer
179 device properties or vice versa.
181 This is a bug in QEMU that will be fixed in the future so that previously
182 accepted incorrect commands will return an error. Users should make sure that
183 all arguments passed to ``device_add`` are consistent with the documented
192 As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of
193 MIPS moved out of support making it hard to maintain our
194 cross-compilation CI tests of the architecture. As we no longer have
195 CI coverage support may bitrot away before the deprecation process
196 completes. The little endian variants of MIPS (both 32 and 64 bit) are
197 still a supported host architecture.
199 System emulation on 32-bit x86 hosts (since 8.0)
200 ''''''''''''''''''''''''''''''''''''''''''''''''
202 Support for 32-bit x86 host deployments is increasingly uncommon in mainstream
203 OS distributions given the widespread availability of 64-bit x86 hardware.
204 The QEMU project no longer considers 32-bit x86 support for system emulation to
205 be an effective use of its limited resources, and thus intends to discontinue
206 it. Since all recent x86 hardware from the past >10 years is capable of the
207 64-bit x86 extensions, a corresponding 64-bit OS should be used instead.
209 System emulation on 32-bit arm hosts (since 8.0)
210 ''''''''''''''''''''''''''''''''''''''''''''''''
212 Since QEMU needs a strong host machine for running full system emulation, and
213 all recent powerful arm hosts support 64-bit, the QEMU project deprecates the
214 support for running any system emulation on 32-bit arm hosts in general. Use
215 64-bit arm hosts for system emulation instead. (Note: "user" mode emulation
216 continues to be supported on 32-bit arm hosts, too)
219 QEMU API (QAPI) events
220 ----------------------
222 ``MEM_UNPLUG_ERROR`` (since 6.2)
223 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
225 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
228 System emulator machines
229 ------------------------
231 Arm ``virt`` machine ``dtb-kaslr-seed`` property
232 ''''''''''''''''''''''''''''''''''''''''''''''''
234 The ``dtb-kaslr-seed`` property on the ``virt`` board has been
235 deprecated; use the new name ``dtb-randomness`` instead. The new name
236 better reflects the way this property affects all random data within
237 the device tree blob, not just the ``kaslr-seed`` node.
239 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0)
240 '''''''''''''''''''''''''''''''''''''''''''''''''''''
242 These old machine types are quite neglected nowadays and thus might have
243 various pitfalls with regards to live migration. Use a newer machine type
250 Using non-persistent backing file with pmem=on (since 6.1)
251 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
253 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
254 device. However enabling ``memory-backend-file.pmem`` option, when backing file
255 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
256 of persistent memory, is not safe and may lead to data loss or corruption in case
260 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
261 (without persistence guaranties) with backing file on non DAX storage
262 - move backing file to NVDIMM storage and keep ``pmem=on``
263 (to have NVDIMM with persistence guaranties).
268 Emulated device options
269 '''''''''''''''''''''''
271 ``-device virtio-blk,scsi=on|off`` (since 5.0)
272 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
274 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
275 and later do not support it because the virtio-scsi device was introduced for
276 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
278 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
281 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
282 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
284 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
285 identifier that is not globally unique. If an EUI-64 identifier is required, the
286 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
288 ``-device nvme,use-intel-id=on|off`` (since 7.1)
289 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
291 The ``nvme`` device originally used a PCI Vendor/Device Identifier combination
292 from Intel that was not properly allocated. Since version 5.2, the controller
293 has used a properly allocated identifier. Deprecate the ``use-intel-id``
294 machine compatibility parameter.
300 ``"backing": ""`` (since 2.12)
301 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
303 In order to prevent QEMU from automatically opening an image's backing
304 chain, use ``"backing": null`` instead.
306 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
307 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
309 Options for ``rbd`` should be specified according to its runtime options,
310 like other block drivers. Legacy parsing of keyvalue pair encoded
311 filenames is useful to open images with the old format for backing files;
312 These image files should be updated to use the current format.
314 Example of legacy encoding::
316 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
318 The above, converted to the current supported format::
320 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
322 ``iscsi,password=xxx`` (since 8.0)
323 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
325 Specifying the iSCSI password in plain text on the command line using the
326 ``password`` option is insecure. The ``password-secret`` option should be
327 used instead, to refer to a ``--object secret...`` instance that provides
328 a password via a file, or encrypted.
330 Backwards compatibility
331 -----------------------
333 Runnability guarantee of CPU models (since 4.1)
334 '''''''''''''''''''''''''''''''''''''''''''''''
336 Previous versions of QEMU never changed existing CPU models in
337 ways that introduced additional host software or hardware
338 requirements to the VM. This allowed management software to
339 safely change the machine type of an existing VM without
340 introducing new requirements ("runnability guarantee"). This
341 prevented CPU models from being updated to include CPU
342 vulnerability mitigations, leaving guests vulnerable in the
343 default configuration.
345 The CPU model runnability guarantee won't apply anymore to
346 existing CPU models. Management software that needs runnability
347 guarantees must resolve the CPU model aliases using the
348 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
351 While those guarantees are kept, the return value of
352 ``query-cpu-definitions`` will have existing CPU model aliases
353 point to a version that doesn't break runnability guarantees
354 (specifically, version 1 of those CPU models). In future QEMU
355 versions, aliases will point to newer CPU model versions
356 depending on the machine type, so management software must
357 resolve CPU model aliases before starting a virtual machine.
362 ``--blacklist`` command line option (since 7.2)
363 '''''''''''''''''''''''''''''''''''''''''''''''
365 ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better
366 wording for what this option does). The short form ``-b`` still stays
367 the same and thus is the preferred way for scripts that should run with
368 both, older and future versions of QEMU.
370 ``blacklist`` config file option (since 7.2)
371 ''''''''''''''''''''''''''''''''''''''''''''
373 The ``blacklist`` config file option has been renamed to ``block-rpcs``
374 (to be in sync with the renaming of the corresponding command line