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 ``-accel hax`` (since 8.0)
103 ''''''''''''''''''''''''''
105 The HAXM project has been retired (see https://github.com/intel/haxm#status).
106 Use "whpx" (on Windows) or "hvf" (on macOS) instead.
109 QEMU Machine Protocol (QMP) commands
110 ------------------------------------
112 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
113 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
115 Use argument ``id`` instead.
117 ``eject`` argument ``device`` (since 2.8)
118 '''''''''''''''''''''''''''''''''''''''''
120 Use argument ``id`` instead.
122 ``blockdev-change-medium`` argument ``device`` (since 2.8)
123 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
125 Use argument ``id`` instead.
127 ``block_set_io_throttle`` argument ``device`` (since 2.8)
128 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''
130 Use argument ``id`` instead.
132 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
133 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
135 Use argument value ``null`` instead.
137 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
138 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
140 Use arguments ``base-node`` and ``top-node`` instead.
142 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
143 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
145 Use the more generic commands ``block-export-add`` and ``block-export-del``
146 instead. As part of this deprecation, where ``nbd-server-add`` used a
147 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
149 ``query-qmp-schema`` return value member ``values`` (since 6.2)
150 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
152 Member ``values`` in return value elements with meta-type ``enum`` is
153 deprecated. Use ``members`` instead.
155 ``drive-backup`` (since 6.2)
156 ''''''''''''''''''''''''''''
158 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
159 This change primarily separates the creation/opening process of the backup
160 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
161 same arguments as ``drive-backup``, except the ``format`` and ``mode``
162 options are removed in favor of using explicit ``blockdev-create`` and
163 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
166 Incorrectly typed ``device_add`` arguments (since 6.2)
167 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
169 Due to shortcomings in the internal implementation of ``device_add``, QEMU
170 incorrectly accepts certain invalid arguments: Any object or list arguments are
171 silently ignored. Other argument types are not checked, but an implicit
172 conversion happens, so that e.g. string values can be assigned to integer
173 device properties or vice versa.
175 This is a bug in QEMU that will be fixed in the future so that previously
176 accepted incorrect commands will return an error. Users should make sure that
177 all arguments passed to ``device_add`` are consistent with the documented
186 As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of
187 MIPS moved out of support making it hard to maintain our
188 cross-compilation CI tests of the architecture. As we no longer have
189 CI coverage support may bitrot away before the deprecation process
190 completes. The little endian variants of MIPS (both 32 and 64 bit) are
191 still a supported host architecture.
193 QEMU API (QAPI) events
194 ----------------------
196 ``MEM_UNPLUG_ERROR`` (since 6.2)
197 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
199 Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
202 System emulator machines
203 ------------------------
205 Arm ``virt`` machine ``dtb-kaslr-seed`` property
206 ''''''''''''''''''''''''''''''''''''''''''''''''
208 The ``dtb-kaslr-seed`` property on the ``virt`` board has been
209 deprecated; use the new name ``dtb-randomness`` instead. The new name
210 better reflects the way this property affects all random data within
211 the device tree blob, not just the ``kaslr-seed`` node.
213 ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0)
214 '''''''''''''''''''''''''''''''''''''''''''''''''''''
216 These old machine types are quite neglected nowadays and thus might have
217 various pitfalls with regards to live migration. Use a newer machine type
224 Using non-persistent backing file with pmem=on (since 6.1)
225 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
227 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
228 device. However enabling ``memory-backend-file.pmem`` option, when backing file
229 is (a) not DAX capable or (b) not on a filesystem that support direct mapping
230 of persistent memory, is not safe and may lead to data loss or corruption in case
234 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
235 (without persistence guaranties) with backing file on non DAX storage
236 - move backing file to NVDIMM storage and keep ``pmem=on``
237 (to have NVDIMM with persistence guaranties).
242 Emulated device options
243 '''''''''''''''''''''''
245 ``-device virtio-blk,scsi=on|off`` (since 5.0)
246 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
248 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
249 and later do not support it because the virtio-scsi device was introduced for
250 full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
252 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
255 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
258 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
259 identifier that is not globally unique. If an EUI-64 identifier is required, the
260 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
262 ``-device nvme,use-intel-id=on|off`` (since 7.1)
263 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
265 The ``nvme`` device originally used a PCI Vendor/Device Identifier combination
266 from Intel that was not properly allocated. Since version 5.2, the controller
267 has used a properly allocated identifier. Deprecate the ``use-intel-id``
268 machine compatibility parameter.
274 ``"backing": ""`` (since 2.12)
275 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
277 In order to prevent QEMU from automatically opening an image's backing
278 chain, use ``"backing": null`` instead.
280 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
281 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
283 Options for ``rbd`` should be specified according to its runtime options,
284 like other block drivers. Legacy parsing of keyvalue pair encoded
285 filenames is useful to open images with the old format for backing files;
286 These image files should be updated to use the current format.
288 Example of legacy encoding::
290 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
292 The above, converted to the current supported format::
294 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
296 ``iscsi,password=xxx`` (since 8.0)
297 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
299 Specifying the iSCSI password in plain text on the command line using the
300 ``password`` option is insecure. The ``password-secret`` option should be
301 used instead, to refer to a ``--object secret...`` instance that provides
302 a password via a file, or encrypted.
304 Backwards compatibility
305 -----------------------
307 Runnability guarantee of CPU models (since 4.1)
308 '''''''''''''''''''''''''''''''''''''''''''''''
310 Previous versions of QEMU never changed existing CPU models in
311 ways that introduced additional host software or hardware
312 requirements to the VM. This allowed management software to
313 safely change the machine type of an existing VM without
314 introducing new requirements ("runnability guarantee"). This
315 prevented CPU models from being updated to include CPU
316 vulnerability mitigations, leaving guests vulnerable in the
317 default configuration.
319 The CPU model runnability guarantee won't apply anymore to
320 existing CPU models. Management software that needs runnability
321 guarantees must resolve the CPU model aliases using the
322 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
325 While those guarantees are kept, the return value of
326 ``query-cpu-definitions`` will have existing CPU model aliases
327 point to a version that doesn't break runnability guarantees
328 (specifically, version 1 of those CPU models). In future QEMU
329 versions, aliases will point to newer CPU model versions
330 depending on the machine type, so management software must
331 resolve CPU model aliases before starting a virtual machine.
336 ``--blacklist`` command line option (since 7.2)
337 '''''''''''''''''''''''''''''''''''''''''''''''
339 ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better
340 wording for what this option does). The short form ``-b`` still stays
341 the same and thus is the preferred way for scripts that should run with
342 both, older and future versions of QEMU.
344 ``blacklist`` config file option (since 7.2)
345 ''''''''''''''''''''''''''''''''''''''''''''
347 The ``blacklist`` config file option has been renamed to ``block-rpcs``
348 (to be in sync with the renaming of the corresponding command line