]>
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 | ||
41fba161 PM |
26 | ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) |
27 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
28 | ||
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. | |
33 | ||
34 | Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) | |
35 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
36 | ||
37 | When not using the deprecated legacy audio config, each sound card | |
38 | should specify an ``audiodev=`` property. Additionally, when using | |
76ca4b58 | 39 | vnc, you should specify an ``audiodev=`` property if you plan to |
41fba161 PM |
40 | transmit audio through the VNC protocol. |
41 | ||
825ff029 GH |
42 | Creating sound card devices using ``-soundhw`` (since 5.1) |
43 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
44 | ||
45 | Sound card devices should be created using ``-device`` instead. The | |
46 | names are the same for most devices. The exceptions are ``hda`` which | |
47 | needs two devices (``-device intel-hda -device hda-duplex``) and | |
48 | ``pcspk`` which can be activated using ``-machine | |
49 | pcspk-audiodev=<name>``. | |
50 | ||
59652436 KW |
51 | ``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) |
52 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
53 | ||
54 | ``tty`` and ``parport`` are aliases that will be removed. Instead, the | |
55 | actual backend names ``serial`` and ``parallel`` should be used. | |
56 | ||
ccd3b3b8 PB |
57 | Short-form boolean options (since 6.0) |
58 | '''''''''''''''''''''''''''''''''''''' | |
59 | ||
60 | Boolean options such as ``share=on``/``share=off`` could be written | |
61 | in short form as ``share`` and ``noshare``. This is now deprecated | |
62 | and will cause a warning. | |
a1b40bda | 63 | |
fe636424 PB |
64 | ``delay`` option for socket character devices (since 6.0) |
65 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
66 | ||
67 | The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` | |
68 | rather than ``delay=off``. | |
69 | ||
16631029 DB |
70 | ``--enable-fips`` (since 6.0) |
71 | ''''''''''''''''''''''''''''' | |
72 | ||
73 | This option restricts usage of certain cryptographic algorithms when | |
74 | the host is operating in FIPS mode. | |
75 | ||
76 | If FIPS compliance is required, QEMU should be built with the ``libgcrypt`` | |
77 | library enabled as a cryptography provider. | |
78 | ||
79 | Neither the ``nettle`` library, or the built-in cryptography provider are | |
80 | supported on FIPS enabled hosts. | |
81 | ||
b979c931 PB |
82 | ``-writeconfig`` (since 6.0) |
83 | ''''''''''''''''''''''''''''' | |
84 | ||
85 | The ``-writeconfig`` option is not able to serialize the entire contents | |
86 | of the QEMU command line. It is thus considered a failed experiment | |
87 | and deprecated, with no current replacement. | |
88 | ||
2c933ac6 PB |
89 | Userspace local APIC with KVM (x86, since 6.0) |
90 | '''''''''''''''''''''''''''''''''''''''''''''' | |
91 | ||
92 | Using ``-M kernel-irqchip=off`` with x86 machine types that include a local | |
93 | APIC is deprecated. The ``split`` setting is supported, as is using | |
94 | ``-M kernel-irqchip=off`` with the ISA PC machine type. | |
95 | ||
f174cd33 EB |
96 | hexadecimal sizes with scaling multipliers (since 6.0) |
97 | '''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
98 | ||
99 | Input parameters that take a size value should only use a size suffix | |
100 | (such as 'k' or 'M') when the base is written in decimal, and not when | |
101 | the value is hexadecimal. That is, '0x20M' is deprecated, and should | |
102 | be written either as '32M' or as '0x2000000'. | |
103 | ||
c47c0bcb DB |
104 | ``-spice password=string`` (since 6.0) |
105 | '''''''''''''''''''''''''''''''''''''' | |
106 | ||
107 | This option is insecure because the SPICE password remains visible in | |
108 | the process listing. This is replaced by the new ``password-secret`` | |
109 | option which lets the password be securely provided on the command | |
110 | line using a ``secret`` object instance. | |
111 | ||
e2cc363b YW |
112 | ``opened`` property of ``rng-*`` objects (since 6.0) |
113 | '''''''''''''''''''''''''''''''''''''''''''''''''''' | |
6815bc1d KW |
114 | |
115 | The only effect of specifying ``opened=on`` in the command line or QMP | |
116 | ``object-add`` is that the device is opened immediately, possibly before all | |
117 | other options have been processed. This will either have no effect (if | |
118 | ``opened`` was the last option) or cause errors. The property is therefore | |
119 | useless and should not be specified. | |
120 | ||
e2cc363b YW |
121 | ``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0) |
122 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
39c4c27d KW |
123 | |
124 | The only effect of specifying ``loaded=on`` in the command line or QMP | |
125 | ``object-add`` is that the secret is loaded immediately, possibly before all | |
126 | other options have been processed. This will either have no effect (if | |
127 | ``loaded`` was the last option) or cause options to be effectively ignored as | |
128 | if they were not given. The property is therefore useless and should not be | |
129 | specified. | |
130 | ||
bb20b86d TH |
131 | ``-display sdl,window_close=...`` (since 6.1) |
132 | ''''''''''''''''''''''''''''''''''''''''''''' | |
133 | ||
134 | Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of | |
135 | an underscore between "window" and "close"). | |
136 | ||
d46156fd TH |
137 | ``-alt-grab`` and ``-display sdl,alt_grab=on`` (since 6.2) |
138 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
139 | ||
140 | Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. | |
141 | ||
142 | ``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (since 6.2) | |
143 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
144 | ||
145 | Use ``-display sdl,grab-mod=rctrl`` instead. | |
146 | ||
6695e4c0 TH |
147 | ``-sdl`` (since 6.2) |
148 | '''''''''''''''''''' | |
149 | ||
150 | Use ``-display sdl`` instead. | |
151 | ||
152 | ``-curses`` (since 6.2) | |
153 | ''''''''''''''''''''''' | |
154 | ||
155 | Use ``-display curses`` instead. | |
156 | ||
d12b64ea PB |
157 | ``-watchdog`` (since 6.2) |
158 | ''''''''''''''''''''''''' | |
159 | ||
160 | Use ``-device`` instead. | |
161 | ||
c2511b16 YW |
162 | ``-smp`` ("parameter=0" SMP configurations) (since 6.2) |
163 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
164 | ||
165 | Specified CPU topology parameters must be greater than zero. | |
166 | ||
167 | In the SMP configuration, users should either provide a CPU topology | |
168 | parameter with a reasonable value (greater than zero) or just omit it | |
169 | and QEMU will compute the missing value. | |
170 | ||
171 | However, historically it was implicitly allowed for users to provide | |
172 | a parameter with zero value, which is meaningless and could also possibly | |
173 | cause unexpected results in the -smp parsing. So support for this kind of | |
174 | configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will | |
175 | be removed in the near future, users have to ensure that all the topology | |
176 | members described with -smp are greater than zero. | |
39c4c27d | 177 | |
67f14574 MM |
178 | Plugin argument passing through ``arg=<string>`` (since 6.1) |
179 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
180 | ||
181 | Passing TCG plugins arguments through ``arg=`` is redundant is makes the | |
182 | command-line less readable, especially when the argument itself consist of a | |
183 | name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. | |
184 | Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated | |
185 | as short-form boolean values, and passed to plugins as ``arg_name=on``. | |
186 | However, short-form booleans are deprecated and full explicit ``arg_name=on`` | |
187 | form is preferred. | |
188 | ||
6b717a8d TH |
189 | ``-drive if=none`` for the sifive_u OTP device (since 6.2) |
190 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
191 | ||
192 | Using ``-drive if=none`` to configure the OTP device of the sifive_u | |
193 | RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. | |
194 | ||
67f14574 | 195 | |
41fba161 PM |
196 | QEMU Machine Protocol (QMP) commands |
197 | ------------------------------------ | |
198 | ||
e2cc363b YW |
199 | ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) |
200 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
201 | |
202 | Use argument ``id`` instead. | |
203 | ||
e2cc363b YW |
204 | ``eject`` argument ``device`` (since 2.8) |
205 | ''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
206 | |
207 | Use argument ``id`` instead. | |
208 | ||
e2cc363b YW |
209 | ``blockdev-change-medium`` argument ``device`` (since 2.8) |
210 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
211 | |
212 | Use argument ``id`` instead. | |
213 | ||
e2cc363b YW |
214 | ``block_set_io_throttle`` argument ``device`` (since 2.8) |
215 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
216 | |
217 | Use argument ``id`` instead. | |
218 | ||
e2cc363b YW |
219 | ``blockdev-add`` empty string argument ``backing`` (since 2.10) |
220 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
221 | |
222 | Use argument value ``null`` instead. | |
223 | ||
e2cc363b YW |
224 | ``block-commit`` arguments ``base`` and ``top`` (since 3.1) |
225 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
226 | |
227 | Use arguments ``base-node`` and ``top-node`` instead. | |
228 | ||
443127e8 KW |
229 | ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) |
230 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
231 | ||
232 | Use the more generic commands ``block-export-add`` and ``block-export-del`` | |
cbad81ce EB |
233 | instead. As part of this deprecation, where ``nbd-server-add`` used a |
234 | single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. | |
443127e8 | 235 | |
75ecee72 MA |
236 | ``query-qmp-schema`` return value member ``values`` (since 6.2) |
237 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
238 | ||
239 | Member ``values`` in return value elements with meta-type ``enum`` is | |
240 | deprecated. Use ``members`` instead. | |
241 | ||
1084159b VSO |
242 | ``drive-backup`` (since 6.2) |
243 | '''''''''''''''''''''''''''' | |
244 | ||
245 | Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. | |
246 | This change primarily separates the creation/opening process of the backup | |
247 | target with explicit, separate steps. ``blockdev-backup`` uses mostly the | |
248 | same arguments as ``drive-backup``, except the ``format`` and ``mode`` | |
249 | options are removed in favor of using explicit ``blockdev-create`` and | |
250 | ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for | |
251 | details. | |
252 | ||
4d8b0f0a KW |
253 | Incorrectly typed ``device_add`` arguments (since 6.2) |
254 | '''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
255 | ||
256 | Due to shortcomings in the internal implementation of ``device_add``, QEMU | |
257 | incorrectly accepts certain invalid arguments: Any object or list arguments are | |
258 | silently ignored. Other argument types are not checked, but an implicit | |
259 | conversion happens, so that e.g. string values can be assigned to integer | |
260 | device properties or vice versa. | |
261 | ||
262 | This is a bug in QEMU that will be fixed in the future so that previously | |
263 | accepted incorrect commands will return an error. Users should make sure that | |
264 | all arguments passed to ``device_add`` are consistent with the documented | |
265 | property types. | |
266 | ||
a66bd91f YZ |
267 | ``query-sgx`` return value member ``section-size`` (since 7.0) |
268 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
269 | ||
270 | Member ``section-size`` in return value elements with meta-type ``uint64`` is | |
271 | deprecated. Use ``sections`` instead. | |
272 | ||
273 | ||
274 | ``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) | |
275 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
276 | ||
277 | Member ``section-size`` in return value elements with meta-type ``uint64`` is | |
278 | deprecated. Use ``sections`` instead. | |
279 | ||
f071dc1f JY |
280 | System accelerators |
281 | ------------------- | |
282 | ||
283 | MIPS ``Trap-and-Emul`` KVM support (since 6.0) | |
284 | '''''''''''''''''''''''''''''''''''''''''''''' | |
285 | ||
286 | The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed | |
287 | from Linux upstream kernel, declare it deprecated. | |
288 | ||
41fba161 PM |
289 | System emulator CPUS |
290 | -------------------- | |
291 | ||
e2cc363b YW |
292 | ``Icelake-Client`` CPU Model (since 5.2) |
293 | '''''''''''''''''''''''''''''''''''''''' | |
3e6a015c RH |
294 | |
295 | ``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU | |
296 | Models instead. | |
297 | ||
a60442eb PMD |
298 | MIPS ``I7200`` CPU Model (since 5.2) |
299 | '''''''''''''''''''''''''''''''''''' | |
300 | ||
301 | The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated | |
302 | (the ISA has never been upstreamed to a compiler toolchain). Therefore | |
303 | this CPU is also deprecated. | |
304 | ||
d43f1670 DHB |
305 | |
306 | QEMU API (QAPI) events | |
307 | ---------------------- | |
308 | ||
309 | ``MEM_UNPLUG_ERROR`` (since 6.2) | |
310 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
311 | ||
312 | Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. | |
313 | ||
314 | ||
41fba161 PM |
315 | System emulator machines |
316 | ------------------------ | |
317 | ||
26e8bed6 TH |
318 | PPC 405 ``taihu`` machine (since 7.0) |
319 | ''''''''''''''''''''''''''''''''''''' | |
320 | ||
321 | The PPC 405 CPU is a system-on-a-chip, so all 405 machines are very similar, | |
322 | except for some external periphery. However, the periphery of the ``taihu`` | |
323 | machine is hardly emulated at all (e.g. neither the LCD nor the USB part had | |
324 | been implemented), so there is not much value added by this board. Use the | |
325 | ``ref405ep`` machine instead. | |
326 | ||
cdcf766d IM |
327 | Backend options |
328 | --------------- | |
329 | ||
330 | Using non-persistent backing file with pmem=on (since 6.1) | |
331 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
332 | ||
333 | This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM | |
334 | device. However enabling ``memory-backend-file.pmem`` option, when backing file | |
335 | is (a) not DAX capable or (b) not on a filesystem that support direct mapping | |
336 | of persistent memory, is not safe and may lead to data loss or corruption in case | |
337 | of host crash. | |
338 | Options are: | |
339 | ||
340 | - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM | |
341 | (without persistence guaranties) with backing file on non DAX storage | |
342 | - move backing file to NVDIMM storage and keep ``pmem=on`` | |
343 | (to have NVDIMM with persistence guaranties). | |
344 | ||
41fba161 PM |
345 | Device options |
346 | -------------- | |
347 | ||
348 | Emulated device options | |
349 | ''''''''''''''''''''''' | |
350 | ||
e2cc363b YW |
351 | ``-device virtio-blk,scsi=on|off`` (since 5.0) |
352 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
353 | |
354 | The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 | |
355 | and later do not support it because the virtio-scsi device was introduced for | |
356 | full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. | |
357 | ||
358 | Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an | |
359 | alias. | |
360 | ||
7c8d295b DB |
361 | ``-device sga`` (since 6.2) |
362 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
363 | ||
364 | The ``sga`` device loads an option ROM for x86 targets which enables | |
365 | SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards | |
366 | contains native support for this feature and thus use of the option | |
367 | ROM approach is obsolete. The native SeaBIOS support can be activated | |
368 | by using ``-machine graphics=off``. | |
369 | ||
370 | ||
41fba161 PM |
371 | Block device options |
372 | '''''''''''''''''''' | |
373 | ||
e2cc363b YW |
374 | ``"backing": ""`` (since 2.12) |
375 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
376 | |
377 | In order to prevent QEMU from automatically opening an image's backing | |
378 | chain, use ``"backing": null`` instead. | |
379 | ||
e2cc363b YW |
380 | ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) |
381 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
382 | |
383 | Options for ``rbd`` should be specified according to its runtime options, | |
384 | like other block drivers. Legacy parsing of keyvalue pair encoded | |
385 | filenames is useful to open images with the old format for backing files; | |
386 | These image files should be updated to use the current format. | |
387 | ||
388 | Example of legacy encoding:: | |
389 | ||
390 | json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} | |
391 | ||
392 | The above, converted to the current supported format:: | |
393 | ||
394 | json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} | |
395 | ||
0f10bf84 PM |
396 | linux-user mode CPUs |
397 | -------------------- | |
398 | ||
a60442eb PMD |
399 | MIPS ``I7200`` CPU (since 5.2) |
400 | '''''''''''''''''''''''''''''' | |
401 | ||
402 | The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated | |
403 | (the ISA has never been upstreamed to a compiler toolchain). Therefore | |
404 | this CPU is also deprecated. | |
405 | ||
41fba161 PM |
406 | Backwards compatibility |
407 | ----------------------- | |
408 | ||
e2cc363b YW |
409 | Runnability guarantee of CPU models (since 4.1) |
410 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
41fba161 PM |
411 | |
412 | Previous versions of QEMU never changed existing CPU models in | |
413 | ways that introduced additional host software or hardware | |
414 | requirements to the VM. This allowed management software to | |
415 | safely change the machine type of an existing VM without | |
416 | introducing new requirements ("runnability guarantee"). This | |
417 | prevented CPU models from being updated to include CPU | |
418 | vulnerability mitigations, leaving guests vulnerable in the | |
419 | default configuration. | |
420 | ||
421 | The CPU model runnability guarantee won't apply anymore to | |
422 | existing CPU models. Management software that needs runnability | |
ac9574bc | 423 | guarantees must resolve the CPU model aliases using the |
41fba161 PM |
424 | ``alias-of`` field returned by the ``query-cpu-definitions`` QMP |
425 | command. | |
426 | ||
427 | While those guarantees are kept, the return value of | |
428 | ``query-cpu-definitions`` will have existing CPU model aliases | |
429 | point to a version that doesn't break runnability guarantees | |
430 | (specifically, version 1 of those CPU models). In future QEMU | |
431 | versions, aliases will point to newer CPU model versions | |
432 | depending on the machine type, so management software must | |
433 | resolve CPU model aliases before starting a virtual machine. | |
434 | ||
a60442eb PMD |
435 | Guest Emulator ISAs |
436 | ------------------- | |
437 | ||
438 | nanoMIPS ISA | |
439 | '''''''''''' | |
440 | ||
441 | The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. | |
442 | As it is hard to generate binaries for it, declare it deprecated. | |
34deee7b DDAG |
443 | |
444 | Tools | |
445 | ----- | |
446 | ||
447 | virtiofsd | |
448 | ''''''''' | |
449 | ||
450 | There is a new Rust implementation of ``virtiofsd`` at | |
451 | ``https://gitlab.com/virtio-fs/virtiofsd``; | |
452 | since this is now marked stable, new development should be done on that | |
453 | rather than the existing C version in the QEMU tree. | |
454 | The C version will still accept fixes and patches that | |
455 | are already in development for the moment, but will eventually | |
456 | be deleted from this tree. | |
457 | New deployments should use the Rust version, and existing systems | |
458 | should consider moving to it. The command line and feature set | |
459 | is very close and moving should be simple. |