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