Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20190714' into staging
[qemu/ar7.git] / qemu-deprecated.texi
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
18 deprecated.
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
54 possible CPUs.
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 -mon ...,control=readline,pretty=on|off (since 4.1)
77 The @code{pretty=on|off} switch has no effect for HMP monitors, but is
78 silently ignored. Using the switch with HMP monitors will become an
79 error in the future.
81 @subsection -realtime (since 4.1)
83 The @code{-realtime mlock=on|off} argument has been replaced by the
84 @code{-overcommit mem-lock=on|off} argument.
86 @subsection -virtfs_synth (since 4.1)
88 The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth''
89 and ``-device virtio-9p-...'' instead.
91 @subsection -numa node,mem=@var{size} (since 4.1)
93 The parameter @option{mem} of @option{-numa node} is used to assign a part of
94 guest RAM to a NUMA node. But when using it, it's impossible to manage specified
95 RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
96 so guest end-ups with the fake NUMA configuration with suboptiomal performance.
97 However since 2014 there is an alternative way to assign RAM to a NUMA node
98 using parameter @option{memdev}, which does the same as @option{mem} and adds
99 means to actualy manage node RAM on the host side. Use parameter @option{memdev}
100 with @var{memory-backend-ram} backend as an replacement for parameter @option{mem}
101 to achieve the same fake NUMA effect or a properly configured
102 @var{memory-backend-file} backend to actually benefit from NUMA configuration.
103 In future new machine versions will not accept the option but it will still
104 work with old machine types. User can check QAPI schema to see if the legacy
105 option is supported by looking at MachineInfo::numa-mem-supported property.
107 @subsection -numa node (without memory specified) (since 4.1)
109 Splitting RAM by default between NUMA nodes has the same issues as @option{mem}
110 parameter described above with the difference that the role of the user plays
111 QEMU using implicit generic or board specific splitting rule.
112 Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if
113 it's supported by used machine type) to define mapping explictly instead.
115 @subsection -mem-path fallback to RAM (since 4.1)
116 Currently if guest RAM allocation from file pointed by @option{mem-path}
117 fails, QEMU falls back to allocating from RAM, which might result
118 in unpredictable behavior since the backing file specified by the user
119 is ignored. In the future, users will be responsible for making sure
120 the backing storage specified with @option{-mem-path} can actually provide
121 the guest RAM configured with @option{-m} and QEMU will fail to start up if
122 RAM allocation is unsuccessful.
124 @section QEMU Machine Protocol (QMP) commands
126 @subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0)
128 "autoload" parameter is now ignored. All bitmaps are automatically loaded
129 from qcow2 images.
131 @subsection query-block result field dirty-bitmaps[i].status (since 4.0)
133 The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
134 the query-block command is deprecated. Two new boolean fields,
135 ``recording'' and ``busy'' effectively replace it.
137 @subsection query-cpus (since 2.12.0)
139 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
141 @subsection query-cpus-fast "arch" output member (since 3.0.0)
143 The ``arch'' output member of the ``query-cpus-fast'' command is
144 replaced by the ``target'' output member.
146 @subsection cpu-add (since 4.0)
148 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
149 documentation of ``query-hotpluggable-cpus'' for additional
150 details.
152 @subsection query-events (since 4.0)
154 The ``query-events'' command has been superseded by the more powerful
155 and accurate ``query-qmp-schema'' command.
157 @subsection chardev client socket with 'wait' option (since 4.0)
159 Character devices creating sockets in client mode should not specify
160 the 'wait' field, which is only applicable to sockets in server mode
162 @section Human Monitor Protocol (HMP) commands
164 @subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
166 The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
167 'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
169 @subsection cpu-add (since 4.0)
171 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
172 documentation of ``query-hotpluggable-cpus'' for additional details.
174 @subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
176 The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
177 ``acl_remove'' commands are deprecated with no replacement. Authorization
178 for VNC should be performed using the pluggable QAuthZ objects.
180 @section Guest Emulator ISAs
182 @subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
184 The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
185 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
186 should be used instead of the 1.09.1 version.
188 @section System emulator CPUS
190 @subsection RISC-V ISA CPUs (since 4.1)
192 The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
193 four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
194 ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
195 option when using the ``rv32`` or ``rv64`` CPUs.
197 @subsection RISC-V ISA CPUs (since 4.1)
199 The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
200 ``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
201 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
203 @section System emulator devices
205 @subsection bluetooth (since 3.1)
207 The bluetooth subsystem is unmaintained since many years and likely bitrotten
208 quite a bit. It will be removed without replacement unless some users speaks
209 up at the @email{} mailing list with information about
210 their usecases.
212 @section System emulator machines
214 @subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0)
216 These machine types are very old and likely can not be used for live migration
217 from old QEMU versions anymore. A newer machine type should be used instead.
219 @subsection prep (PowerPC) (since 3.1)
221 This machine type uses an unmaintained firmware, broken in lots of ways,
222 and unable to start post-2004 operating systems. 40p machine type should be
223 used instead.
225 @subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
227 The version specific Spike machines have been deprecated in favour of the
228 generic ``spike`` machine. If you need to specify an older version of the RISC-V
229 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
231 @section Device options
233 @subsection Block device options
235 @subsubsection "backing": "" (since 2.12.0)
237 In order to prevent QEMU from automatically opening an image's backing
238 chain, use ``"backing": null'' instead.
240 @subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
242 Options for ``rbd'' should be specified according to its runtime options,
243 like other block drivers.  Legacy parsing of keyvalue pair encoded
244 filenames is useful to open images with the old format for backing files;
245 These image files should be updated to use the current format.
247 Example of legacy encoding:
249 @code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
251 The above, converted to the current supported format:
253 @code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
255 @section Related binaries
257 @subsection qemu-nbd --partition (since 4.0.0)
259 The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
260 can only handle MBR partitions, and has never correctly handled
261 logical partitions beyond partition 5.  If you know the offset and
262 length of the partition (perhaps by using @code{sfdisk} within the
263 guest), you can achieve the effect of exporting just that subset of
264 the disk by use of the @option{--image-opts} option with a raw
265 blockdev using the @code{offset} and @code{size} parameters layered on
266 top of any other existing blockdev. For example, if partition 1 is
267 100MiB long starting at 1MiB, the old command:
269 @code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
271 can be rewritten as:
273 @code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.backing.driver=file,file.backing.filename=file.qcow2}
275 Alternatively, the @code{nbdkit} project provides a more powerful
276 partition filter on top of its nbd plugin, which can be used to select
277 an arbitrary MBR or GPT partition on top of any other full-image NBD
278 export.  Using this to rewrite the above example results in:
280 @code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &}
281 @code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1}
283 Note that if you are exposing the export via /dev/nbd0, it is easier
284 to just export the entire image and then mount only /dev/nbd0p1 than
285 it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a
286 subset of the image.
288 @section Build system
290 @subsection Python 2 support (since 4.1.0)
292 In the future, QEMU will require Python 3 to be available at
293 build time.  Support for Python 2 in scripts shipped with QEMU
294 is deprecated.
296 @section Backwards compatibility
298 @subsection Runnability guarantee of CPU models (since 4.1.0)
300 Previous versions of QEMU never changed existing CPU models in
301 ways that introduced additional host software or hardware
302 requirements to the VM.  This allowed management software to
303 safely change the machine type of an existing VM without
304 introducing new requirements ("runnability guarantee").  This
305 prevented CPU models from being updated to include CPU
306 vulnerability mitigations, leaving guests vulnerable in the
307 default configuration.
309 The CPU model runnability guarantee won't apply anymore to
310 existing CPU models.  Management software that needs runnability
311 guarantees must resolve the CPU model aliases using te
312 ``alias-of'' field returned by the ``query-cpu-definitions'' QMP
313 command.