linux-user: fix use of SIGRTMIN
[qemu/ar7.git] / qemu-deprecated.texi
blob017b750ca8e2b77bfbd3444484ff363ccba2bc62
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 ``-accel tcg''.
31 @subsection -usbdevice (since 2.10.0)
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.
39 @subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
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.
45 @subsection -net ...,name=@var{name} (since 3.1)
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.
50 @subsection -smp (invalid topologies) (since 3.1)
52 CPU topology properties should describe whole machine topology including
53 possible CPUs.
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}}.
62 @subsection -vnc acl (since 4.0.0)
64 The @code{acl} option to the @code{-vnc} argument has been replaced
65 by the @code{tls-authz} and @code{sasl-authz} options.
67 @subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
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.
74 @subsection Creating sound card devices and vnc without audiodev= property (since 4.2)
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.
81 @subsection -mon ...,control=readline,pretty=on|off (since 4.1)
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.
87 @subsection -realtime (since 4.1)
89 The @code{-realtime mlock=on|off} argument has been replaced by the
90 @code{-overcommit mem-lock=on|off} argument.
92 @subsection -numa node,mem=@var{size} (since 4.1)
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.
108 @subsection -numa node (without memory specified) (since 4.1)
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.
116 @subsection -mem-path fallback to RAM (since 4.1)
117 Currently if guest RAM allocation from file pointed by @option{mem-path}
118 fails, QEMU falls back to allocating from RAM, which might result
119 in unpredictable behavior since the backing file specified by the user
120 is ignored. In the future, users will be responsible for making sure
121 the backing storage specified with @option{-mem-path} can actually provide
122 the guest RAM configured with @option{-m} and QEMU will fail to start up if
123 RAM allocation is unsuccessful.
125 @subsection RISC-V -bios (since 4.1)
127 QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
128 RISC-V virt machine and sifive_u machine.
130 QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
131 default will change in a future QEMU release, so please prepare now. All users
132 of the virt or sifive_u machine must change their command line usage.
134 QEMU 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.
145 @subsection -tb-size option (since 5.0)
147 QEMU 5.0 introduced an alternative syntax to specify the size of the translation
148 block cache, @option{-accel tcg,tb-size=}.  The new syntax deprecates the
149 previously available @option{-tb-size} option.
151 @section QEMU Machine Protocol (QMP) commands
153 @subsection change (since 2.5.0)
155 Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
157 @subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
159 Use ``migrate-set-parameters'' instead.
161 @subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
163 Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
165 @subsection query-block result field dirty-bitmaps[i].status (since 4.0)
167 The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
168 the query-block command is deprecated. Two new boolean fields,
169 ``recording'' and ``busy'' effectively replace it.
171 @subsection query-block result field dirty-bitmaps (Since 4.2)
173 The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
174 the query-block command is itself now deprecated. The ``dirty-bitmaps``
175 field of the ``BlockDeviceInfo`` struct should be used instead, which is the
176 type of the ``inserted`` field in query-block replies, as well as the
177 type of array items in query-named-block-nodes.
179 Since the ``dirty-bitmaps`` field is optionally present in both the old and
180 new locations, clients must use introspection to learn where to anticipate
181 the field if/when it does appear in command output.
183 @subsection query-cpus (since 2.12.0)
185 The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
187 @subsection query-cpus-fast "arch" output member (since 3.0.0)
189 The ``arch'' output member of the ``query-cpus-fast'' command is
190 replaced by the ``target'' output member.
192 @subsection cpu-add (since 4.0)
194 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
195 documentation of ``query-hotpluggable-cpus'' for additional
196 details.
198 @subsection query-events (since 4.0)
200 The ``query-events'' command has been superseded by the more powerful
201 and accurate ``query-qmp-schema'' command.
203 @subsection chardev client socket with 'wait' option (since 4.0)
205 Character devices creating sockets in client mode should not specify
206 the 'wait' field, which is only applicable to sockets in server mode
208 @section Human Monitor Protocol (HMP) commands
210 @subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
212 The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
213 'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
215 @subsection cpu-add (since 4.0)
217 Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
218 documentation of ``query-hotpluggable-cpus'' for additional details.
220 @subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
222 The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
223 ``acl_remove'' commands are deprecated with no replacement. Authorization
224 for VNC should be performed using the pluggable QAuthZ objects.
226 @section Guest Emulator ISAs
228 @subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
230 The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
231 QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
232 should be used instead of the 1.09.1 version.
234 @section System emulator CPUS
236 @subsection RISC-V ISA CPUs (since 4.1)
238 The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
239 four 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``
241 option when using the ``rv32`` or ``rv64`` CPUs.
243 @subsection RISC-V ISA CPUs (since 4.1)
245 The 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
247 via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
249 @section System emulator devices
251 @subsection ide-drive (since 4.2)
253 The '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.
256 @subsection scsi-disk (since 4.2)
258 The '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.
261 @section System emulator machines
263 @subsection mips r4k platform (since 5.0)
265 This machine type is very old and unmaintained. Users should use the 'malta'
266 machine type instead.
268 @subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
270 These machine types are very old and likely can not be used for live migration
271 from old QEMU versions anymore. A newer machine type should be used instead.
273 @subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
275 The version specific Spike machines have been deprecated in favour of the
276 generic ``spike`` machine. If you need to specify an older version of the RISC-V
277 spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
279 @section Device options
281 @subsection Emulated device options
283 @subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
285 The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature.  VIRTIO 1.0
286 and later do not support it because the virtio-scsi device was introduced for
287 full SCSI support.  Use virtio-scsi instead when SCSI passthrough is required.
289 Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an
290 alias.
292 @subsection Block device options
294 @subsubsection "backing": "" (since 2.12.0)
296 In order to prevent QEMU from automatically opening an image's backing
297 chain, use ``"backing": null'' instead.
299 @subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
301 Options for ``rbd'' should be specified according to its runtime options,
302 like other block drivers.  Legacy parsing of keyvalue pair encoded
303 filenames is useful to open images with the old format for backing files;
304 These image files should be updated to use the current format.
306 Example of legacy encoding:
308 @code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
310 The above, converted to the current supported format:
312 @code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
314 @section Related binaries
316 @subsection qemu-img convert -n -o (since 4.2.0)
318 All options specified in @option{-o} are image creation options, so
319 they have no effect when used with @option{-n} to skip image creation.
320 Silently ignored options can be confusing, so this combination of
321 options will be made an error in future versions.
323 @section Backwards compatibility
325 @subsection Runnability guarantee of CPU models (since 4.1.0)
327 Previous versions of QEMU never changed existing CPU models in
328 ways that introduced additional host software or hardware
329 requirements to the VM.  This allowed management software to
330 safely change the machine type of an existing VM without
331 introducing new requirements ("runnability guarantee").  This
332 prevented CPU models from being updated to include CPU
333 vulnerability mitigations, leaving guests vulnerable in the
334 default configuration.
336 The CPU model runnability guarantee won't apply anymore to
337 existing CPU models.  Management software that needs runnability
338 guarantees must resolve the CPU model aliases using te
339 ``alias-of'' field returned by the ``query-cpu-definitions'' QMP
340 command.
342 While those guarantees are kept, the return value of
343 ``query-cpu-definitions'' will have existing CPU model aliases
344 point to a version that doesn't break runnability guarantees
345 (specifically, version 1 of those CPU models).  In future QEMU
346 versions, aliases will point to newer CPU model versions
347 depending on the machine type, so management software must
348 resolve CPU model aliases before starting a virtual machine.
351 @node Recently removed features
352 @appendix Recently removed features
354 What follows is a record of recently removed, formerly deprecated
355 features that serves as a record for users who have encountered
356 trouble after a recent upgrade.
358 @section QEMU Machine Protocol (QMP) commands
360 @subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
362 The "autoload" parameter has been ignored since 2.12.0. All bitmaps
363 are automatically loaded from qcow2 images.
365 @section Related binaries
367 @subsection qemu-nbd --partition (removed in 5.0.0)
369 The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
370 could only handle MBR partitions, and never correctly handled logical
371 partitions beyond partition 5.  Exporting a partition can still be
372 done by utilizing the @option{--image-opts} option with a raw blockdev
373 using the @code{offset} and @code{size} parameters layered on top of
374 any other existing blockdev. For example, if partition 1 is 100MiB
375 long starting at 1MiB, the old command:
377 @code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
379 can be rewritten as:
381 @code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2}