Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-03-17' into staging
[qemu.git] / docs / system / deprecated.rst
1 Deprecated features
2 ===================
3
4 In general features are intended to be supported indefinitely once
5 introduced into QEMU. In the event that a feature needs to be removed,
6 it will be listed in this section. The feature will remain functional
7 for 2 releases prior to actual removal. Deprecated features may also
8 generate warnings on the console when QEMU starts up, or if activated
9 via a monitor command, however, this is not a mandatory requirement.
10
11 Prior to the 2.10.0 release there was no official policy on how
12 long features would be deprecated prior to their removal, nor
13 any documented list of which features were deprecated. Thus
14 any features deprecated prior to 2.10.0 will be treated as if
15 they were first deprecated in the 2.10.0 release.
16
17 What follows is a list of all features currently marked as
18 deprecated.
19
20 System emulator command line arguments
21 --------------------------------------
22
23 ``-machine enforce-config-section=on|off`` (since 3.1)
24 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
25
26 The ``enforce-config-section`` parameter is replaced by the
27 ``-global migration.send-configuration={on|off}`` option.
28
29 ``-no-kvm`` (since 1.3.0)
30 '''''''''''''''''''''''''
31
32 The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
33
34 ``-usbdevice`` (since 2.10.0)
35 '''''''''''''''''''''''''''''
36
37 The ``-usbdevice DEV`` argument is now a synonym for setting
38 the ``-device usb-DEV`` argument instead. The deprecated syntax
39 would automatically enable USB support on the machine type.
40 If using the new syntax, USB support must be explicitly
41 enabled via the ``-machine usb=on`` argument.
42
43 ``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
44 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
45
46 The 'file' driver for drives is no longer appropriate for character or host
47 devices and will only accept regular files (S_IFREG). The correct driver
48 for these file types is 'host_cdrom' or 'host_device' as appropriate.
49
50 ``-net ...,name=``\ *name* (since 3.1)
51 ''''''''''''''''''''''''''''''''''''''
52
53 The ``name`` parameter of the ``-net`` option is a synonym
54 for the ``id`` parameter, which should now be used instead.
55
56 ``-smp`` (invalid topologies) (since 3.1)
57 '''''''''''''''''''''''''''''''''''''''''
58
59 CPU topology properties should describe whole machine topology including
60 possible CPUs.
61
62 However, historically it was possible to start QEMU with an incorrect topology
63 where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
64 which could lead to an incorrect topology enumeration by the guest.
65 Support for invalid topologies will be removed, the user must ensure
66 topologies described with -smp include all possible cpus, i.e.
67 *sockets* * *cores* * *threads* = *maxcpus*.
68
69 ``-vnc acl`` (since 4.0.0)
70 ''''''''''''''''''''''''''
71
72 The ``acl`` option to the ``-vnc`` argument has been replaced
73 by the ``tls-authz`` and ``sasl-authz`` options.
74
75 ``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
76 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
77
78 The ``-audiodev`` argument is now the preferred way to specify audio
79 backend settings instead of environment variables.  To ease migration to
80 the new format, the ``-audiodev-help`` option can be used to convert
81 the current values of the environment variables to ``-audiodev`` options.
82
83 Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
84 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
85
86 When not using the deprecated legacy audio config, each sound card
87 should specify an ``audiodev=`` property.  Additionally, when using
88 vnc, you should specify an ``audiodev=`` propery if you plan to
89 transmit audio through the VNC protocol.
90
91 ``-mon ...,control=readline,pretty=on|off`` (since 4.1)
92 '''''''''''''''''''''''''''''''''''''''''''''''''''''''
93
94 The ``pretty=on|off`` switch has no effect for HMP monitors, but is
95 silently ignored. Using the switch with HMP monitors will become an
96 error in the future.
97
98 ``-realtime`` (since 4.1)
99 '''''''''''''''''''''''''
100
101 The ``-realtime mlock=on|off`` argument has been replaced by the
102 ``-overcommit mem-lock=on|off`` argument.
103
104 ``-numa node,mem=``\ *size* (since 4.1)
105 '''''''''''''''''''''''''''''''''''''''
106
107 The parameter ``mem`` of ``-numa node`` is used to assign a part of
108 guest RAM to a NUMA node. But when using it, it's impossible to manage specified
109 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
110 so guest end-ups with the fake NUMA configuration with suboptiomal performance.
111 However since 2014 there is an alternative way to assign RAM to a NUMA node
112 using parameter ``memdev``, which does the same as ``mem`` and adds
113 means to actualy manage node RAM on the host side. Use parameter ``memdev``
114 with *memory-backend-ram* backend as an replacement for parameter ``mem``
115 to achieve the same fake NUMA effect or a properly configured
116 *memory-backend-file* backend to actually benefit from NUMA configuration.
117 In future new machine versions will not accept the option but it will still
118 work with old machine types. User can check QAPI schema to see if the legacy
119 option is supported by looking at MachineInfo::numa-mem-supported property.
120
121 ``-numa`` node (without memory specified) (since 4.1)
122 '''''''''''''''''''''''''''''''''''''''''''''''''''''
123
124 Splitting RAM by default between NUMA nodes has the same issues as ``mem``
125 parameter described above with the difference that the role of the user plays
126 QEMU using implicit generic or board specific splitting rule.
127 Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
128 it's supported by used machine type) to define mapping explictly instead.
129
130 ``-mem-path`` fallback to RAM (since 4.1)
131 '''''''''''''''''''''''''''''''''''''''''
132
133 Currently if guest RAM allocation from file pointed by ``mem-path``
134 fails, QEMU falls back to allocating from RAM, which might result
135 in unpredictable behavior since the backing file specified by the user
136 is ignored. In the future, users will be responsible for making sure
137 the backing storage specified with ``-mem-path`` can actually provide
138 the guest RAM configured with ``-m`` and QEMU will fail to start up if
139 RAM allocation is unsuccessful.
140
141 RISC-V ``-bios`` (since 4.1)
142 ''''''''''''''''''''''''''''
143
144 QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
145 RISC-V virt machine and sifive_u machine.
146
147 QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
148 default will change in a future QEMU release, so please prepare now. All users
149 of the virt or sifive_u machine must change their command line usage.
150
151 QEMU 4.1 has three options, please migrate to one of these three:
152  1. ``-bios none`` - This is the current default behavior if no -bios option
153       is included. QEMU will not automatically load any firmware. It is up
154       to the user to load all the images they need.
155  2. ``-bios default`` - In a future QEMU release this will become the default
156       behaviour if no -bios option is specified. This option will load the
157       default OpenSBI firmware automatically. The firmware is included with
158       the QEMU release and no user interaction is required. All a user needs
159       to do is specify the kernel they want to boot with the -kernel option
160  3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
161
162 ``-tb-size`` option (since 5.0)
163 '''''''''''''''''''''''''''''''
164
165 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
166 block cache, ``-accel tcg,tb-size=``.  The new syntax deprecates the
167 previously available ``-tb-size`` option.
168
169 ``-show-cursor`` option (since 5.0)
170 '''''''''''''''''''''''''''''''''''
171
172 Use ``-display sdl,show-cursor=on`` or
173  ``-display gtk,show-cursor=on`` instead.
174
175 QEMU Machine Protocol (QMP) commands
176 ------------------------------------
177
178 ``change`` (since 2.5.0)
179 ''''''''''''''''''''''''
180
181 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
182
183 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0)
184 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
185
186 Use argument ``id`` instead.
187
188 ``eject`` argument ``device`` (since 2.8.0)
189 '''''''''''''''''''''''''''''''''''''''''''
190
191 Use argument ``id`` instead.
192
193 ``blockdev-change-medium`` argument ``device`` (since 2.8.0)
194 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
195
196 Use argument ``id`` instead.
197
198 ``block_set_io_throttle`` argument ``device`` (since 2.8.0)
199 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
200
201 Use argument ``id`` instead.
202
203 ``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
204 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
205
206 Use ``migrate-set-parameters`` instead.
207
208 ``query-named-block-nodes`` result ``encryption_key_missing`` (since 2.10.0)
209 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
210
211 Always false.
212
213 ``query-block`` result ``inserted.encryption_key_missing`` (since 2.10.0)
214 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
215
216 Always false.
217
218 ``blockdev-add`` empty string argument ``backing`` (since 2.10.0)
219 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
220
221 Use argument value ``null`` instead.
222
223 ``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
224 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
225
226 Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
227
228 ``block-commit`` arguments ``base`` and ``top`` (since 3.1.0)
229 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
230
231 Use arguments ``base-node`` and ``top-node`` instead.
232
233 ``object-add`` option ``props`` (since 5.0)
234 '''''''''''''''''''''''''''''''''''''''''''
235
236 Specify the properties for the object as top-level arguments instead.
237
238 ``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (since 4.0)
239 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
240
241 The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
242 these commands is deprecated. Two new boolean fields, ``recording`` and
243 ``busy`` effectively replace it.
244
245 ``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
246 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
247
248 The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
249 the query-block command is itself now deprecated. The ``dirty-bitmaps``
250 field of the ``BlockDeviceInfo`` struct should be used instead, which is the
251 type of the ``inserted`` field in query-block replies, as well as the
252 type of array items in query-named-block-nodes.
253
254 Since the ``dirty-bitmaps`` field is optionally present in both the old and
255 new locations, clients must use introspection to learn where to anticipate
256 the field if/when it does appear in command output.
257
258 ``query-cpus`` (since 2.12.0)
259 '''''''''''''''''''''''''''''
260
261 The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
262
263 ``query-cpus-fast`` ``arch`` output member (since 3.0.0)
264 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
265
266 The ``arch`` output member of the ``query-cpus-fast`` command is
267 replaced by the ``target`` output member.
268
269 ``cpu-add`` (since 4.0)
270 '''''''''''''''''''''''
271
272 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
273 documentation of ``query-hotpluggable-cpus`` for additional
274 details.
275
276 ``query-events`` (since 4.0)
277 ''''''''''''''''''''''''''''
278
279 The ``query-events`` command has been superseded by the more powerful
280 and accurate ``query-qmp-schema`` command.
281
282 chardev client socket with ``wait`` option (since 4.0)
283 ''''''''''''''''''''''''''''''''''''''''''''''''''''''
284
285 Character devices creating sockets in client mode should not specify
286 the 'wait' field, which is only applicable to sockets in server mode
287
288 Human Monitor Protocol (HMP) commands
289 -------------------------------------
290
291 ``cpu-add`` (since 4.0)
292 '''''''''''''''''''''''
293
294 Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``.  See
295 documentation of ``query-hotpluggable-cpus`` for additional details.
296
297 ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
298 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
299
300 The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
301 ``acl_remove`` commands are deprecated with no replacement. Authorization
302 for VNC should be performed using the pluggable QAuthZ objects.
303
304 Guest Emulator ISAs
305 -------------------
306
307 RISC-V ISA privledge specification version 1.09.1 (since 4.1)
308 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
309
310 The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
311 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
312 should be used instead of the 1.09.1 version.
313
314 System emulator CPUS
315 --------------------
316
317 RISC-V ISA CPUs (since 4.1)
318 '''''''''''''''''''''''''''
319
320 The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
321 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
322 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
323 option when using the ``rv32`` or ``rv64`` CPUs.
324
325 RISC-V ISA CPUs (since 4.1)
326 '''''''''''''''''''''''''''
327
328 The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
329 ``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
330 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
331
332 ``compat`` property of server class POWER CPUs (since 5.0)
333 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
334
335 The ``compat`` property used to set backwards compatibility modes for
336 the processor has been deprecated. The ``max-cpu-compat`` property of
337 the ``pseries`` machine type should be used instead.
338
339 System emulator devices
340 -----------------------
341
342 ``ide-drive`` (since 4.2)
343 '''''''''''''''''''''''''
344
345 The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
346 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
347
348 ``scsi-disk`` (since 4.2)
349 '''''''''''''''''''''''''
350
351 The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
352 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
353
354 System emulator machines
355 ------------------------
356
357 mips ``r4k`` platform (since 5.0)
358 '''''''''''''''''''''''''''''''''
359
360 This machine type is very old and unmaintained. Users should use the ``malta``
361 machine type instead.
362
363 ``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
364 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
365
366 These machine types are very old and likely can not be used for live migration
367 from old QEMU versions anymore. A newer machine type should be used instead.
368
369 ``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
370 ''''''''''''''''''''''''''''''''''''''''''''''''
371
372 The version specific Spike machines have been deprecated in favour of the
373 generic ``spike`` machine. If you need to specify an older version of the RISC-V
374 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
375
376 Device options
377 --------------
378
379 Emulated device options
380 '''''''''''''''''''''''
381
382 ``-device virtio-blk,scsi=on|off`` (since 5.0.0)
383 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
384
385 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
386 and later do not support it because the virtio-scsi device was introduced for
387 full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
388
389 Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
390 alias.
391
392 Block device options
393 ''''''''''''''''''''
394
395 ``"backing": ""`` (since 2.12.0)
396 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
397
398 In order to prevent QEMU from automatically opening an image's backing
399 chain, use ``"backing": null`` instead.
400
401 ``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
403
404 Options for ``rbd`` should be specified according to its runtime options,
405 like other block drivers.  Legacy parsing of keyvalue pair encoded
406 filenames is useful to open images with the old format for backing files;
407 These image files should be updated to use the current format.
408
409 Example of legacy encoding::
410
411   json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
412
413 The above, converted to the current supported format::
414
415   json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
416
417 Related binaries
418 ----------------
419
420 ``qemu-img convert -n -o`` (since 4.2.0)
421 ''''''''''''''''''''''''''''''''''''''''
422
423 All options specified in ``-o`` are image creation options, so
424 they have no effect when used with ``-n`` to skip image creation.
425 Silently ignored options can be confusing, so this combination of
426 options will be made an error in future versions.
427
428 Backwards compatibility
429 -----------------------
430
431 Runnability guarantee of CPU models (since 4.1.0)
432 '''''''''''''''''''''''''''''''''''''''''''''''''
433
434 Previous versions of QEMU never changed existing CPU models in
435 ways that introduced additional host software or hardware
436 requirements to the VM.  This allowed management software to
437 safely change the machine type of an existing VM without
438 introducing new requirements ("runnability guarantee").  This
439 prevented CPU models from being updated to include CPU
440 vulnerability mitigations, leaving guests vulnerable in the
441 default configuration.
442
443 The CPU model runnability guarantee won't apply anymore to
444 existing CPU models.  Management software that needs runnability
445 guarantees must resolve the CPU model aliases using te
446 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
447 command.
448
449 While those guarantees are kept, the return value of
450 ``query-cpu-definitions`` will have existing CPU model aliases
451 point to a version that doesn't break runnability guarantees
452 (specifically, version 1 of those CPU models).  In future QEMU
453 versions, aliases will point to newer CPU model versions
454 depending on the machine type, so management software must
455 resolve CPU model aliases before starting a virtual machine.
456
457
458 Recently removed features
459 =========================
460
461 What follows is a record of recently removed, formerly deprecated
462 features that serves as a record for users who have encountered
463 trouble after a recent upgrade.
464
465 QEMU Machine Protocol (QMP) commands
466 ------------------------------------
467
468 ``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
469 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
470
471 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
472 are automatically loaded from qcow2 images.
473
474 Human Monitor Protocol (HMP) commands
475 -------------------------------------
476
477 The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0)
478 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
479
480 The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
481 'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
482
483 Related binaries
484 ----------------
485
486 ``qemu-nbd --partition`` (removed in 5.0.0)
487 '''''''''''''''''''''''''''''''''''''''''''
488
489 The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
490 could only handle MBR partitions, and never correctly handled logical
491 partitions beyond partition 5.  Exporting a partition can still be
492 done by utilizing the ``--image-opts`` option with a raw blockdev
493 using the ``offset`` and ``size`` parameters layered on top of
494 any other existing blockdev. For example, if partition 1 is 100MiB
495 long starting at 1MiB, the old command::
496
497   qemu-nbd -t -P 1 -f qcow2 file.qcow2
498
499 can be rewritten as::
500
501   qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2