1@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 20@section System emulator command line arguments 21 22@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 27@subsection -no-kvm (since 1.3.0) 28 29The ``-no-kvm'' argument is now a synonym for setting 30``-machine accel=tcg''. 31 32@subsection -usbdevice (since 2.10.0) 33 34The ``-usbdevice DEV'' argument is now a synonym for setting 35the ``-device usb-DEV'' argument instead. The deprecated syntax 36would automatically enable USB support on the machine type. 37If using the new syntax, USB support must be explicitly 38enabled via the ``-machine usb=on'' argument. 39 40@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0) 41 42The 'file' driver for drives is no longer appropriate for character or host 43devices and will only accept regular files (S_IFREG). The correct driver 44for these file types is 'host_cdrom' or 'host_device' as appropriate. 45 46@subsection -net ...,name=@var{name} (since 3.1) 47 48The @option{name} parameter of the @option{-net} option is a synonym 49for the @option{id} parameter, which should now be used instead. 50 51@subsection -smp (invalid topologies) (since 3.1) 52 53CPU topology properties should describe whole machine topology including 54possible CPUs. 55 56However, historically it was possible to start QEMU with an incorrect topology 57where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}}, 58which could lead to an incorrect topology enumeration by the guest. 59Support for invalid topologies will be removed, the user must ensure 60topologies 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 65The @code{acl} option to the @code{-vnc} argument has been replaced 66by the @code{tls-authz} and @code{sasl-authz} options. 67 68@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0) 69 70The ``-audiodev'' argument is now the preferred way to specify audio 71backend settings instead of environment variables. To ease migration to 72the new format, the ``-audiodev-help'' option can be used to convert 73the current values of the environment variables to ``-audiodev'' options. 74 75@subsection -mon ...,control=readline,pretty=on|off (since 4.1) 76 77The @code{pretty=on|off} switch has no effect for HMP monitors, but is 78silently ignored. Using the switch with HMP monitors will become an 79error in the future. 80 81@subsection -realtime (since 4.1) 82 83The @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 88The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth'' 89and ``-device virtio-9p-...'' instead. 90 91@subsection -numa node,mem=@var{size} (since 4.1) 92 93The parameter @option{mem} of @option{-numa node} is used to assign a part of 94guest RAM to a NUMA node. But when using it, it's impossible to manage specified 95RAM chunk on the host side (like bind it to a host node, setting bind policy, ...), 96so guest end-ups with the fake NUMA configuration with suboptiomal performance. 97However since 2014 there is an alternative way to assign RAM to a NUMA node 98using parameter @option{memdev}, which does the same as @option{mem} and adds 99means to actualy manage node RAM on the host side. Use parameter @option{memdev} 100with @var{memory-backend-ram} backend as an replacement for parameter @option{mem} 101to achieve the same fake NUMA effect or a properly configured 102@var{memory-backend-file} backend to actually benefit from NUMA configuration. 103In future new machine versions will not accept the option but it will still 104work with old machine types. User can check QAPI schema to see if the legacy 105option is supported by looking at MachineInfo::numa-mem-supported property. 106 107@subsection -numa node (without memory specified) (since 4.1) 108 109Splitting RAM by default between NUMA nodes has the same issues as @option{mem} 110parameter described above with the difference that the role of the user plays 111QEMU using implicit generic or board specific splitting rule. 112Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if 113it's supported by used machine type) to define mapping explictly instead. 114 115@subsection -mem-path fallback to RAM (since 4.1) 116Currently if guest RAM allocation from file pointed by @option{mem-path} 117fails, QEMU falls back to allocating from RAM, which might result 118in unpredictable behavior since the backing file specified by the user 119is ignored. In the future, users will be responsible for making sure 120the backing storage specified with @option{-mem-path} can actually provide 121the guest RAM configured with @option{-m} and QEMU will fail to start up if 122RAM allocation is unsuccessful. 123 124@subsection RISC-V -bios (since 4.1) 125 126QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the 127RISC-V virt machine and sifive_u machine. 128 129QEMU 4.1 has no changes to the default behaviour to avoid breakages. This 130default will change in a future QEMU release, so please prepare now. All users 131of the virt or sifive_u machine must change their command line usage. 132 133QEMU 4.1 has three options, please migrate to one of these three: 134 1. ``-bios none`` - This is the current default behavior if no -bios option 135 is included. QEMU will not automatically load any firmware. It is up 136 to the user to load all the images they need. 137 2. ``-bios default`` - In a future QEMU release this will become the default 138 behaviour if no -bios option is specified. This option will load the 139 default OpenSBI firmware automatically. The firmware is included with 140 the QEMU release and no user interaction is required. All a user needs 141 to do is specify the kernel they want to boot with the -kernel option 142 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae. 143 144@section QEMU Machine Protocol (QMP) commands 145 146@subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0) 147 148"autoload" parameter is now ignored. All bitmaps are automatically loaded 149from qcow2 images. 150 151@subsection query-block result field dirty-bitmaps[i].status (since 4.0) 152 153The ``status'' field of the ``BlockDirtyInfo'' structure, returned by 154the query-block command is deprecated. Two new boolean fields, 155``recording'' and ``busy'' effectively replace it. 156 157@subsection query-cpus (since 2.12.0) 158 159The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. 160 161@subsection query-cpus-fast "arch" output member (since 3.0.0) 162 163The ``arch'' output member of the ``query-cpus-fast'' command is 164replaced by the ``target'' output member. 165 166@subsection cpu-add (since 4.0) 167 168Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 169documentation of ``query-hotpluggable-cpus'' for additional 170details. 171 172@subsection query-events (since 4.0) 173 174The ``query-events'' command has been superseded by the more powerful 175and accurate ``query-qmp-schema'' command. 176 177@subsection chardev client socket with 'wait' option (since 4.0) 178 179Character devices creating sockets in client mode should not specify 180the 'wait' field, which is only applicable to sockets in server mode 181 182@section Human Monitor Protocol (HMP) commands 183 184@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1) 185 186The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and 187'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}. 188 189@subsection cpu-add (since 4.0) 190 191Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 192documentation of ``query-hotpluggable-cpus'' for additional details. 193 194@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0) 195 196The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and 197``acl_remove'' commands are deprecated with no replacement. Authorization 198for VNC should be performed using the pluggable QAuthZ objects. 199 200@section Guest Emulator ISAs 201 202@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1) 203 204The RISC-V ISA privledge specification version 1.09.1 has been deprecated. 205QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these 206should be used instead of the 1.09.1 version. 207 208@section System emulator CPUS 209 210@subsection RISC-V ISA CPUs (since 4.1) 211 212The RISC-V cpus with the ISA version in the CPU name have been depcreated. The 213four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and 214``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec`` 215option when using the ``rv32`` or ``rv64`` CPUs. 216 217@subsection RISC-V ISA CPUs (since 4.1) 218 219The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and 220``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified 221via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. 222 223@section System emulator devices 224 225@subsection bluetooth (since 3.1) 226 227The bluetooth subsystem is unmaintained since many years and likely bitrotten 228quite a bit. It will be removed without replacement unless some users speaks 229up at the @email{qemu-devel@@nongnu.org} mailing list with information about 230their usecases. 231 232@section System emulator machines 233 234@subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0) 235 236These machine types are very old and likely can not be used for live migration 237from old QEMU versions anymore. A newer machine type should be used instead. 238 239@subsection prep (PowerPC) (since 3.1) 240 241This machine type uses an unmaintained firmware, broken in lots of ways, 242and unable to start post-2004 operating systems. 40p machine type should be 243used instead. 244 245@subsection spike_v1.9.1 and spike_v1.10 (since 4.1) 246 247The version specific Spike machines have been deprecated in favour of the 248generic ``spike`` machine. If you need to specify an older version of the RISC-V 249spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument. 250 251@section Device options 252 253@subsection Block device options 254 255@subsubsection "backing": "" (since 2.12.0) 256 257In order to prevent QEMU from automatically opening an image's backing 258chain, use ``"backing": null'' instead. 259 260@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0) 261 262Options for ``rbd'' should be specified according to its runtime options, 263like other block drivers. Legacy parsing of keyvalue pair encoded 264filenames is useful to open images with the old format for backing files; 265These image files should be updated to use the current format. 266 267Example of legacy encoding: 268 269@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}} 270 271The above, converted to the current supported format: 272 273@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}} 274 275@section Related binaries 276 277@subsection qemu-nbd --partition (since 4.0.0) 278 279The ``qemu-nbd --partition $digit'' code (also spelled @option{-P}) 280can only handle MBR partitions, and has never correctly handled 281logical partitions beyond partition 5. If you know the offset and 282length of the partition (perhaps by using @code{sfdisk} within the 283guest), you can achieve the effect of exporting just that subset of 284the disk by use of the @option{--image-opts} option with a raw 285blockdev using the @code{offset} and @code{size} parameters layered on 286top of any other existing blockdev. For example, if partition 1 is 287100MiB long starting at 1MiB, the old command: 288 289@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2} 290 291can be rewritten as: 292 293@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.backing.driver=file,file.backing.filename=file.qcow2} 294 295Alternatively, the @code{nbdkit} project provides a more powerful 296partition filter on top of its nbd plugin, which can be used to select 297an arbitrary MBR or GPT partition on top of any other full-image NBD 298export. Using this to rewrite the above example results in: 299 300@code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &} 301@code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1} 302 303Note that if you are exposing the export via /dev/nbd0, it is easier 304to just export the entire image and then mount only /dev/nbd0p1 than 305it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a 306subset of the image. 307 308@section Build system 309 310@subsection Python 2 support (since 4.1.0) 311 312In the future, QEMU will require Python 3 to be available at 313build time. Support for Python 2 in scripts shipped with QEMU 314is deprecated. 315 316@section Backwards compatibility 317 318@subsection Runnability guarantee of CPU models (since 4.1.0) 319 320Previous versions of QEMU never changed existing CPU models in 321ways that introduced additional host software or hardware 322requirements to the VM. This allowed management software to 323safely change the machine type of an existing VM without 324introducing new requirements ("runnability guarantee"). This 325prevented CPU models from being updated to include CPU 326vulnerability mitigations, leaving guests vulnerable in the 327default configuration. 328 329The CPU model runnability guarantee won't apply anymore to 330existing CPU models. Management software that needs runnability 331guarantees must resolve the CPU model aliases using te 332``alias-of'' field returned by the ``query-cpu-definitions'' QMP 333command. 334