]>
Commit | Line | Data |
---|---|---|
44c67847 MA |
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 | ||
44c67847 MA |
20 | @section System emulator command line arguments |
21 | ||
91c082ad TH |
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 | ||
44c67847 MA |
27 | @subsection -no-kvm (since 1.3.0) |
28 | ||
976e8c54 | 29 | The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''. |
44c67847 | 30 | |
44c67847 MA |
31 | @subsection -usbdevice (since 2.10.0) |
32 | ||
33 | The ``-usbdevice DEV'' argument is now a synonym for setting | |
34 | the ``-device usb-DEV'' argument instead. The deprecated syntax | |
35 | would automatically enable USB support on the machine type. | |
36 | If using the new syntax, USB support must be explicitly | |
37 | enabled via the ``-machine usb=on'' argument. | |
38 | ||
44c67847 MA |
39 | @subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0) |
40 | ||
41 | The 'file' driver for drives is no longer appropriate for character or host | |
42 | devices and will only accept regular files (S_IFREG). The correct driver | |
43 | for these file types is 'host_cdrom' or 'host_device' as appropriate. | |
44 | ||
101625a4 TH |
45 | @subsection -net ...,name=@var{name} (since 3.1) |
46 | ||
47 | The @option{name} parameter of the @option{-net} option is a synonym | |
48 | for the @option{id} parameter, which should now be used instead. | |
49 | ||
bc1fb850 IM |
50 | @subsection -smp (invalid topologies) (since 3.1) |
51 | ||
52 | CPU topology properties should describe whole machine topology including | |
53 | possible CPUs. | |
54 | ||
55 | However, historically it was possible to start QEMU with an incorrect topology | |
56 | where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}}, | |
57 | which could lead to an incorrect topology enumeration by the guest. | |
58 | Support for invalid topologies will be removed, the user must ensure | |
59 | topologies described with -smp include all possible cpus, i.e. | |
60 | @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}. | |
61 | ||
55cf09a0 DB |
62 | @subsection -vnc acl (since 4.0.0) |
63 | ||
64 | The @code{acl} option to the @code{-vnc} argument has been replaced | |
65 | by the @code{tls-authz} and @code{sasl-authz} options. | |
66 | ||
f0b3d811 KZ |
67 | @subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0) |
68 | ||
69 | The ``-audiodev'' argument is now the preferred way to specify audio | |
70 | backend settings instead of environment variables. To ease migration to | |
71 | the new format, the ``-audiodev-help'' option can be used to convert | |
72 | the current values of the environment variables to ``-audiodev'' options. | |
73 | ||
4b3b7793 KZ |
74 | @subsection Creating sound card devices and vnc without audiodev= property (since 4.2) |
75 | ||
76 | When not using the deprecated legacy audio config, each sound card | |
77 | should specify an @code{audiodev=} property. Additionally, when using | |
78 | vnc, you should specify an @code{audiodev=} propery if you plan to | |
79 | transmit audio through the VNC protocol. | |
80 | ||
3c45f625 KW |
81 | @subsection -mon ...,control=readline,pretty=on|off (since 4.1) |
82 | ||
83 | The @code{pretty=on|off} switch has no effect for HMP monitors, but is | |
84 | silently ignored. Using the switch with HMP monitors will become an | |
85 | error in the future. | |
86 | ||
583f34c4 TH |
87 | @subsection -realtime (since 4.1) |
88 | ||
89 | The @code{-realtime mlock=on|off} argument has been replaced by the | |
90 | @code{-overcommit mem-lock=on|off} argument. | |
91 | ||
cdf80365 IM |
92 | @subsection -numa node,mem=@var{size} (since 4.1) |
93 | ||
94 | The parameter @option{mem} of @option{-numa node} is used to assign a part of | |
95 | guest RAM to a NUMA node. But when using it, it's impossible to manage specified | |
96 | RAM chunk on the host side (like bind it to a host node, setting bind policy, ...), | |
97 | so guest end-ups with the fake NUMA configuration with suboptiomal performance. | |
98 | However since 2014 there is an alternative way to assign RAM to a NUMA node | |
99 | using parameter @option{memdev}, which does the same as @option{mem} and adds | |
100 | means to actualy manage node RAM on the host side. Use parameter @option{memdev} | |
101 | with @var{memory-backend-ram} backend as an replacement for parameter @option{mem} | |
102 | to achieve the same fake NUMA effect or a properly configured | |
103 | @var{memory-backend-file} backend to actually benefit from NUMA configuration. | |
104 | In future new machine versions will not accept the option but it will still | |
105 | work with old machine types. User can check QAPI schema to see if the legacy | |
106 | option is supported by looking at MachineInfo::numa-mem-supported property. | |
107 | ||
4bb4a273 IM |
108 | @subsection -numa node (without memory specified) (since 4.1) |
109 | ||
110 | Splitting RAM by default between NUMA nodes has the same issues as @option{mem} | |
111 | parameter described above with the difference that the role of the user plays | |
112 | QEMU using implicit generic or board specific splitting rule. | |
113 | Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if | |
114 | it's supported by used machine type) to define mapping explictly instead. | |
115 | ||
fdd1bda4 AF |
116 | @subsection RISC-V -bios (since 4.1) |
117 | ||
118 | QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the | |
119 | RISC-V virt machine and sifive_u machine. | |
120 | ||
121 | QEMU 4.1 has no changes to the default behaviour to avoid breakages. This | |
122 | default will change in a future QEMU release, so please prepare now. All users | |
123 | of the virt or sifive_u machine must change their command line usage. | |
124 | ||
125 | QEMU 4.1 has three options, please migrate to one of these three: | |
126 | 1. ``-bios none`` - This is the current default behavior if no -bios option | |
127 | is included. QEMU will not automatically load any firmware. It is up | |
128 | to the user to load all the images they need. | |
129 | 2. ``-bios default`` - In a future QEMU release this will become the default | |
130 | behaviour if no -bios option is specified. This option will load the | |
131 | default OpenSBI firmware automatically. The firmware is included with | |
132 | the QEMU release and no user interaction is required. All a user needs | |
133 | to do is specify the kernel they want to boot with the -kernel option | |
134 | 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae. | |
135 | ||
fe174132 PB |
136 | @subsection -tb-size option (since 5.0) |
137 | ||
138 | QEMU 5.0 introduced an alternative syntax to specify the size of the translation | |
139 | block cache, @option{-accel tcg,tb-size=}. The new syntax deprecates the | |
140 | previously available @option{-tb-size} option. | |
141 | ||
2811ce36 GH |
142 | @subsection -show-cursor option (since 5.0) |
143 | ||
144 | Use @option{-display sdl,show-cursor=on} or | |
145 | @option{-display gtk,show-cursor=on} instead. | |
146 | ||
44c67847 MA |
147 | @section QEMU Machine Protocol (QMP) commands |
148 | ||
6d570ca1 MA |
149 | @subsection change (since 2.5.0) |
150 | ||
151 | Use ``blockdev-change-medium'' or ``change-vnc-password'' instead. | |
152 | ||
153 | @subsection migrate_set_downtime and migrate_set_speed (since 2.8.0) | |
154 | ||
155 | Use ``migrate-set-parameters'' instead. | |
156 | ||
157 | @subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0) | |
158 | ||
159 | Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead. | |
160 | ||
4db6ceb0 JS |
161 | @subsection query-block result field dirty-bitmaps[i].status (since 4.0) |
162 | ||
163 | The ``status'' field of the ``BlockDirtyInfo'' structure, returned by | |
164 | the query-block command is deprecated. Two new boolean fields, | |
165 | ``recording'' and ``busy'' effectively replace it. | |
166 | ||
590a63d5 VSO |
167 | @subsection query-block result field dirty-bitmaps (Since 4.2) |
168 | ||
169 | The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by | |
170 | the query-block command is itself now deprecated. The ``dirty-bitmaps`` | |
171 | field of the ``BlockDeviceInfo`` struct should be used instead, which is the | |
172 | type of the ``inserted`` field in query-block replies, as well as the | |
173 | type of array items in query-named-block-nodes. | |
174 | ||
175 | Since the ``dirty-bitmaps`` field is optionally present in both the old and | |
176 | new locations, clients must use introspection to learn where to anticipate | |
177 | the field if/when it does appear in command output. | |
178 | ||
44c67847 MA |
179 | @subsection query-cpus (since 2.12.0) |
180 | ||
181 | The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. | |
182 | ||
183 | @subsection query-cpus-fast "arch" output member (since 3.0.0) | |
184 | ||
185 | The ``arch'' output member of the ``query-cpus-fast'' command is | |
186 | replaced by the ``target'' output member. | |
187 | ||
c73e661f KC |
188 | @subsection cpu-add (since 4.0) |
189 | ||
190 | Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See | |
191 | documentation of ``query-hotpluggable-cpus'' for additional | |
192 | details. | |
193 | ||
9d7b7086 MA |
194 | @subsection query-events (since 4.0) |
195 | ||
196 | The ``query-events'' command has been superseded by the more powerful | |
197 | and accurate ``query-qmp-schema'' command. | |
198 | ||
a9b305ba MAL |
199 | @subsection chardev client socket with 'wait' option (since 4.0) |
200 | ||
201 | Character devices creating sockets in client mode should not specify | |
202 | the 'wait' field, which is only applicable to sockets in server mode | |
203 | ||
e9b24fb9 | 204 | @section Human Monitor Protocol (HMP) commands |
68cb29ea TH |
205 | |
206 | @subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1) | |
207 | ||
208 | The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and | |
209 | 'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}. | |
210 | ||
dc15043e | 211 | @subsection cpu-add (since 4.0) |
3800db78 KC |
212 | |
213 | Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See | |
214 | documentation of ``query-hotpluggable-cpus'' for additional details. | |
215 | ||
01438407 DB |
216 | @subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0) |
217 | ||
218 | The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and | |
219 | ``acl_remove'' commands are deprecated with no replacement. Authorization | |
220 | for VNC should be performed using the pluggable QAuthZ objects. | |
221 | ||
a101b643 AF |
222 | @section Guest Emulator ISAs |
223 | ||
224 | @subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1) | |
225 | ||
226 | The RISC-V ISA privledge specification version 1.09.1 has been deprecated. | |
227 | QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these | |
228 | should be used instead of the 1.09.1 version. | |
229 | ||
8903bf6e AF |
230 | @section System emulator CPUS |
231 | ||
232 | @subsection RISC-V ISA CPUs (since 4.1) | |
233 | ||
234 | The RISC-V cpus with the ISA version in the CPU name have been depcreated. The | |
235 | four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and | |
236 | ``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec`` | |
237 | option when using the ``rv32`` or ``rv64`` CPUs. | |
d64db71c AF |
238 | |
239 | @subsection RISC-V ISA CPUs (since 4.1) | |
240 | ||
241 | The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and | |
242 | ``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified | |
243 | via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. | |
8903bf6e | 244 | |
44c67847 MA |
245 | @section System emulator devices |
246 | ||
7d60133f JS |
247 | @subsection ide-drive (since 4.2) |
248 | ||
249 | The 'ide-drive' device is deprecated. Users should use 'ide-hd' or | |
250 | 'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed. | |
251 | ||
0d074bf8 PB |
252 | @subsection scsi-disk (since 4.2) |
253 | ||
254 | The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or | |
255 | 'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed. | |
256 | ||
44c67847 MA |
257 | @section System emulator machines |
258 | ||
2048d5d4 | 259 | @subsection mips r4k platform (since 5.0) |
d32dc614 PMD |
260 | |
261 | This machine type is very old and unmaintained. Users should use the 'malta' | |
262 | machine type instead. | |
263 | ||
30d2a17b | 264 | @subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0) |
44c67847 MA |
265 | |
266 | These machine types are very old and likely can not be used for live migration | |
267 | from old QEMU versions anymore. A newer machine type should be used instead. | |
268 | ||
cd69e3a6 AF |
269 | @subsection spike_v1.9.1 and spike_v1.10 (since 4.1) |
270 | ||
271 | The version specific Spike machines have been deprecated in favour of the | |
272 | generic ``spike`` machine. If you need to specify an older version of the RISC-V | |
273 | spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument. | |
274 | ||
44c67847 MA |
275 | @section Device options |
276 | ||
5847c750 SH |
277 | @subsection Emulated device options |
278 | ||
279 | @subsubsection -device virtio-blk,scsi=on|off (since 5.0.0) | |
280 | ||
281 | The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 | |
282 | and later do not support it because the virtio-scsi device was introduced for | |
283 | full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. | |
284 | ||
285 | Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an | |
286 | alias. | |
287 | ||
44c67847 MA |
288 | @subsection Block device options |
289 | ||
290 | @subsubsection "backing": "" (since 2.12.0) | |
291 | ||
292 | In order to prevent QEMU from automatically opening an image's backing | |
293 | chain, use ``"backing": null'' instead. | |
294 | ||
3bebd37e JC |
295 | @subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0) |
296 | ||
297 | Options for ``rbd'' should be specified according to its runtime options, | |
298 | like other block drivers. Legacy parsing of keyvalue pair encoded | |
299 | filenames is useful to open images with the old format for backing files; | |
300 | These image files should be updated to use the current format. | |
301 | ||
302 | Example of legacy encoding: | |
303 | ||
304 | @code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}} | |
305 | ||
306 | The above, converted to the current supported format: | |
307 | ||
308 | @code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}} | |
0ae2d546 EB |
309 | |
310 | @section Related binaries | |
311 | ||
ffd8e8ff KW |
312 | @subsection qemu-img convert -n -o (since 4.2.0) |
313 | ||
314 | All options specified in @option{-o} are image creation options, so | |
315 | they have no effect when used with @option{-n} to skip image creation. | |
316 | Silently ignored options can be confusing, so this combination of | |
317 | options will be made an error in future versions. | |
318 | ||
aa5b9692 EH |
319 | @section Backwards compatibility |
320 | ||
321 | @subsection Runnability guarantee of CPU models (since 4.1.0) | |
322 | ||
323 | Previous versions of QEMU never changed existing CPU models in | |
324 | ways that introduced additional host software or hardware | |
325 | requirements to the VM. This allowed management software to | |
326 | safely change the machine type of an existing VM without | |
327 | introducing new requirements ("runnability guarantee"). This | |
328 | prevented CPU models from being updated to include CPU | |
329 | vulnerability mitigations, leaving guests vulnerable in the | |
330 | default configuration. | |
331 | ||
332 | The CPU model runnability guarantee won't apply anymore to | |
333 | existing CPU models. Management software that needs runnability | |
334 | guarantees must resolve the CPU model aliases using te | |
335 | ``alias-of'' field returned by the ``query-cpu-definitions'' QMP | |
336 | command. | |
3264ffce | 337 | |
ad183928 EH |
338 | While those guarantees are kept, the return value of |
339 | ``query-cpu-definitions'' will have existing CPU model aliases | |
340 | point to a version that doesn't break runnability guarantees | |
341 | (specifically, version 1 of those CPU models). In future QEMU | |
342 | versions, aliases will point to newer CPU model versions | |
343 | depending on the machine type, so management software must | |
344 | resolve CPU model aliases before starting a virtual machine. | |
345 | ||
3264ffce JS |
346 | |
347 | @node Recently removed features | |
348 | @appendix Recently removed features | |
349 | ||
350 | What follows is a record of recently removed, formerly deprecated | |
351 | features that serves as a record for users who have encountered | |
352 | trouble after a recent upgrade. | |
353 | ||
354 | @section QEMU Machine Protocol (QMP) commands | |
355 | ||
356 | @subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0) | |
357 | ||
358 | The "autoload" parameter has been ignored since 2.12.0. All bitmaps | |
359 | are automatically loaded from qcow2 images. | |
0bc16997 EB |
360 | |
361 | @section Related binaries | |
362 | ||
363 | @subsection qemu-nbd --partition (removed in 5.0.0) | |
364 | ||
365 | The ``qemu-nbd --partition $digit'' code (also spelled @option{-P}) | |
366 | could only handle MBR partitions, and never correctly handled logical | |
367 | partitions beyond partition 5. Exporting a partition can still be | |
368 | done by utilizing the @option{--image-opts} option with a raw blockdev | |
369 | using the @code{offset} and @code{size} parameters layered on top of | |
370 | any other existing blockdev. For example, if partition 1 is 100MiB | |
371 | long starting at 1MiB, the old command: | |
372 | ||
373 | @code{qemu-nbd -t -P 1 -f qcow2 file.qcow2} | |
374 | ||
375 | can be rewritten as: | |
376 | ||
377 | @code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2} |