]> git.proxmox.com Git - mirror_qemu.git/blame - docs/about/deprecated.rst
migration: Remove 'blk/-b' option from migrate commands
[mirror_qemu.git] / docs / about / deprecated.rst
CommitLineData
7f800d34
MAL
1.. _Deprecated features:
2
41fba161
PM
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,
ef1f5b0a
SH
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.
41fba161
PM
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
ccd3b3b8
PB
26Short-form boolean options (since 6.0)
27''''''''''''''''''''''''''''''''''''''
28
29Boolean options such as ``share=on``/``share=off`` could be written
30in short form as ``share`` and ``noshare``. This is now deprecated
31and will cause a warning.
a1b40bda 32
fe636424
PB
33``delay`` option for socket character devices (since 6.0)
34'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
35
36The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
37rather than ``delay=off``.
38
67f14574
MM
39Plugin argument passing through ``arg=<string>`` (since 6.1)
40''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
41
42Passing TCG plugins arguments through ``arg=`` is redundant is makes the
43command-line less readable, especially when the argument itself consist of a
44name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
45Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
46as short-form boolean values, and passed to plugins as ``arg_name=on``.
47However, short-form booleans are deprecated and full explicit ``arg_name=on``
48form is preferred.
49
54c4ea8f
ZL
50``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0)
51'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
52
53Specified CPU topology parameters must be supported by the machine.
54
55In the SMP configuration, users should provide the CPU topology parameters that
56are supported by the target machine.
57
58However, historically it was allowed for users to specify the unsupported
59topology parameter as "1", which is meaningless. So support for this kind of
60configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is
61marked deprecated since 9.0, users have to ensure that all the topology members
62described with -smp are supported by the target machine.
63
afc8b05c
ZL
64User-mode emulator command line arguments
65-----------------------------------------
66
67``-p`` (since 9.0)
68''''''''''''''''''
69
70The ``-p`` option pretends to control the host page size. However,
71it is not possible to change the host page size, and using the
72option only causes failures.
73
41fba161
PM
74QEMU Machine Protocol (QMP) commands
75------------------------------------
76
e2cc363b
YW
77``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
78'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
79
80Use argument ``id`` instead.
81
e2cc363b
YW
82``eject`` argument ``device`` (since 2.8)
83'''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
84
85Use argument ``id`` instead.
86
e2cc363b
YW
87``blockdev-change-medium`` argument ``device`` (since 2.8)
88''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
89
90Use argument ``id`` instead.
91
e2cc363b
YW
92``block_set_io_throttle`` argument ``device`` (since 2.8)
93'''''''''''''''''''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
94
95Use argument ``id`` instead.
96
e2cc363b
YW
97``blockdev-add`` empty string argument ``backing`` (since 2.10)
98'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
99
100Use argument value ``null`` instead.
101
e2cc363b
YW
102``block-commit`` arguments ``base`` and ``top`` (since 3.1)
103'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
73756ae3
MA
104
105Use arguments ``base-node`` and ``top-node`` instead.
106
443127e8
KW
107``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
108''''''''''''''''''''''''''''''''''''''''''''''''''''''''
109
110Use the more generic commands ``block-export-add`` and ``block-export-del``
cbad81ce
EB
111instead. As part of this deprecation, where ``nbd-server-add`` used a
112single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
443127e8 113
75ecee72
MA
114``query-qmp-schema`` return value member ``values`` (since 6.2)
115'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
116
117Member ``values`` in return value elements with meta-type ``enum`` is
118deprecated. Use ``members`` instead.
119
1084159b
VSO
120``drive-backup`` (since 6.2)
121''''''''''''''''''''''''''''
122
123Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
124This change primarily separates the creation/opening process of the backup
125target with explicit, separate steps. ``blockdev-backup`` uses mostly the
126same arguments as ``drive-backup``, except the ``format`` and ``mode``
127options are removed in favor of using explicit ``blockdev-create`` and
128``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
129details.
130
4d8b0f0a
KW
131Incorrectly typed ``device_add`` arguments (since 6.2)
132''''''''''''''''''''''''''''''''''''''''''''''''''''''
133
134Due to shortcomings in the internal implementation of ``device_add``, QEMU
135incorrectly accepts certain invalid arguments: Any object or list arguments are
136silently ignored. Other argument types are not checked, but an implicit
137conversion happens, so that e.g. string values can be assigned to integer
138device properties or vice versa.
139
140This is a bug in QEMU that will be fixed in the future so that previously
141accepted incorrect commands will return an error. Users should make sure that
142all arguments passed to ``device_add`` are consistent with the documented
143property types.
144
1a8fc850
AB
145QEMU Machine Protocol (QMP) events
146----------------------------------
147
148``MEM_UNPLUG_ERROR`` (since 6.2)
149''''''''''''''''''''''''''''''''''''''''''''''''''''''''
150
151Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead.
152
5485e52a
AB
153``vcpu`` trace events (since 8.1)
154'''''''''''''''''''''''''''''''''
155
156The ability to instrument QEMU helper functions with vCPU-aware trace
157points was removed in 7.0. However QMP still exposed the vcpu
158parameter. This argument has now been deprecated and the remaining
159remaining trace points that used it are selected just by name.
1a8fc850 160
54ab3c3f
AB
161Host Architectures
162------------------
163
164BE MIPS (since 7.2)
165'''''''''''''''''''
166
167As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of
168MIPS moved out of support making it hard to maintain our
169cross-compilation CI tests of the architecture. As we no longer have
170CI coverage support may bitrot away before the deprecation process
171completes. The little endian variants of MIPS (both 32 and 64 bit) are
172still a supported host architecture.
173
5c27baf9
TH
174System emulation on 32-bit x86 hosts (since 8.0)
175''''''''''''''''''''''''''''''''''''''''''''''''
176
177Support for 32-bit x86 host deployments is increasingly uncommon in mainstream
178OS distributions given the widespread availability of 64-bit x86 hardware.
179The QEMU project no longer considers 32-bit x86 support for system emulation to
180be an effective use of its limited resources, and thus intends to discontinue
181it. Since all recent x86 hardware from the past >10 years is capable of the
18264-bit x86 extensions, a corresponding 64-bit OS should be used instead.
183
184
9997771b
PMD
185System emulator CPUs
186--------------------
187
6a41a621
TH
188``power5+`` and ``power7+`` CPU names (since 9.0)
189'''''''''''''''''''''''''''''''''''''''''''''''''
190
191The character "+" in device (and thus also CPU) names is not allowed
192in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``,
193``power7+`` and ``power7+_v2.1`` are currently still supported via
194an alias, but for consistency these will get removed in a future
195release, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead.
196
029171b5
TH
197``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1)
198'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
199
200The character "+" in device (and thus also CPU) names is not allowed
201in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and
202``Sun-UltraSparc-IV+`` are currently still supported via a workaround,
203but for consistency these will get removed in a future release, too.
204Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead.
205
c7bbef40
AB
206CRIS CPU architecture (since 9.0)
207'''''''''''''''''''''''''''''''''
208
209The CRIS architecture was pulled from Linux in 4.17 and the compiler
210is no longer packaged in any distro making it harder to run the
211``check-tcg`` tests. Unless we can improve the testing situation there
212is a chance the code will bitrot without anyone noticing.
9997771b 213
41fba161
PM
214System emulator machines
215------------------------
216
ac64ebbe
PM
217Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1)
218''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
5242876f
JD
219
220The ``dtb-kaslr-seed`` property on the ``virt`` board has been
221deprecated; use the new name ``dtb-randomness`` instead. The new name
222better reflects the way this property affects all random data within
223the device tree blob, not just the ``kaslr-seed`` node.
224
c7437f0d
TH
225``pc-i440fx-2.0`` up to ``pc-i440fx-2.3`` (since 8.2)
226'''''''''''''''''''''''''''''''''''''''''''''''''''''
227
228These old machine types are quite neglected nowadays and thus might have
229various pitfalls with regards to live migration. Use a newer machine type
230instead.
231
322b038c
ST
232``shix`` (since 9.0)
233''''''''''''''''''''
234
235The machine is no longer in existence and has been long unmaintained
c8cdec74 236in QEMU. This also holds for the TC51828 16MiB flash that it uses.
c7437f0d 237
0cac0f1b 238``pseries-2.1`` up to ``pseries-2.12`` (since 9.0)
1392617d
CLG
239''''''''''''''''''''''''''''''''''''''''''''''''''
240
0cac0f1b 241Older pseries machines before version 3.0 have undergone many changes
1392617d
CLG
242to correct issues, mostly regarding migration compatibility. These are
243no longer maintained and removing them will make the code easier to
0cac0f1b 244read and maintain. Use versions 3.0 and above as a replacement.
1392617d 245
a2531bb8
PM
246Arm machines ``akita``, ``borzoi``, ``cheetah``, ``connex``, ``mainstone``, ``n800``, ``n810``, ``spitz``, ``terrier``, ``tosa``, ``verdex``, ``z2`` (since 9.0)
247''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
248
249QEMU includes models of some machine types where the QEMU code that
250emulates their SoCs is very old and unmaintained. This code is now
251blocking our ability to move forward with various changes across
252the codebase, and over many years nobody has been interested in
253trying to modernise it. We don't expect any of these machines to have
254a large number of users, because they're all modelling hardware that
255has now passed away into history. We are therefore dropping support
256for all machine types using the PXA2xx and OMAP2 SoCs. We are also
257dropping the ``cheetah`` OMAP1 board, because we don't have any
258test images for it and don't know of anybody who does; the ``sx1``
259and ``sx1-v1`` OMAP1 machines remain supported for now.
260
cdcf766d
IM
261Backend options
262---------------
263
264Using non-persistent backing file with pmem=on (since 6.1)
265''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
266
267This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
268device. However enabling ``memory-backend-file.pmem`` option, when backing file
269is (a) not DAX capable or (b) not on a filesystem that support direct mapping
270of persistent memory, is not safe and may lead to data loss or corruption in case
271of host crash.
272Options are:
273
274 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
275 (without persistence guaranties) with backing file on non DAX storage
276 - move backing file to NVDIMM storage and keep ``pmem=on``
277 (to have NVDIMM with persistence guaranties).
278
41fba161
PM
279Device options
280--------------
281
282Emulated device options
283'''''''''''''''''''''''
284
e2cc363b
YW
285``-device virtio-blk,scsi=on|off`` (since 5.0)
286^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
41fba161
PM
287
288The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
289and later do not support it because the virtio-scsi device was introduced for
290full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
291
292Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
293alias.
294
36d83272
KJ
295``-device nvme-ns,eui64-default=on|off`` (since 7.1)
296^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
297
298In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
120f765e 299identifier that is not globally unique. If an EUI-64 identifier is required, the
36d83272
KJ
300user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
301
8b1e59a6
KJ
302``-device nvme,use-intel-id=on|off`` (since 7.1)
303^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
304
305The ``nvme`` device originally used a PCI Vendor/Device Identifier combination
306from Intel that was not properly allocated. Since version 5.2, the controller
307has used a properly allocated identifier. Deprecate the ``use-intel-id``
308machine compatibility parameter.
309
adacc814
GP
310``-device cxl-type3,memdev=xxxx`` (since 8.0)
311^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
312
313The ``cxl-type3`` device initially only used a single memory backend. With
314the addition of volatile memory support, it is now necessary to distinguish
315between persistent and volatile memory backends. As such, memdev is deprecated
316in favor of persistent-memdev.
317
71d72ece
CS
318``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1)
319^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
320
321The 9p ``proxy`` filesystem backend driver has been deprecated and will be
322removed (along with its proxy helper daemon) in a future version of QEMU. Please
323use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem
324backend, or alternatively consider deploying virtiofsd instead.
325
326The 9p ``proxy`` backend was originally developed as an alternative to the 9p
327``local`` backend. The idea was to enhance security by dispatching actual low
328level filesystem operations from 9p server (QEMU process) over to a separate
329process (the virtfs-proxy-helper binary). However this alternative never gained
330momentum. The proxy backend is much slower than the local backend, hasn't seen
331any development in years, and showed to be less secure, especially due to the
332fact that its helper daemon must be run as root, whereas with the local backend
333QEMU is typically run as unprivileged user and allows to tighten behaviour by
334mapping permissions et al by using its 'mapped' security model option.
335
336Nowadays it would make sense to reimplement the ``proxy`` backend by using
337QEMU's ``vhost`` feature, which would eliminate the high latency costs under
338which the 9p ``proxy`` backend currently suffers. However as of to date nobody
313e1629 339has indicated plans for such kind of reimplementation unfortunately.
71d72ece 340
f57d5f80
DHB
341RISC-V 'any' CPU type ``-cpu any`` (since 8.2)
342^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
343
344The 'any' CPU type was introduced back in 2018 and has been around since the
345initial RISC-V QEMU port. Its usage has always been unclear: users don't know
346what to expect from a CPU called 'any', and in fact the CPU does not do anything
347special that isn't already done by the default CPUs rv32/rv64.
348
349After the introduction of the 'max' CPU type, RISC-V now has a good coverage
350of generic CPUs: rv32 and rv64 as default CPUs and 'max' as a feature complete
351CPU for both 32 and 64 bit builds. Users are then discouraged to use the 'any'
352CPU type starting in 8.2.
7c8d295b 353
8043effd
DHB
354RISC-V CPU properties which start with capital 'Z' (since 8.2)
355^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
356
357All RISC-V CPU properties which start with capital 'Z' are being deprecated
358starting in 8.2. The reason is that they were wrongly added with capital 'Z'
359in the past. CPU properties were later added with lower-case names, which
360is the format we want to use from now on.
361
362Users which try to use these deprecated properties will receive a warning
363recommending to switch to their stable counterparts:
364
365- "Zifencei" should be replaced with "zifencei"
366- "Zicsr" should be replaced with "zicsr"
367- "Zihintntl" should be replaced with "zihintntl"
368- "Zihintpause" should be replaced with "zihintpause"
369- "Zawrs" should be replaced with "zawrs"
370- "Zfa" should be replaced with "zfa"
371- "Zfh" should be replaced with "zfh"
372- "Zfhmin" should be replaced with "zfhmin"
373- "Zve32f" should be replaced with "zve32f"
374- "Zve64f" should be replaced with "zve64f"
375- "Zve64d" should be replaced with "zve64d"
376
41fba161
PM
377Block device options
378''''''''''''''''''''
379
e2cc363b
YW
380``"backing": ""`` (since 2.12)
381^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
41fba161
PM
382
383In order to prevent QEMU from automatically opening an image's backing
384chain, use ``"backing": null`` instead.
385
e2cc363b
YW
386``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1)
387^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
41fba161
PM
388
389Options for ``rbd`` should be specified according to its runtime options,
390like other block drivers. Legacy parsing of keyvalue pair encoded
391filenames is useful to open images with the old format for backing files;
392These image files should be updated to use the current format.
393
394Example of legacy encoding::
395
396 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
397
398The above, converted to the current supported format::
399
400 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
401
610783cb
DB
402``iscsi,password=xxx`` (since 8.0)
403^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
404
405Specifying the iSCSI password in plain text on the command line using the
406``password`` option is insecure. The ``password-secret`` option should be
407used instead, to refer to a ``--object secret...`` instance that provides
408a password via a file, or encrypted.
409
b04c1228
MA
410Character device options
411''''''''''''''''''''''''
412
413Backend ``memory`` (since 9.0)
414^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
415
416``memory`` is a deprecated synonym for ``ringbuf``.
417
bc5e8445
RB
418CPU device properties
419'''''''''''''''''''''
420
421``pmu-num=n`` on RISC-V CPUs (since 8.2)
422^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
423
424In order to support more flexible counter configurations this has been replaced
425by a ``pmu-mask`` property. If set of counters is continuous then the mask can
426be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits
427must be left clear.
428
429
41fba161
PM
430Backwards compatibility
431-----------------------
432
e2cc363b
YW
433Runnability guarantee of CPU models (since 4.1)
434'''''''''''''''''''''''''''''''''''''''''''''''
41fba161
PM
435
436Previous versions of QEMU never changed existing CPU models in
437ways that introduced additional host software or hardware
438requirements to the VM. This allowed management software to
439safely change the machine type of an existing VM without
440introducing new requirements ("runnability guarantee"). This
441prevented CPU models from being updated to include CPU
442vulnerability mitigations, leaving guests vulnerable in the
443default configuration.
444
445The CPU model runnability guarantee won't apply anymore to
446existing CPU models. Management software that needs runnability
ac9574bc 447guarantees must resolve the CPU model aliases using the
41fba161
PM
448``alias-of`` field returned by the ``query-cpu-definitions`` QMP
449command.
450
451While those guarantees are kept, the return value of
452``query-cpu-definitions`` will have existing CPU model aliases
453point to a version that doesn't break runnability guarantees
454(specifically, version 1 of those CPU models). In future QEMU
455versions, aliases will point to newer CPU model versions
456depending on the machine type, so management software must
457resolve CPU model aliases before starting a virtual machine.
458
582a098e
TH
459QEMU guest agent
460----------------
461
462``--blacklist`` command line option (since 7.2)
463'''''''''''''''''''''''''''''''''''''''''''''''
464
465``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better
466wording for what this option does). The short form ``-b`` still stays
467the same and thus is the preferred way for scripts that should run with
468both, older and future versions of QEMU.
469
470``blacklist`` config file option (since 7.2)
471''''''''''''''''''''''''''''''''''''''''''''
472
473The ``blacklist`` config file option has been renamed to ``block-rpcs``
474(to be in sync with the renaming of the corresponding command line
475option).
7b24d326
JQ
476
477Migration
478---------
479
66db46ca
JQ
480block migration (since 8.2)
481'''''''''''''''''''''''''''
482
483Block migration is too inflexible. It needs to migrate all block
484devices or none.
485
486Please see "QMP invocation for live storage migration with
487``blockdev-mirror`` + NBD" in docs/interop/live-block-operations.rst
488for a detailed explanation.
864128df
JQ
489
490old compression method (since 8.2)
491''''''''''''''''''''''''''''''''''
492
493Compression method fails too much. Too many races. We are going to
494remove it if nobody fixes it. For starters, migration-test
6477366f 495compression tests are disabled because they fail randomly. If you need
864128df 496compression, use multifd compression methods.