1 @node Deprecated features
2 @appendix Deprecated features
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 appendix. 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.
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.
17 What follows is a list of all features currently marked as
20 @section System emulator command line arguments
22 @subsection -machine enforce-config-section=on|off (since 3.1)
24 The @option{enforce-config-section} parameter is replaced by the
25 @option{-global migration.send-configuration=@var{on|off}} option.
27 @subsection -no-kvm (since 1.3.0)
29 The ``-no-kvm'' argument is now a synonym for setting
30 ``-machine accel=tcg''.
32 @subsection -usbdevice (since 2.10.0)
34 The ``-usbdevice DEV'' argument is now a synonym for setting
35 the ``-device usb-DEV'' argument instead. The deprecated syntax
36 would automatically enable USB support on the machine type.
37 If using the new syntax, USB support must be explicitly
38 enabled via the ``-machine usb=on'' argument.
40 @subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
42 The 'file' driver for drives is no longer appropriate for character or host
43 devices and will only accept regular files (S_IFREG). The correct driver
44 for these file types is 'host_cdrom' or 'host_device' as appropriate.
46 @subsection -net ...,name=@var{name} (since 3.1)
48 The @option{name} parameter of the @option{-net} option is a synonym
49 for the @option{id} parameter, which should now be used instead.
51 @subsection -smp (invalid topologies) (since 3.1)
53 CPU topology properties should describe whole machine topology including
56 However, historically it was possible to start QEMU with an incorrect topology
57 where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}},
58 which could lead to an incorrect topology enumeration by the guest.
59 Support for invalid topologies will be removed, the user must ensure
60 topologies described with -smp include all possible cpus, i.e.
61 @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
63 @subsection -vnc acl (since 4.0.0)
65 The @code{acl} option to the @code{-vnc} argument has been replaced
66 by the @code{tls-authz} and @code{sasl-authz} options.
68 @subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
70 The ``-audiodev'' argument is now the preferred way to specify audio
71 backend settings instead of environment variables. To ease migration to
72 the new format, the ``-audiodev-help'' option can be used to convert
73 the current values of the environment variables to ``-audiodev'' options.
75 @subsection -realtime (since 4.1)
77 The @code{-realtime mlock=on|off} argument has been replaced by the
78 @code{-overcommit mem-lock=on|off} argument.
80 @subsection -virtfs_synth (since 4.1)
82 The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth''
83 and ``-device virtio-9p-...'' instead.
85 @section QEMU Machine Protocol (QMP) commands
87 @subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0)
89 "autoload" parameter is now ignored. All bitmaps are automatically loaded
92 @subsection query-block result field dirty-bitmaps[i].status (since 4.0)
94 The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
95 the query-block command is deprecated. Two new boolean fields,
96 ``recording'' and ``busy'' effectively replace it.
98 @subsection query-cpus (since 2.12.0)
100 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
102 @subsection query-cpus-fast "arch" output member (since 3.0.0)
104 The ``arch'' output member of the ``query-cpus-fast'' command is
105 replaced by the ``target'' output member.
107 @subsection cpu-add (since 4.0)
109 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
110 documentation of ``query-hotpluggable-cpus'' for additional
113 @subsection query-events (since 4.0)
115 The ``query-events'' command has been superseded by the more powerful
116 and accurate ``query-qmp-schema'' command.
118 @subsection chardev client socket with 'wait' option (since 4.0)
120 Character devices creating sockets in client mode should not specify
121 the 'wait' field, which is only applicable to sockets in server mode
123 @section Human Monitor Protocol (HMP) commands
125 @subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
127 The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
128 'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
130 @subsection cpu-add (since 4.0)
132 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
133 documentation of ``query-hotpluggable-cpus'' for additional details.
135 @subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
137 The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
138 ``acl_remove'' commands are deprecated with no replacement. Authorization
139 for VNC should be performed using the pluggable QAuthZ objects.
141 @section System emulator CPUS
143 @subsection RISC-V ISA CPUs (since 4.1)
145 The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
146 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
147 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
148 option when using the ``rv32`` or ``rv64`` CPUs.
150 @section System emulator devices
152 @subsection bluetooth (since 3.1)
154 The bluetooth subsystem is unmaintained since many years and likely bitrotten
155 quite a bit. It will be removed without replacement unless some users speaks
156 up at the @email{qemu-devel@@nongnu.org} mailing list with information about
159 @section System emulator machines
161 @subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0)
163 These machine types are very old and likely can not be used for live migration
164 from old QEMU versions anymore. A newer machine type should be used instead.
166 @subsection prep (PowerPC) (since 3.1)
168 This machine type uses an unmaintained firmware, broken in lots of ways,
169 and unable to start post-2004 operating systems. 40p machine type should be
172 @section Device options
174 @subsection Block device options
176 @subsubsection "backing": "" (since 2.12.0)
178 In order to prevent QEMU from automatically opening an image's backing
179 chain, use ``"backing": null'' instead.
181 @subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
183 Options for ``rbd'' should be specified according to its runtime options,
184 like other block drivers. Legacy parsing of keyvalue pair encoded
185 filenames is useful to open images with the old format for backing files;
186 These image files should be updated to use the current format.
188 Example of legacy encoding:
190 @code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
192 The above, converted to the current supported format:
194 @code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
196 @section Related binaries
198 @subsection qemu-nbd --partition (since 4.0.0)
200 The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
201 can only handle MBR partitions, and has never correctly handled
202 logical partitions beyond partition 5. If you know the offset and
203 length of the partition (perhaps by using @code{sfdisk} within the
204 guest), you can achieve the effect of exporting just that subset of
205 the disk by use of the @option{--image-opts} option with a raw
206 blockdev using the @code{offset} and @code{size} parameters layered on
207 top of any other existing blockdev. For example, if partition 1 is
208 100MiB long starting at 1MiB, the old command:
210 @code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
214 @code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.backing.driver=file,file.backing.filename=file.qcow2}
216 Alternatively, the @code{nbdkit} project provides a more powerful
217 partition filter on top of its nbd plugin, which can be used to select
218 an arbitrary MBR or GPT partition on top of any other full-image NBD
219 export. Using this to rewrite the above example results in:
221 @code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &}
222 @code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1}
224 Note that if you are exposing the export via /dev/nbd0, it is easier
225 to just export the entire image and then mount only /dev/nbd0p1 than
226 it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a