]> git.proxmox.com Git - mirror_qemu.git/blob - qemu-deprecated.texi
Merge tag 'pull-aspeed-20240201' of https://github.com/legoater/qemu into staging
[mirror_qemu.git] / qemu-deprecated.texi
1 @node Deprecated features
2 @appendix Deprecated features
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 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.
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 @section System emulator command line arguments
21
22 @subsection -machine enforce-config-section=on|off (since 3.1)
23
24 The @option{enforce-config-section} parameter is replaced by the
25 @option{-global migration.send-configuration=@var{on|off}} option.
26
27 @subsection -no-kvm (since 1.3.0)
28
29 The ``-no-kvm'' argument is now a synonym for setting
30 ``-machine accel=tcg''.
31
32 @subsection -usbdevice (since 2.10.0)
33
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.
39
40 @subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
41
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.
45
46 @subsection -net ...,name=@var{name} (since 3.1)
47
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.
50
51 @subsection -smp (invalid topologies) (since 3.1)
52
53 CPU topology properties should describe whole machine topology including
54 possible CPUs.
55
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}}.
62
63 @subsection -vnc acl (since 4.0.0)
64
65 The @code{acl} option to the @code{-vnc} argument has been replaced
66 by the @code{tls-authz} and @code{sasl-authz} options.
67
68 @subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
69
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.
74
75 @subsection -mon ...,control=readline,pretty=on|off (since 4.1)
76
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.
80
81 @subsection -realtime (since 4.1)
82
83 The @code{-realtime mlock=on|off} argument has been replaced by the
84 @code{-overcommit mem-lock=on|off} argument.
85
86 @subsection -virtfs_synth (since 4.1)
87
88 The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth''
89 and ``-device virtio-9p-...'' instead.
90
91 @subsection -numa node,mem=@var{size} (since 4.1)
92
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.
106
107 @subsection -numa node (without memory specified) (since 4.1)
108
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.
114
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.
123
124 @section QEMU Machine Protocol (QMP) commands
125
126 @subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0)
127
128 "autoload" parameter is now ignored. All bitmaps are automatically loaded
129 from qcow2 images.
130
131 @subsection query-block result field dirty-bitmaps[i].status (since 4.0)
132
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.
136
137 @subsection query-cpus (since 2.12.0)
138
139 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
140
141 @subsection query-cpus-fast "arch" output member (since 3.0.0)
142
143 The ``arch'' output member of the ``query-cpus-fast'' command is
144 replaced by the ``target'' output member.
145
146 @subsection cpu-add (since 4.0)
147
148 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
149 documentation of ``query-hotpluggable-cpus'' for additional
150 details.
151
152 @subsection query-events (since 4.0)
153
154 The ``query-events'' command has been superseded by the more powerful
155 and accurate ``query-qmp-schema'' command.
156
157 @subsection chardev client socket with 'wait' option (since 4.0)
158
159 Character devices creating sockets in client mode should not specify
160 the 'wait' field, which is only applicable to sockets in server mode
161
162 @section Human Monitor Protocol (HMP) commands
163
164 @subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
165
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}.
168
169 @subsection cpu-add (since 4.0)
170
171 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
172 documentation of ``query-hotpluggable-cpus'' for additional details.
173
174 @subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
175
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.
179
180 @section Guest Emulator ISAs
181
182 @subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
183
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.
187
188 @section System emulator CPUS
189
190 @subsection RISC-V ISA CPUs (since 4.1)
191
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.
196
197 @subsection RISC-V ISA CPUs (since 4.1)
198
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.
202
203 @section System emulator devices
204
205 @subsection bluetooth (since 3.1)
206
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{qemu-devel@@nongnu.org} mailing list with information about
210 their usecases.
211
212 @section System emulator machines
213
214 @subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0)
215
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.
218
219 @subsection prep (PowerPC) (since 3.1)
220
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.
224
225 @subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
226
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.
230
231 @section Device options
232
233 @subsection Block device options
234
235 @subsubsection "backing": "" (since 2.12.0)
236
237 In order to prevent QEMU from automatically opening an image's backing
238 chain, use ``"backing": null'' instead.
239
240 @subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
241
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.
246
247 Example of legacy encoding:
248
249 @code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
250
251 The above, converted to the current supported format:
252
253 @code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
254
255 @section Related binaries
256
257 @subsection qemu-nbd --partition (since 4.0.0)
258
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:
268
269 @code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
270
271 can be rewritten as:
272
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}
274
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:
279
280 @code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &}
281 @code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1}
282
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.
287
288 @section Build system
289
290 @subsection Python 2 support (since 4.1.0)
291
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.
295
296 @section Backwards compatibility
297
298 @subsection Runnability guarantee of CPU models (since 4.1.0)
299
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.
308
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.