]>
Commit | Line | Data |
---|---|---|
7f800d34 MAL |
1 | .. _Deprecated features: |
2 | ||
41fba161 PM |
3 | Deprecated features |
4 | =================== | |
5 | ||
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, | |
ef1f5b0a SH |
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. | |
41fba161 PM |
13 | |
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. | |
19 | ||
20 | What follows is a list of all features currently marked as | |
21 | deprecated. | |
22 | ||
23 | System emulator command line arguments | |
24 | -------------------------------------- | |
25 | ||
ccd3b3b8 PB |
26 | Short-form boolean options (since 6.0) |
27 | '''''''''''''''''''''''''''''''''''''' | |
28 | ||
29 | Boolean options such as ``share=on``/``share=off`` could be written | |
30 | in short form as ``share`` and ``noshare``. This is now deprecated | |
31 | and will cause a warning. | |
a1b40bda | 32 | |
fe636424 PB |
33 | ``delay`` option for socket character devices (since 6.0) |
34 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
35 | ||
36 | The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` | |
37 | rather than ``delay=off``. | |
38 | ||
c2511b16 YW |
39 | ``-smp`` ("parameter=0" SMP configurations) (since 6.2) |
40 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
41 | ||
42 | Specified CPU topology parameters must be greater than zero. | |
43 | ||
44 | In the SMP configuration, users should either provide a CPU topology | |
45 | parameter with a reasonable value (greater than zero) or just omit it | |
46 | and QEMU will compute the missing value. | |
47 | ||
48 | However, historically it was implicitly allowed for users to provide | |
49 | a parameter with zero value, which is meaningless and could also possibly | |
50 | cause unexpected results in the -smp parsing. So support for this kind of | |
51 | configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will | |
52 | be removed in the near future, users have to ensure that all the topology | |
53 | members described with -smp are greater than zero. | |
39c4c27d | 54 | |
67f14574 MM |
55 | Plugin argument passing through ``arg=<string>`` (since 6.1) |
56 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
57 | ||
58 | Passing TCG plugins arguments through ``arg=`` is redundant is makes the | |
59 | command-line less readable, especially when the argument itself consist of a | |
60 | name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. | |
61 | Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated | |
62 | as short-form boolean values, and passed to plugins as ``arg_name=on``. | |
63 | However, short-form booleans are deprecated and full explicit ``arg_name=on`` | |
64 | form is preferred. | |
65 | ||
df37330c TH |
66 | ``-no-hpet`` (since 8.0) |
67 | '''''''''''''''''''''''' | |
68 | ||
69 | The HPET setting has been turned into a machine property. | |
70 | Use ``-machine hpet=off`` instead. | |
71 | ||
fffa36b6 TH |
72 | ``-no-acpi`` (since 8.0) |
73 | '''''''''''''''''''''''' | |
74 | ||
75 | The ``-no-acpi`` setting has been turned into a machine property. | |
76 | Use ``-machine acpi=off`` instead. | |
77 | ||
80bd81ca CI |
78 | ``-async-teardown`` (since 8.1) |
79 | ''''''''''''''''''''''''''''''' | |
80 | ||
81 | Use ``-run-with async-teardown=on`` instead. | |
82 | ||
9ffcbe2a TH |
83 | ``-chroot`` (since 8.1) |
84 | ''''''''''''''''''''''' | |
85 | ||
86 | Use ``-run-with chroot=dir`` instead. | |
87 | ||
12fd0f41 PM |
88 | ``-singlestep`` (since 8.1) |
89 | ''''''''''''''''''''''''''' | |
90 | ||
91 | The ``-singlestep`` option has been turned into an accelerator property, | |
92 | and given a name that better reflects what it actually does. | |
93 | Use ``-accel tcg,one-insn-per-tb=on`` instead. | |
94 | ||
95 | User-mode emulator command line arguments | |
96 | ----------------------------------------- | |
97 | ||
98 | ``-singlestep`` (since 8.1) | |
99 | ''''''''''''''''''''''''''' | |
100 | ||
101 | The ``-singlestep`` option has been given a name that better reflects | |
102 | what it actually does. For both linux-user and bsd-user, use the | |
103 | new ``-one-insn-per-tb`` option instead. | |
67f14574 | 104 | |
41fba161 PM |
105 | QEMU Machine Protocol (QMP) commands |
106 | ------------------------------------ | |
107 | ||
e2cc363b YW |
108 | ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) |
109 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
110 | |
111 | Use argument ``id`` instead. | |
112 | ||
e2cc363b YW |
113 | ``eject`` argument ``device`` (since 2.8) |
114 | ''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
115 | |
116 | Use argument ``id`` instead. | |
117 | ||
e2cc363b YW |
118 | ``blockdev-change-medium`` argument ``device`` (since 2.8) |
119 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
120 | |
121 | Use argument ``id`` instead. | |
122 | ||
e2cc363b YW |
123 | ``block_set_io_throttle`` argument ``device`` (since 2.8) |
124 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
125 | |
126 | Use argument ``id`` instead. | |
127 | ||
e2cc363b YW |
128 | ``blockdev-add`` empty string argument ``backing`` (since 2.10) |
129 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
130 | |
131 | Use argument value ``null`` instead. | |
132 | ||
e2cc363b YW |
133 | ``block-commit`` arguments ``base`` and ``top`` (since 3.1) |
134 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
135 | |
136 | Use arguments ``base-node`` and ``top-node`` instead. | |
137 | ||
443127e8 KW |
138 | ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) |
139 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
140 | ||
141 | Use the more generic commands ``block-export-add`` and ``block-export-del`` | |
cbad81ce EB |
142 | instead. As part of this deprecation, where ``nbd-server-add`` used a |
143 | single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. | |
443127e8 | 144 | |
75ecee72 MA |
145 | ``query-qmp-schema`` return value member ``values`` (since 6.2) |
146 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
147 | ||
148 | Member ``values`` in return value elements with meta-type ``enum`` is | |
149 | deprecated. Use ``members`` instead. | |
150 | ||
1084159b VSO |
151 | ``drive-backup`` (since 6.2) |
152 | '''''''''''''''''''''''''''' | |
153 | ||
154 | Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. | |
155 | This change primarily separates the creation/opening process of the backup | |
156 | target with explicit, separate steps. ``blockdev-backup`` uses mostly the | |
157 | same arguments as ``drive-backup``, except the ``format`` and ``mode`` | |
158 | options are removed in favor of using explicit ``blockdev-create`` and | |
159 | ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for | |
160 | details. | |
161 | ||
4d8b0f0a KW |
162 | Incorrectly typed ``device_add`` arguments (since 6.2) |
163 | '''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
164 | ||
165 | Due to shortcomings in the internal implementation of ``device_add``, QEMU | |
166 | incorrectly accepts certain invalid arguments: Any object or list arguments are | |
167 | silently ignored. Other argument types are not checked, but an implicit | |
168 | conversion happens, so that e.g. string values can be assigned to integer | |
169 | device properties or vice versa. | |
170 | ||
171 | This is a bug in QEMU that will be fixed in the future so that previously | |
172 | accepted incorrect commands will return an error. Users should make sure that | |
173 | all arguments passed to ``device_add`` are consistent with the documented | |
174 | property types. | |
175 | ||
34c18203 PM |
176 | ``StatusInfo`` member ``singlestep`` (since 8.1) |
177 | '''''''''''''''''''''''''''''''''''''''''''''''' | |
178 | ||
179 | The ``singlestep`` member of the ``StatusInfo`` returned from the | |
180 | ``query-status`` command is deprecated. This member has a confusing | |
181 | name and it never did what the documentation claimed or what its name | |
182 | suggests. We do not believe that anybody is actually using the | |
183 | information provided in this member. | |
184 | ||
185 | The information it reports is whether the TCG JIT is in "one | |
186 | instruction per translated block" mode (which can be set on the | |
187 | command line or via the HMP, but not via QMP). The information remains | |
188 | available via the HMP 'info jit' command. | |
189 | ||
1a8fc850 AB |
190 | QEMU Machine Protocol (QMP) events |
191 | ---------------------------------- | |
192 | ||
193 | ``MEM_UNPLUG_ERROR`` (since 6.2) | |
194 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
195 | ||
196 | Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. | |
197 | ||
5485e52a AB |
198 | ``vcpu`` trace events (since 8.1) |
199 | ''''''''''''''''''''''''''''''''' | |
200 | ||
201 | The ability to instrument QEMU helper functions with vCPU-aware trace | |
202 | points was removed in 7.0. However QMP still exposed the vcpu | |
203 | parameter. This argument has now been deprecated and the remaining | |
204 | remaining trace points that used it are selected just by name. | |
1a8fc850 | 205 | |
e9ccfdd9 PM |
206 | Human Monitor Protocol (HMP) commands |
207 | ------------------------------------- | |
208 | ||
209 | ``singlestep`` (since 8.1) | |
210 | '''''''''''''''''''''''''' | |
211 | ||
212 | The ``singlestep`` command has been replaced by the ``one-insn-per-tb`` | |
213 | command, which has the same behaviour but a less misleading name. | |
214 | ||
54ab3c3f AB |
215 | Host Architectures |
216 | ------------------ | |
217 | ||
218 | BE MIPS (since 7.2) | |
219 | ''''''''''''''''''' | |
220 | ||
221 | As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of | |
222 | MIPS moved out of support making it hard to maintain our | |
223 | cross-compilation CI tests of the architecture. As we no longer have | |
224 | CI coverage support may bitrot away before the deprecation process | |
225 | completes. The little endian variants of MIPS (both 32 and 64 bit) are | |
226 | still a supported host architecture. | |
227 | ||
5c27baf9 TH |
228 | System emulation on 32-bit x86 hosts (since 8.0) |
229 | '''''''''''''''''''''''''''''''''''''''''''''''' | |
230 | ||
231 | Support for 32-bit x86 host deployments is increasingly uncommon in mainstream | |
232 | OS distributions given the widespread availability of 64-bit x86 hardware. | |
233 | The QEMU project no longer considers 32-bit x86 support for system emulation to | |
234 | be an effective use of its limited resources, and thus intends to discontinue | |
235 | it. Since all recent x86 hardware from the past >10 years is capable of the | |
236 | 64-bit x86 extensions, a corresponding 64-bit OS should be used instead. | |
237 | ||
238 | ||
41fba161 PM |
239 | System emulator machines |
240 | ------------------------ | |
241 | ||
ac64ebbe PM |
242 | Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) |
243 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
5242876f JD |
244 | |
245 | The ``dtb-kaslr-seed`` property on the ``virt`` board has been | |
246 | deprecated; use the new name ``dtb-randomness`` instead. The new name | |
247 | better reflects the way this property affects all random data within | |
248 | the device tree blob, not just the ``kaslr-seed`` node. | |
249 | ||
cdcf766d IM |
250 | Backend options |
251 | --------------- | |
252 | ||
253 | Using non-persistent backing file with pmem=on (since 6.1) | |
254 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
255 | ||
256 | This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM | |
257 | device. However enabling ``memory-backend-file.pmem`` option, when backing file | |
258 | is (a) not DAX capable or (b) not on a filesystem that support direct mapping | |
259 | of persistent memory, is not safe and may lead to data loss or corruption in case | |
260 | of host crash. | |
261 | Options are: | |
262 | ||
263 | - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM | |
264 | (without persistence guaranties) with backing file on non DAX storage | |
265 | - move backing file to NVDIMM storage and keep ``pmem=on`` | |
266 | (to have NVDIMM with persistence guaranties). | |
267 | ||
41fba161 PM |
268 | Device options |
269 | -------------- | |
270 | ||
271 | Emulated device options | |
272 | ''''''''''''''''''''''' | |
273 | ||
e2cc363b YW |
274 | ``-device virtio-blk,scsi=on|off`` (since 5.0) |
275 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
276 | |
277 | The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 | |
278 | and later do not support it because the virtio-scsi device was introduced for | |
279 | full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. | |
280 | ||
281 | Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an | |
282 | alias. | |
283 | ||
36d83272 KJ |
284 | ``-device nvme-ns,eui64-default=on|off`` (since 7.1) |
285 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
286 | ||
287 | In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 | |
120f765e | 288 | identifier that is not globally unique. If an EUI-64 identifier is required, the |
36d83272 KJ |
289 | user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. |
290 | ||
8b1e59a6 KJ |
291 | ``-device nvme,use-intel-id=on|off`` (since 7.1) |
292 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
293 | ||
294 | The ``nvme`` device originally used a PCI Vendor/Device Identifier combination | |
295 | from Intel that was not properly allocated. Since version 5.2, the controller | |
296 | has used a properly allocated identifier. Deprecate the ``use-intel-id`` | |
297 | machine compatibility parameter. | |
298 | ||
adacc814 GP |
299 | ``-device cxl-type3,memdev=xxxx`` (since 8.0) |
300 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
301 | ||
302 | The ``cxl-type3`` device initially only used a single memory backend. With | |
303 | the addition of volatile memory support, it is now necessary to distinguish | |
304 | between persistent and volatile memory backends. As such, memdev is deprecated | |
305 | in favor of persistent-memdev. | |
306 | ||
71d72ece CS |
307 | ``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) |
308 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
309 | ||
310 | The 9p ``proxy`` filesystem backend driver has been deprecated and will be | |
311 | removed (along with its proxy helper daemon) in a future version of QEMU. Please | |
312 | use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem | |
313 | backend, or alternatively consider deploying virtiofsd instead. | |
314 | ||
315 | The 9p ``proxy`` backend was originally developed as an alternative to the 9p | |
316 | ``local`` backend. The idea was to enhance security by dispatching actual low | |
317 | level filesystem operations from 9p server (QEMU process) over to a separate | |
318 | process (the virtfs-proxy-helper binary). However this alternative never gained | |
319 | momentum. The proxy backend is much slower than the local backend, hasn't seen | |
320 | any development in years, and showed to be less secure, especially due to the | |
321 | fact that its helper daemon must be run as root, whereas with the local backend | |
322 | QEMU is typically run as unprivileged user and allows to tighten behaviour by | |
323 | mapping permissions et al by using its 'mapped' security model option. | |
324 | ||
325 | Nowadays it would make sense to reimplement the ``proxy`` backend by using | |
326 | QEMU's ``vhost`` feature, which would eliminate the high latency costs under | |
327 | which the 9p ``proxy`` backend currently suffers. However as of to date nobody | |
313e1629 | 328 | has indicated plans for such kind of reimplementation unfortunately. |
71d72ece | 329 | |
e9a54265 TH |
330 | ``-device pvrdma`` and the rdma subsystem (since 8.2) |
331 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
332 | ||
333 | The pvrdma device and the whole rdma subsystem are in a bad shape and | |
334 | without active maintenance. The QEMU project intends to remove this | |
335 | device and subsystem from the code base in a future release without | |
336 | replacement unless somebody steps up and improves the situation. | |
337 | ||
7c8d295b | 338 | |
41fba161 PM |
339 | Block device options |
340 | '''''''''''''''''''' | |
341 | ||
e2cc363b YW |
342 | ``"backing": ""`` (since 2.12) |
343 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
344 | |
345 | In order to prevent QEMU from automatically opening an image's backing | |
346 | chain, use ``"backing": null`` instead. | |
347 | ||
e2cc363b YW |
348 | ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) |
349 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
350 | |
351 | Options for ``rbd`` should be specified according to its runtime options, | |
352 | like other block drivers. Legacy parsing of keyvalue pair encoded | |
353 | filenames is useful to open images with the old format for backing files; | |
354 | These image files should be updated to use the current format. | |
355 | ||
356 | Example of legacy encoding:: | |
357 | ||
358 | json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} | |
359 | ||
360 | The above, converted to the current supported format:: | |
361 | ||
362 | json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} | |
363 | ||
610783cb DB |
364 | ``iscsi,password=xxx`` (since 8.0) |
365 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
366 | ||
367 | Specifying the iSCSI password in plain text on the command line using the | |
368 | ``password`` option is insecure. The ``password-secret`` option should be | |
369 | used instead, to refer to a ``--object secret...`` instance that provides | |
370 | a password via a file, or encrypted. | |
371 | ||
41fba161 PM |
372 | Backwards compatibility |
373 | ----------------------- | |
374 | ||
e2cc363b YW |
375 | Runnability guarantee of CPU models (since 4.1) |
376 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
41fba161 PM |
377 | |
378 | Previous versions of QEMU never changed existing CPU models in | |
379 | ways that introduced additional host software or hardware | |
380 | requirements to the VM. This allowed management software to | |
381 | safely change the machine type of an existing VM without | |
382 | introducing new requirements ("runnability guarantee"). This | |
383 | prevented CPU models from being updated to include CPU | |
384 | vulnerability mitigations, leaving guests vulnerable in the | |
385 | default configuration. | |
386 | ||
387 | The CPU model runnability guarantee won't apply anymore to | |
388 | existing CPU models. Management software that needs runnability | |
ac9574bc | 389 | guarantees must resolve the CPU model aliases using the |
41fba161 PM |
390 | ``alias-of`` field returned by the ``query-cpu-definitions`` QMP |
391 | command. | |
392 | ||
393 | While those guarantees are kept, the return value of | |
394 | ``query-cpu-definitions`` will have existing CPU model aliases | |
395 | point to a version that doesn't break runnability guarantees | |
396 | (specifically, version 1 of those CPU models). In future QEMU | |
397 | versions, aliases will point to newer CPU model versions | |
398 | depending on the machine type, so management software must | |
399 | resolve CPU model aliases before starting a virtual machine. | |
400 | ||
582a098e TH |
401 | QEMU guest agent |
402 | ---------------- | |
403 | ||
404 | ``--blacklist`` command line option (since 7.2) | |
405 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
406 | ||
407 | ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better | |
408 | wording for what this option does). The short form ``-b`` still stays | |
409 | the same and thus is the preferred way for scripts that should run with | |
410 | both, older and future versions of QEMU. | |
411 | ||
412 | ``blacklist`` config file option (since 7.2) | |
413 | '''''''''''''''''''''''''''''''''''''''''''' | |
414 | ||
415 | The ``blacklist`` config file option has been renamed to ``block-rpcs`` | |
416 | (to be in sync with the renaming of the corresponding command line | |
417 | option). | |
7b24d326 JQ |
418 | |
419 | Migration | |
420 | --------- | |
421 | ||
422 | ``skipped`` MigrationStats field (since 8.1) | |
423 | '''''''''''''''''''''''''''''''''''''''''''' | |
424 | ||
425 | ``skipped`` field in Migration stats has been deprecated. It hasn't | |
426 | been used for more than 10 years. | |
427 |