]>
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 | ||
bb9ecae7 AB |
23 | Build options |
24 | ------------- | |
25 | ||
26 | ``gprof`` builds (since 8.0) | |
27 | '''''''''''''''''''''''''''' | |
28 | ||
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 | |
35 | coverage. | |
36 | ||
41fba161 PM |
37 | System emulator command line arguments |
38 | -------------------------------------- | |
39 | ||
41fba161 PM |
40 | ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) |
41 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
42 | ||
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. | |
47 | ||
48 | Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) | |
49 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
50 | ||
51 | When not using the deprecated legacy audio config, each sound card | |
52 | should specify an ``audiodev=`` property. Additionally, when using | |
76ca4b58 | 53 | vnc, you should specify an ``audiodev=`` property if you plan to |
41fba161 PM |
54 | transmit audio through the VNC protocol. |
55 | ||
ccd3b3b8 PB |
56 | Short-form boolean options (since 6.0) |
57 | '''''''''''''''''''''''''''''''''''''' | |
58 | ||
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. | |
a1b40bda | 62 | |
fe636424 PB |
63 | ``delay`` option for socket character devices (since 6.0) |
64 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
65 | ||
66 | The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` | |
67 | rather than ``delay=off``. | |
68 | ||
c47c0bcb DB |
69 | ``-spice password=string`` (since 6.0) |
70 | '''''''''''''''''''''''''''''''''''''' | |
71 | ||
72 | This option is insecure because the SPICE password remains visible in | |
73 | the process listing. This is replaced by the new ``password-secret`` | |
74 | option which lets the password be securely provided on the command | |
75 | line using a ``secret`` object instance. | |
76 | ||
c2511b16 YW |
77 | ``-smp`` ("parameter=0" SMP configurations) (since 6.2) |
78 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
79 | ||
80 | Specified CPU topology parameters must be greater than zero. | |
81 | ||
82 | In the SMP configuration, users should either provide a CPU topology | |
83 | parameter with a reasonable value (greater than zero) or just omit it | |
84 | and QEMU will compute the missing value. | |
85 | ||
86 | However, historically it was implicitly allowed for users to provide | |
87 | a parameter with zero value, which is meaningless and could also possibly | |
88 | cause unexpected results in the -smp parsing. So support for this kind of | |
89 | configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will | |
90 | be removed in the near future, users have to ensure that all the topology | |
91 | members described with -smp are greater than zero. | |
39c4c27d | 92 | |
67f14574 MM |
93 | Plugin argument passing through ``arg=<string>`` (since 6.1) |
94 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
95 | ||
96 | Passing TCG plugins arguments through ``arg=`` is redundant is makes the | |
97 | command-line less readable, especially when the argument itself consist of a | |
98 | name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. | |
99 | Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated | |
100 | as short-form boolean values, and passed to plugins as ``arg_name=on``. | |
101 | However, short-form booleans are deprecated and full explicit ``arg_name=on`` | |
102 | form is preferred. | |
103 | ||
df37330c TH |
104 | ``-no-hpet`` (since 8.0) |
105 | '''''''''''''''''''''''' | |
106 | ||
107 | The HPET setting has been turned into a machine property. | |
108 | Use ``-machine hpet=off`` instead. | |
109 | ||
90c167a1 TH |
110 | ``-accel hax`` (since 8.0) |
111 | '''''''''''''''''''''''''' | |
112 | ||
113 | The HAXM project has been retired (see https://github.com/intel/haxm#status). | |
114 | Use "whpx" (on Windows) or "hvf" (on macOS) instead. | |
115 | ||
67f14574 | 116 | |
41fba161 PM |
117 | QEMU Machine Protocol (QMP) commands |
118 | ------------------------------------ | |
119 | ||
e2cc363b YW |
120 | ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) |
121 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
122 | |
123 | Use argument ``id`` instead. | |
124 | ||
e2cc363b YW |
125 | ``eject`` argument ``device`` (since 2.8) |
126 | ''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
127 | |
128 | Use argument ``id`` instead. | |
129 | ||
e2cc363b YW |
130 | ``blockdev-change-medium`` argument ``device`` (since 2.8) |
131 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
132 | |
133 | Use argument ``id`` instead. | |
134 | ||
e2cc363b YW |
135 | ``block_set_io_throttle`` argument ``device`` (since 2.8) |
136 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
137 | |
138 | Use argument ``id`` instead. | |
139 | ||
e2cc363b YW |
140 | ``blockdev-add`` empty string argument ``backing`` (since 2.10) |
141 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
142 | |
143 | Use argument value ``null`` instead. | |
144 | ||
e2cc363b YW |
145 | ``block-commit`` arguments ``base`` and ``top`` (since 3.1) |
146 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
73756ae3 MA |
147 | |
148 | Use arguments ``base-node`` and ``top-node`` instead. | |
149 | ||
443127e8 KW |
150 | ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) |
151 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
152 | ||
153 | Use the more generic commands ``block-export-add`` and ``block-export-del`` | |
cbad81ce EB |
154 | instead. As part of this deprecation, where ``nbd-server-add`` used a |
155 | single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. | |
443127e8 | 156 | |
75ecee72 MA |
157 | ``query-qmp-schema`` return value member ``values`` (since 6.2) |
158 | ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
159 | ||
160 | Member ``values`` in return value elements with meta-type ``enum`` is | |
161 | deprecated. Use ``members`` instead. | |
162 | ||
1084159b VSO |
163 | ``drive-backup`` (since 6.2) |
164 | '''''''''''''''''''''''''''' | |
165 | ||
166 | Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. | |
167 | This change primarily separates the creation/opening process of the backup | |
168 | target with explicit, separate steps. ``blockdev-backup`` uses mostly the | |
169 | same arguments as ``drive-backup``, except the ``format`` and ``mode`` | |
170 | options are removed in favor of using explicit ``blockdev-create`` and | |
171 | ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for | |
172 | details. | |
173 | ||
4d8b0f0a KW |
174 | Incorrectly typed ``device_add`` arguments (since 6.2) |
175 | '''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
176 | ||
177 | Due to shortcomings in the internal implementation of ``device_add``, QEMU | |
178 | incorrectly accepts certain invalid arguments: Any object or list arguments are | |
179 | silently ignored. Other argument types are not checked, but an implicit | |
180 | conversion happens, so that e.g. string values can be assigned to integer | |
181 | device properties or vice versa. | |
182 | ||
183 | This is a bug in QEMU that will be fixed in the future so that previously | |
184 | accepted incorrect commands will return an error. Users should make sure that | |
185 | all arguments passed to ``device_add`` are consistent with the documented | |
186 | property types. | |
187 | ||
54ab3c3f AB |
188 | Host Architectures |
189 | ------------------ | |
190 | ||
191 | BE MIPS (since 7.2) | |
192 | ''''''''''''''''''' | |
193 | ||
194 | As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of | |
195 | MIPS moved out of support making it hard to maintain our | |
196 | cross-compilation CI tests of the architecture. As we no longer have | |
197 | CI coverage support may bitrot away before the deprecation process | |
198 | completes. The little endian variants of MIPS (both 32 and 64 bit) are | |
199 | still a supported host architecture. | |
200 | ||
d43f1670 DHB |
201 | QEMU API (QAPI) events |
202 | ---------------------- | |
203 | ||
204 | ``MEM_UNPLUG_ERROR`` (since 6.2) | |
205 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
206 | ||
207 | Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. | |
208 | ||
209 | ||
41fba161 PM |
210 | System emulator machines |
211 | ------------------------ | |
212 | ||
5242876f JD |
213 | Arm ``virt`` machine ``dtb-kaslr-seed`` property |
214 | '''''''''''''''''''''''''''''''''''''''''''''''' | |
215 | ||
216 | The ``dtb-kaslr-seed`` property on the ``virt`` board has been | |
217 | deprecated; use the new name ``dtb-randomness`` instead. The new name | |
218 | better reflects the way this property affects all random data within | |
219 | the device tree blob, not just the ``kaslr-seed`` node. | |
220 | ||
f59fb188 TH |
221 | ``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) |
222 | ''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
223 | ||
224 | These old machine types are quite neglected nowadays and thus might have | |
225 | various pitfalls with regards to live migration. Use a newer machine type | |
226 | instead. | |
227 | ||
228 | ||
cdcf766d IM |
229 | Backend options |
230 | --------------- | |
231 | ||
232 | Using non-persistent backing file with pmem=on (since 6.1) | |
233 | '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | |
234 | ||
235 | This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM | |
236 | device. However enabling ``memory-backend-file.pmem`` option, when backing file | |
237 | is (a) not DAX capable or (b) not on a filesystem that support direct mapping | |
238 | of persistent memory, is not safe and may lead to data loss or corruption in case | |
239 | of host crash. | |
240 | Options are: | |
241 | ||
242 | - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM | |
243 | (without persistence guaranties) with backing file on non DAX storage | |
244 | - move backing file to NVDIMM storage and keep ``pmem=on`` | |
245 | (to have NVDIMM with persistence guaranties). | |
246 | ||
41fba161 PM |
247 | Device options |
248 | -------------- | |
249 | ||
250 | Emulated device options | |
251 | ''''''''''''''''''''''' | |
252 | ||
e2cc363b YW |
253 | ``-device virtio-blk,scsi=on|off`` (since 5.0) |
254 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
255 | |
256 | The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 | |
257 | and later do not support it because the virtio-scsi device was introduced for | |
258 | full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. | |
259 | ||
260 | Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an | |
261 | alias. | |
262 | ||
36d83272 KJ |
263 | ``-device nvme-ns,eui64-default=on|off`` (since 7.1) |
264 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
265 | ||
266 | In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 | |
120f765e | 267 | identifier that is not globally unique. If an EUI-64 identifier is required, the |
36d83272 KJ |
268 | user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. |
269 | ||
8b1e59a6 KJ |
270 | ``-device nvme,use-intel-id=on|off`` (since 7.1) |
271 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
272 | ||
273 | The ``nvme`` device originally used a PCI Vendor/Device Identifier combination | |
274 | from Intel that was not properly allocated. Since version 5.2, the controller | |
275 | has used a properly allocated identifier. Deprecate the ``use-intel-id`` | |
276 | machine compatibility parameter. | |
277 | ||
7c8d295b | 278 | |
41fba161 PM |
279 | Block device options |
280 | '''''''''''''''''''' | |
281 | ||
e2cc363b YW |
282 | ``"backing": ""`` (since 2.12) |
283 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
284 | |
285 | In order to prevent QEMU from automatically opening an image's backing | |
286 | chain, use ``"backing": null`` instead. | |
287 | ||
e2cc363b YW |
288 | ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) |
289 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
41fba161 PM |
290 | |
291 | Options for ``rbd`` should be specified according to its runtime options, | |
292 | like other block drivers. Legacy parsing of keyvalue pair encoded | |
293 | filenames is useful to open images with the old format for backing files; | |
294 | These image files should be updated to use the current format. | |
295 | ||
296 | Example of legacy encoding:: | |
297 | ||
298 | json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} | |
299 | ||
300 | The above, converted to the current supported format:: | |
301 | ||
302 | json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} | |
303 | ||
41fba161 PM |
304 | Backwards compatibility |
305 | ----------------------- | |
306 | ||
e2cc363b YW |
307 | Runnability guarantee of CPU models (since 4.1) |
308 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
41fba161 PM |
309 | |
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. | |
318 | ||
319 | The CPU model runnability guarantee won't apply anymore to | |
320 | existing CPU models. Management software that needs runnability | |
ac9574bc | 321 | guarantees must resolve the CPU model aliases using the |
41fba161 PM |
322 | ``alias-of`` field returned by the ``query-cpu-definitions`` QMP |
323 | command. | |
324 | ||
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. | |
332 | ||
34deee7b DDAG |
333 | Tools |
334 | ----- | |
335 | ||
336 | virtiofsd | |
337 | ''''''''' | |
338 | ||
339 | There is a new Rust implementation of ``virtiofsd`` at | |
340 | ``https://gitlab.com/virtio-fs/virtiofsd``; | |
341 | since this is now marked stable, new development should be done on that | |
342 | rather than the existing C version in the QEMU tree. | |
343 | The C version will still accept fixes and patches that | |
344 | are already in development for the moment, but will eventually | |
345 | be deleted from this tree. | |
346 | New deployments should use the Rust version, and existing systems | |
347 | should consider moving to it. The command line and feature set | |
348 | is very close and moving should be simple. | |
582a098e TH |
349 | |
350 | ||
351 | QEMU guest agent | |
352 | ---------------- | |
353 | ||
354 | ``--blacklist`` command line option (since 7.2) | |
355 | ''''''''''''''''''''''''''''''''''''''''''''''' | |
356 | ||
357 | ``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better | |
358 | wording for what this option does). The short form ``-b`` still stays | |
359 | the same and thus is the preferred way for scripts that should run with | |
360 | both, older and future versions of QEMU. | |
361 | ||
362 | ``blacklist`` config file option (since 7.2) | |
363 | '''''''''''''''''''''''''''''''''''''''''''' | |
364 | ||
365 | The ``blacklist`` config file option has been renamed to ``block-rpcs`` | |
366 | (to be in sync with the renaming of the corresponding command line | |
367 | option). |