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