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 ``-accel tcg''. 30 31@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 39@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 45@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 50@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 62@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 67@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 74@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 81@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 87@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 92@subsection -virtfs_synth (since 4.1) 93 94The ``-virtfs_synth'' argument is now deprecated. Please use ``-fsdev synth'' 95and ``-device virtio-9p-...'' instead. 96 97@subsection -numa node,mem=@var{size} (since 4.1) 98 99The parameter @option{mem} of @option{-numa node} is used to assign a part of 100guest RAM to a NUMA node. But when using it, it's impossible to manage specified 101RAM chunk on the host side (like bind it to a host node, setting bind policy, ...), 102so guest end-ups with the fake NUMA configuration with suboptiomal performance. 103However since 2014 there is an alternative way to assign RAM to a NUMA node 104using parameter @option{memdev}, which does the same as @option{mem} and adds 105means to actualy manage node RAM on the host side. Use parameter @option{memdev} 106with @var{memory-backend-ram} backend as an replacement for parameter @option{mem} 107to achieve the same fake NUMA effect or a properly configured 108@var{memory-backend-file} backend to actually benefit from NUMA configuration. 109In future new machine versions will not accept the option but it will still 110work with old machine types. User can check QAPI schema to see if the legacy 111option is supported by looking at MachineInfo::numa-mem-supported property. 112 113@subsection -numa node (without memory specified) (since 4.1) 114 115Splitting RAM by default between NUMA nodes has the same issues as @option{mem} 116parameter described above with the difference that the role of the user plays 117QEMU using implicit generic or board specific splitting rule. 118Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if 119it's supported by used machine type) to define mapping explictly instead. 120 121@subsection -mem-path fallback to RAM (since 4.1) 122Currently if guest RAM allocation from file pointed by @option{mem-path} 123fails, QEMU falls back to allocating from RAM, which might result 124in unpredictable behavior since the backing file specified by the user 125is ignored. In the future, users will be responsible for making sure 126the backing storage specified with @option{-mem-path} can actually provide 127the guest RAM configured with @option{-m} and QEMU will fail to start up if 128RAM allocation is unsuccessful. 129 130@subsection RISC-V -bios (since 4.1) 131 132QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the 133RISC-V virt machine and sifive_u machine. 134 135QEMU 4.1 has no changes to the default behaviour to avoid breakages. This 136default will change in a future QEMU release, so please prepare now. All users 137of the virt or sifive_u machine must change their command line usage. 138 139QEMU 4.1 has three options, please migrate to one of these three: 140 1. ``-bios none`` - This is the current default behavior if no -bios option 141 is included. QEMU will not automatically load any firmware. It is up 142 to the user to load all the images they need. 143 2. ``-bios default`` - In a future QEMU release this will become the default 144 behaviour if no -bios option is specified. This option will load the 145 default OpenSBI firmware automatically. The firmware is included with 146 the QEMU release and no user interaction is required. All a user needs 147 to do is specify the kernel they want to boot with the -kernel option 148 3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae. 149 150@section QEMU Machine Protocol (QMP) commands 151 152@subsection change (since 2.5.0) 153 154Use ``blockdev-change-medium'' or ``change-vnc-password'' instead. 155 156@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0) 157 158Use ``migrate-set-parameters'' instead. 159 160@subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0) 161 162Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead. 163 164@subsection query-block result field dirty-bitmaps[i].status (since 4.0) 165 166The ``status'' field of the ``BlockDirtyInfo'' structure, returned by 167the query-block command is deprecated. Two new boolean fields, 168``recording'' and ``busy'' effectively replace it. 169 170@subsection query-block result field dirty-bitmaps (Since 4.2) 171 172The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by 173the query-block command is itself now deprecated. The ``dirty-bitmaps`` 174field of the ``BlockDeviceInfo`` struct should be used instead, which is the 175type of the ``inserted`` field in query-block replies, as well as the 176type of array items in query-named-block-nodes. 177 178Since the ``dirty-bitmaps`` field is optionally present in both the old and 179new locations, clients must use introspection to learn where to anticipate 180the field if/when it does appear in command output. 181 182@subsection query-cpus (since 2.12.0) 183 184The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command. 185 186@subsection query-cpus-fast "arch" output member (since 3.0.0) 187 188The ``arch'' output member of the ``query-cpus-fast'' command is 189replaced by the ``target'' output member. 190 191@subsection cpu-add (since 4.0) 192 193Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 194documentation of ``query-hotpluggable-cpus'' for additional 195details. 196 197@subsection query-events (since 4.0) 198 199The ``query-events'' command has been superseded by the more powerful 200and accurate ``query-qmp-schema'' command. 201 202@subsection chardev client socket with 'wait' option (since 4.0) 203 204Character devices creating sockets in client mode should not specify 205the 'wait' field, which is only applicable to sockets in server mode 206 207@section Human Monitor Protocol (HMP) commands 208 209@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1) 210 211The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and 212'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}. 213 214@subsection cpu-add (since 4.0) 215 216Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See 217documentation of ``query-hotpluggable-cpus'' for additional details. 218 219@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0) 220 221The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and 222``acl_remove'' commands are deprecated with no replacement. Authorization 223for VNC should be performed using the pluggable QAuthZ objects. 224 225@section Guest Emulator ISAs 226 227@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1) 228 229The RISC-V ISA privledge specification version 1.09.1 has been deprecated. 230QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these 231should be used instead of the 1.09.1 version. 232 233@section System emulator CPUS 234 235@subsection RISC-V ISA CPUs (since 4.1) 236 237The RISC-V cpus with the ISA version in the CPU name have been depcreated. The 238four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and 239``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec`` 240option when using the ``rv32`` or ``rv64`` CPUs. 241 242@subsection RISC-V ISA CPUs (since 4.1) 243 244The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and 245``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified 246via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. 247 248@section System emulator devices 249 250@subsection bluetooth (since 3.1) 251 252The bluetooth subsystem is unmaintained since many years and likely bitrotten 253quite a bit. It will be removed without replacement unless some users speaks 254up at the @email{qemu-devel@@nongnu.org} mailing list with information about 255their usecases. 256 257@subsection ide-drive (since 4.2) 258 259The 'ide-drive' device is deprecated. Users should use 'ide-hd' or 260'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed. 261 262@subsection scsi-disk (since 4.2) 263 264The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or 265'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed. 266 267@section System emulator machines 268 269@subsection pc-0.12, pc-0.13, pc-0.14 and pc-0.15 (since 4.0) 270 271These machine types are very old and likely can not be used for live migration 272from old QEMU versions anymore. A newer machine type should be used instead. 273 274@subsection prep (PowerPC) (since 3.1) 275 276This machine type uses an unmaintained firmware, broken in lots of ways, 277and unable to start post-2004 operating systems. 40p machine type should be 278used instead. 279 280@subsection spike_v1.9.1 and spike_v1.10 (since 4.1) 281 282The version specific Spike machines have been deprecated in favour of the 283generic ``spike`` machine. If you need to specify an older version of the RISC-V 284spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument. 285 286@section Device options 287 288@subsection Block device options 289 290@subsubsection "backing": "" (since 2.12.0) 291 292In order to prevent QEMU from automatically opening an image's backing 293chain, use ``"backing": null'' instead. 294 295@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0) 296 297Options for ``rbd'' should be specified according to its runtime options, 298like other block drivers. Legacy parsing of keyvalue pair encoded 299filenames is useful to open images with the old format for backing files; 300These image files should be updated to use the current format. 301 302Example of legacy encoding: 303 304@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}} 305 306The above, converted to the current supported format: 307 308@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}} 309 310@section Related binaries 311 312@subsection qemu-nbd --partition (since 4.0.0) 313 314The ``qemu-nbd --partition $digit'' code (also spelled @option{-P}) 315can only handle MBR partitions, and has never correctly handled 316logical partitions beyond partition 5. If you know the offset and 317length of the partition (perhaps by using @code{sfdisk} within the 318guest), you can achieve the effect of exporting just that subset of 319the disk by use of the @option{--image-opts} option with a raw 320blockdev using the @code{offset} and @code{size} parameters layered on 321top of any other existing blockdev. For example, if partition 1 is 322100MiB long starting at 1MiB, the old command: 323 324@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2} 325 326can be rewritten as: 327 328@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.backing.driver=file,file.backing.filename=file.qcow2} 329 330Alternatively, the @code{nbdkit} project provides a more powerful 331partition filter on top of its nbd plugin, which can be used to select 332an arbitrary MBR or GPT partition on top of any other full-image NBD 333export. Using this to rewrite the above example results in: 334 335@code{qemu-nbd -t -k /tmp/sock -f qcow2 file.qcow2 &} 336@code{nbdkit -f --filter=partition nbd socket=/tmp/sock partition=1} 337 338Note that if you are exposing the export via /dev/nbd0, it is easier 339to just export the entire image and then mount only /dev/nbd0p1 than 340it is to reinvoke @command{qemu-nbd -c /dev/nbd0} limited to just a 341subset of the image. 342 343@subsection qemu-img convert -n -o (since 4.2.0) 344 345All options specified in @option{-o} are image creation options, so 346they have no effect when used with @option{-n} to skip image creation. 347Silently ignored options can be confusing, so this combination of 348options will be made an error in future versions. 349 350@section Build system 351 352@subsection Python 2 support (since 4.1.0) 353 354In the future, QEMU will require Python 3 to be available at 355build time. Support for Python 2 in scripts shipped with QEMU 356is deprecated. 357 358@section Backwards compatibility 359 360@subsection Runnability guarantee of CPU models (since 4.1.0) 361 362Previous versions of QEMU never changed existing CPU models in 363ways that introduced additional host software or hardware 364requirements to the VM. This allowed management software to 365safely change the machine type of an existing VM without 366introducing new requirements ("runnability guarantee"). This 367prevented CPU models from being updated to include CPU 368vulnerability mitigations, leaving guests vulnerable in the 369default configuration. 370 371The CPU model runnability guarantee won't apply anymore to 372existing CPU models. Management software that needs runnability 373guarantees must resolve the CPU model aliases using te 374``alias-of'' field returned by the ``query-cpu-definitions'' QMP 375command. 376 377 378@node Recently removed features 379@appendix Recently removed features 380 381What follows is a record of recently removed, formerly deprecated 382features that serves as a record for users who have encountered 383trouble after a recent upgrade. 384 385@section QEMU Machine Protocol (QMP) commands 386 387@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0) 388 389The "autoload" parameter has been ignored since 2.12.0. All bitmaps 390are automatically loaded from qcow2 images. 391