blob: 2634e00ec8260e9f29b7d90659a9a068c7321111 [file] [log] [blame]
Markus Armbruster44c67842018-07-16 09:32:25 +02001@node Deprecated features
2@appendix Deprecated features
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 appendix. 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
Markus Armbruster44c67842018-07-16 09:32:25 +020020@section System emulator command line arguments
21
Thomas Huth91c082a2018-09-20 09:22:07 +020022@subsection -machine enforce-config-section=on|off (since 3.1)
23
24The @option{enforce-config-section} parameter is replaced by the
25@option{-global migration.send-configuration=@var{on|off}} option.
26
Markus Armbruster44c67842018-07-16 09:32:25 +020027@subsection -no-kvm (since 1.3.0)
28
Thomas Huth976e8c52019-09-04 07:27:39 +020029The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''.
Markus Armbruster44c67842018-07-16 09:32:25 +020030
Markus Armbruster44c67842018-07-16 09:32:25 +020031@subsection -usbdevice (since 2.10.0)
32
33The ``-usbdevice DEV'' argument is now a synonym for setting
34the ``-device usb-DEV'' argument instead. The deprecated syntax
35would automatically enable USB support on the machine type.
36If using the new syntax, USB support must be explicitly
37enabled via the ``-machine usb=on'' argument.
38
Markus Armbruster44c67842018-07-16 09:32:25 +020039@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
40
41The 'file' driver for drives is no longer appropriate for character or host
42devices and will only accept regular files (S_IFREG). The correct driver
43for these file types is 'host_cdrom' or 'host_device' as appropriate.
44
Thomas Huth101625a2018-09-20 10:14:08 +020045@subsection -net ...,name=@var{name} (since 3.1)
46
47The @option{name} parameter of the @option{-net} option is a synonym
48for the @option{id} parameter, which should now be used instead.
49
Igor Mammedovbc1fb852018-09-13 13:06:01 +020050@subsection -smp (invalid topologies) (since 3.1)
51
52CPU topology properties should describe whole machine topology including
53possible CPUs.
54
55However, historically it was possible to start QEMU with an incorrect topology
56where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}},
57which could lead to an incorrect topology enumeration by the guest.
58Support for invalid topologies will be removed, the user must ensure
59topologies described with -smp include all possible cpus, i.e.
60 @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
61
Daniel P. Berrange55cf09a2019-02-27 14:57:54 +000062@subsection -vnc acl (since 4.0.0)
63
64The @code{acl} option to the @code{-vnc} argument has been replaced
65by the @code{tls-authz} and @code{sasl-authz} options.
66
Kővágó, Zoltánf0b3d812019-03-08 23:34:14 +010067@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
68
69The ``-audiodev'' argument is now the preferred way to specify audio
70backend settings instead of environment variables. To ease migration to
71the new format, the ``-audiodev-help'' option can be used to convert
72the current values of the environment variables to ``-audiodev'' options.
73
Kővágó, Zoltán4b3b7792019-08-26 21:59:02 +020074@subsection Creating sound card devices and vnc without audiodev= property (since 4.2)
75
76When not using the deprecated legacy audio config, each sound card
77should specify an @code{audiodev=} property. Additionally, when using
78vnc, you should specify an @code{audiodev=} propery if you plan to
79transmit audio through the VNC protocol.
80
Kevin Wolf3c45f622019-06-13 17:34:05 +020081@subsection -mon ...,control=readline,pretty=on|off (since 4.1)
82
83The @code{pretty=on|off} switch has no effect for HMP monitors, but is
84silently ignored. Using the switch with HMP monitors will become an
85error in the future.
86
Thomas Huth583f34c2019-04-11 19:53:45 +020087@subsection -realtime (since 4.1)
88
89The @code{-realtime mlock=on|off} argument has been replaced by the
90@code{-overcommit mem-lock=on|off} argument.
91
Igor Mammedovcdf80362019-05-30 10:33:18 +020092@subsection -numa node,mem=@var{size} (since 4.1)
93
94The parameter @option{mem} of @option{-numa node} is used to assign a part of
95guest RAM to a NUMA node. But when using it, it's impossible to manage specified
96RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
97so guest end-ups with the fake NUMA configuration with suboptiomal performance.
98However since 2014 there is an alternative way to assign RAM to a NUMA node
99using parameter @option{memdev}, which does the same as @option{mem} and adds
100means to actualy manage node RAM on the host side. Use parameter @option{memdev}
101with @var{memory-backend-ram} backend as an replacement for parameter @option{mem}
102to achieve the same fake NUMA effect or a properly configured
103@var{memory-backend-file} backend to actually benefit from NUMA configuration.
104In future new machine versions will not accept the option but it will still
105work with old machine types. User can check QAPI schema to see if the legacy
106option is supported by looking at MachineInfo::numa-mem-supported property.
107
Igor Mammedov4bb4a272019-05-30 10:33:19 +0200108@subsection -numa node (without memory specified) (since 4.1)
109
110Splitting RAM by default between NUMA nodes has the same issues as @option{mem}
111parameter described above with the difference that the role of the user plays
112QEMU using implicit generic or board specific splitting rule.
113Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if
114it's supported by used machine type) to define mapping explictly instead.
115
Igor Mammedovcb792242019-06-26 03:42:28 -0400116@subsection -mem-path fallback to RAM (since 4.1)
117Currently if guest RAM allocation from file pointed by @option{mem-path}
118fails, QEMU falls back to allocating from RAM, which might result
119in unpredictable behavior since the backing file specified by the user
120is ignored. In the future, users will be responsible for making sure
121the backing storage specified with @option{-mem-path} can actually provide
122the guest RAM configured with @option{-m} and QEMU will fail to start up if
123RAM allocation is unsuccessful.
124
Alistair Francisfdd1bda2019-07-16 11:47:25 -0700125@subsection RISC-V -bios (since 4.1)
126
127QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
128RISC-V virt machine and sifive_u machine.
129
130QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
131default will change in a future QEMU release, so please prepare now. All users
132of the virt or sifive_u machine must change their command line usage.
133
134QEMU 4.1 has three options, please migrate to one of these three:
135 1. ``-bios none`` - This is the current default behavior if no -bios option
136 is included. QEMU will not automatically load any firmware. It is up
137 to the user to load all the images they need.
138 2. ``-bios default`` - In a future QEMU release this will become the default
139 behaviour if no -bios option is specified. This option will load the
140 default OpenSBI firmware automatically. The firmware is included with
141 the QEMU release and no user interaction is required. All a user needs
142 to do is specify the kernel they want to boot with the -kernel option
143 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
144
Paolo Bonzinife174132019-11-13 15:16:44 +0100145@subsection -tb-size option (since 5.0)
146
147QEMU 5.0 introduced an alternative syntax to specify the size of the translation
148block cache, @option{-accel tcg,tb-size=}. The new syntax deprecates the
149previously available @option{-tb-size} option.
150
Markus Armbruster44c67842018-07-16 09:32:25 +0200151@section QEMU Machine Protocol (QMP) commands
152
Markus Armbruster6d570ca2019-10-24 13:02:23 +0200153@subsection change (since 2.5.0)
154
155Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
156
157@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
158
159Use ``migrate-set-parameters'' instead.
160
161@subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
162
163Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
164
John Snow4db6ceb2019-03-12 12:05:48 -0400165@subsection query-block result field dirty-bitmaps[i].status (since 4.0)
166
167The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
168the query-block command is deprecated. Two new boolean fields,
169``recording'' and ``busy'' effectively replace it.
170
Vladimir Sementsov-Ogievskiy590a63d2019-07-29 16:35:56 -0400171@subsection query-block result field dirty-bitmaps (Since 4.2)
172
173The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
174the query-block command is itself now deprecated. The ``dirty-bitmaps``
175field of the ``BlockDeviceInfo`` struct should be used instead, which is the
176type of the ``inserted`` field in query-block replies, as well as the
177type of array items in query-named-block-nodes.
178
179Since the ``dirty-bitmaps`` field is optionally present in both the old and
180new locations, clients must use introspection to learn where to anticipate
181the field if/when it does appear in command output.
182
Markus Armbruster44c67842018-07-16 09:32:25 +0200183@subsection query-cpus (since 2.12.0)
184
185The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
186
187@subsection query-cpus-fast "arch" output member (since 3.0.0)
188
189The ``arch'' output member of the ``query-cpus-fast'' command is
190replaced by the ``target'' output member.
191
Kashyap Chamarthyc73e6612018-12-13 13:42:24 +0100192@subsection cpu-add (since 4.0)
193
194Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
195documentation of ``query-hotpluggable-cpus'' for additional
196details.
197
Markus Armbruster9d7b7082019-02-14 16:22:50 +0100198@subsection query-events (since 4.0)
199
200The ``query-events'' command has been superseded by the more powerful
201and accurate ``query-qmp-schema'' command.
202
Marc-André Lureaua9b305b2019-04-15 18:33:36 +0200203@subsection chardev client socket with 'wait' option (since 4.0)
204
205Character devices creating sockets in client mode should not specify
206the 'wait' field, which is only applicable to sockets in server mode
207
Kashyap Chamarthye9b24fb2018-12-13 13:42:22 +0100208@section Human Monitor Protocol (HMP) commands
Thomas Huth68cb29e2018-09-20 10:22:27 +0200209
210@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
211
212The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
213'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
214
Kashyap Chamarthydc150432018-12-13 13:42:23 +0100215@subsection cpu-add (since 4.0)
Kashyap Chamarthy3800db72018-10-30 13:35:24 +0100216
217Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
218documentation of ``query-hotpluggable-cpus'' for additional details.
219
Daniel P. Berrangé01438402019-02-27 14:57:55 +0000220@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
221
222The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
223``acl_remove'' commands are deprecated with no replacement. Authorization
224for VNC should be performed using the pluggable QAuthZ objects.
225
Alistair Francisa101b642019-06-17 18:31:13 -0700226@section Guest Emulator ISAs
227
228@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
229
230The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
231QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
232should be used instead of the 1.09.1 version.
233
Alistair Francis8903bf62019-04-20 02:24:09 +0000234@section System emulator CPUS
235
236@subsection RISC-V ISA CPUs (since 4.1)
237
238The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
239four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
240``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
241option when using the ``rv32`` or ``rv64`` CPUs.
242
Alistair Francisd64db712019-04-20 02:24:18 +0000243@subsection RISC-V ISA CPUs (since 4.1)
244
245The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
246``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
247via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
248
Markus Armbruster44c67842018-07-16 09:32:25 +0200249@section System emulator devices
250
John Snow7d601332019-10-09 18:43:03 -0400251@subsection ide-drive (since 4.2)
252
253The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
254'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
255
Paolo Bonzini0d074bf2019-11-01 14:32:20 +0100256@subsection scsi-disk (since 4.2)
257
258The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
259'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
260
Markus Armbruster44c67842018-07-16 09:32:25 +0200261@section System emulator machines
262
Aleksandar Markovic2048d5d2020-01-24 17:38:43 +0100263@subsection mips r4k platform (since 5.0)
Philippe Mathieu-Daudéd32dc612019-11-25 11:41:03 +0100264
265This machine type is very old and unmaintained. Users should use the 'malta'
266machine type instead.
267
Thomas Huth30d2a172019-12-09 13:52:45 +0100268@subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
Markus Armbruster44c67842018-07-16 09:32:25 +0200269
270These machine types are very old and likely can not be used for live migration
271from old QEMU versions anymore. A newer machine type should be used instead.
272
Alistair Franciscd69e3a2019-04-20 02:24:26 +0000273@subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
274
275The version specific Spike machines have been deprecated in favour of the
276generic ``spike`` machine. If you need to specify an older version of the RISC-V
277spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
278
Markus Armbruster44c67842018-07-16 09:32:25 +0200279@section Device options
280
Stefan Hajnoczi5847c752019-12-13 14:46:26 +0000281@subsection Emulated device options
282
283@subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
284
285The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
286and later do not support it because the virtio-scsi device was introduced for
287full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
288
289Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an
290alias.
291
Markus Armbruster44c67842018-07-16 09:32:25 +0200292@subsection Block device options
293
294@subsubsection "backing": "" (since 2.12.0)
295
296In order to prevent QEMU from automatically opening an image's backing
297chain, use ``"backing": null'' instead.
298
Jeff Cody3bebd372018-09-11 18:32:33 -0400299@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
300
301Options for ``rbd'' should be specified according to its runtime options,
302like other block drivers. Legacy parsing of keyvalue pair encoded
303filenames is useful to open images with the old format for backing files;
304These image files should be updated to use the current format.
305
306Example of legacy encoding:
307
308@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
309
310The above, converted to the current supported format:
311
312@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
Eric Blake0ae2d542019-01-25 17:48:37 -0600313
314@section Related binaries
315
Kevin Wolfffd8e8f2019-08-09 11:09:21 +0200316@subsection qemu-img convert -n -o (since 4.2.0)
317
318All options specified in @option{-o} are image creation options, so
319they have no effect when used with @option{-n} to skip image creation.
320Silently ignored options can be confusing, so this combination of
321options will be made an error in future versions.
322
Eduardo Habkoste5abf592019-05-03 16:37:21 -0300323@section Build system
324
325@subsection Python 2 support (since 4.1.0)
326
327In the future, QEMU will require Python 3 to be available at
328build time. Support for Python 2 in scripts shipped with QEMU
329is deprecated.
Eduardo Habkostaa5b9692019-06-27 21:28:43 -0300330
331@section Backwards compatibility
332
333@subsection Runnability guarantee of CPU models (since 4.1.0)
334
335Previous versions of QEMU never changed existing CPU models in
336ways that introduced additional host software or hardware
337requirements to the VM. This allowed management software to
338safely change the machine type of an existing VM without
339introducing new requirements ("runnability guarantee"). This
340prevented CPU models from being updated to include CPU
341vulnerability mitigations, leaving guests vulnerable in the
342default configuration.
343
344The CPU model runnability guarantee won't apply anymore to
345existing CPU models. Management software that needs runnability
346guarantees must resolve the CPU model aliases using te
347``alias-of'' field returned by the ``query-cpu-definitions'' QMP
348command.
John Snow3264ffc2019-10-02 19:24:11 -0400349
Eduardo Habkostad183922019-12-05 19:33:39 -0300350While those guarantees are kept, the return value of
351``query-cpu-definitions'' will have existing CPU model aliases
352point to a version that doesn't break runnability guarantees
353(specifically, version 1 of those CPU models). In future QEMU
354versions, aliases will point to newer CPU model versions
355depending on the machine type, so management software must
356resolve CPU model aliases before starting a virtual machine.
357
John Snow3264ffc2019-10-02 19:24:11 -0400358
359@node Recently removed features
360@appendix Recently removed features
361
362What follows is a record of recently removed, formerly deprecated
363features that serves as a record for users who have encountered
364trouble after a recent upgrade.
365
366@section QEMU Machine Protocol (QMP) commands
367
368@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
369
370The "autoload" parameter has been ignored since 2.12.0. All bitmaps
371are automatically loaded from qcow2 images.
Eric Blake0bc16992020-01-23 10:46:50 -0600372
373@section Related binaries
374
375@subsection qemu-nbd --partition (removed in 5.0.0)
376
377The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
378could only handle MBR partitions, and never correctly handled logical
379partitions beyond partition 5. Exporting a partition can still be
380done by utilizing the @option{--image-opts} option with a raw blockdev
381using the @code{offset} and @code{size} parameters layered on top of
382any other existing blockdev. For example, if partition 1 is 100MiB
383long starting at 1MiB, the old command:
384
385@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
386
387can be rewritten as:
388
389@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2}