1.. _Deprecated features: 2 3Deprecated features 4=================== 5 6In general features are intended to be supported indefinitely once 7introduced into QEMU. In the event that a feature needs to be removed, 8it will be listed in this section. The feature will remain functional for the 9release in which it was deprecated and one further release. After these two 10releases, the feature is liable to be removed. Deprecated features may also 11generate warnings on the console when QEMU starts up, or if activated via a 12monitor command, however, this is not a mandatory requirement. 13 14Prior to the 2.10.0 release there was no official policy on how 15long features would be deprecated prior to their removal, nor 16any documented list of which features were deprecated. Thus 17any features deprecated prior to 2.10.0 will be treated as if 18they were first deprecated in the 2.10.0 release. 19 20What follows is a list of all features currently marked as 21deprecated. 22 23System emulator command line arguments 24-------------------------------------- 25 26Short-form boolean options (since 6.0) 27'''''''''''''''''''''''''''''''''''''' 28 29Boolean options such as ``share=on``/``share=off`` could be written 30in short form as ``share`` and ``noshare``. This is now deprecated 31and will cause a warning. 32 33``delay`` option for socket character devices (since 6.0) 34''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 35 36The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 37rather than ``delay=off``. 38 39``-smp`` ("parameter=0" SMP configurations) (since 6.2) 40''''''''''''''''''''''''''''''''''''''''''''''''''''''' 41 42Specified CPU topology parameters must be greater than zero. 43 44In the SMP configuration, users should either provide a CPU topology 45parameter with a reasonable value (greater than zero) or just omit it 46and QEMU will compute the missing value. 47 48However, historically it was implicitly allowed for users to provide 49a parameter with zero value, which is meaningless and could also possibly 50cause unexpected results in the -smp parsing. So support for this kind of 51configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will 52be removed in the near future, users have to ensure that all the topology 53members described with -smp are greater than zero. 54 55Plugin argument passing through ``arg=<string>`` (since 6.1) 56'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 57 58Passing TCG plugins arguments through ``arg=`` is redundant is makes the 59command-line less readable, especially when the argument itself consist of a 60name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 61Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 62as short-form boolean values, and passed to plugins as ``arg_name=on``. 63However, short-form booleans are deprecated and full explicit ``arg_name=on`` 64form is preferred. 65 66User-mode emulator command line arguments 67----------------------------------------- 68 69``-p`` (since 9.0) 70'''''''''''''''''' 71 72The ``-p`` option pretends to control the host page size. However, 73it is not possible to change the host page size, and using the 74option only causes failures. 75 76QEMU Machine Protocol (QMP) commands 77------------------------------------ 78 79``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 80''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 81 82Use argument ``id`` instead. 83 84``eject`` argument ``device`` (since 2.8) 85''''''''''''''''''''''''''''''''''''''''' 86 87Use argument ``id`` instead. 88 89``blockdev-change-medium`` argument ``device`` (since 2.8) 90'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 91 92Use argument ``id`` instead. 93 94``block_set_io_throttle`` argument ``device`` (since 2.8) 95''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 96 97Use argument ``id`` instead. 98 99``blockdev-add`` empty string argument ``backing`` (since 2.10) 100''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 101 102Use argument value ``null`` instead. 103 104``block-commit`` arguments ``base`` and ``top`` (since 3.1) 105''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 106 107Use arguments ``base-node`` and ``top-node`` instead. 108 109``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 110'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 111 112Use the more generic commands ``block-export-add`` and ``block-export-del`` 113instead. As part of this deprecation, where ``nbd-server-add`` used a 114single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 115 116``query-qmp-schema`` return value member ``values`` (since 6.2) 117''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 118 119Member ``values`` in return value elements with meta-type ``enum`` is 120deprecated. Use ``members`` instead. 121 122``drive-backup`` (since 6.2) 123'''''''''''''''''''''''''''' 124 125Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 126This change primarily separates the creation/opening process of the backup 127target with explicit, separate steps. ``blockdev-backup`` uses mostly the 128same arguments as ``drive-backup``, except the ``format`` and ``mode`` 129options are removed in favor of using explicit ``blockdev-create`` and 130``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 131details. 132 133Incorrectly typed ``device_add`` arguments (since 6.2) 134'''''''''''''''''''''''''''''''''''''''''''''''''''''' 135 136Due to shortcomings in the internal implementation of ``device_add``, QEMU 137incorrectly accepts certain invalid arguments: Any object or list arguments are 138silently ignored. Other argument types are not checked, but an implicit 139conversion happens, so that e.g. string values can be assigned to integer 140device properties or vice versa. 141 142This is a bug in QEMU that will be fixed in the future so that previously 143accepted incorrect commands will return an error. Users should make sure that 144all arguments passed to ``device_add`` are consistent with the documented 145property types. 146 147QEMU Machine Protocol (QMP) events 148---------------------------------- 149 150``MEM_UNPLUG_ERROR`` (since 6.2) 151'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 152 153Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. 154 155``vcpu`` trace events (since 8.1) 156''''''''''''''''''''''''''''''''' 157 158The ability to instrument QEMU helper functions with vCPU-aware trace 159points was removed in 7.0. However QMP still exposed the vcpu 160parameter. This argument has now been deprecated and the remaining 161remaining trace points that used it are selected just by name. 162 163Host Architectures 164------------------ 165 166BE MIPS (since 7.2) 167''''''''''''''''''' 168 169As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 170MIPS moved out of support making it hard to maintain our 171cross-compilation CI tests of the architecture. As we no longer have 172CI coverage support may bitrot away before the deprecation process 173completes. The little endian variants of MIPS (both 32 and 64 bit) are 174still a supported host architecture. 175 176System emulation on 32-bit x86 hosts (since 8.0) 177'''''''''''''''''''''''''''''''''''''''''''''''' 178 179Support for 32-bit x86 host deployments is increasingly uncommon in mainstream 180OS distributions given the widespread availability of 64-bit x86 hardware. 181The QEMU project no longer considers 32-bit x86 support for system emulation to 182be an effective use of its limited resources, and thus intends to discontinue 183it. Since all recent x86 hardware from the past >10 years is capable of the 18464-bit x86 extensions, a corresponding 64-bit OS should be used instead. 185 186 187System emulator CPUs 188-------------------- 189 190Nios II CPU (since 8.2) 191''''''''''''''''''''''' 192 193The Nios II architecture is orphan. The ``nios2`` guest CPU support is 194deprecated and will be removed in a future version of QEMU. 195 196``power5+`` and ``power7+`` CPU names (since 9.0) 197''''''''''''''''''''''''''''''''''''''''''''''''' 198 199The character "+" in device (and thus also CPU) names is not allowed 200in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 201``power7+`` and ``power7+_v2.1`` are currently still supported via 202an alias, but for consistency these will get removed in a future 203release, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 204 205CRIS CPU architecture (since 9.0) 206''''''''''''''''''''''''''''''''' 207 208The CRIS architecture was pulled from Linux in 4.17 and the compiler 209is no longer packaged in any distro making it harder to run the 210``check-tcg`` tests. Unless we can improve the testing situation there 211is a chance the code will bitrot without anyone noticing. 212 213System emulator machines 214------------------------ 215 216Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 217'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 218 219The ``dtb-kaslr-seed`` property on the ``virt`` board has been 220deprecated; use the new name ``dtb-randomness`` instead. The new name 221better reflects the way this property affects all random data within 222the device tree blob, not just the ``kaslr-seed`` node. 223 224``pc-i440fx-2.0`` up to ``pc-i440fx-2.3`` (since 8.2) 225''''''''''''''''''''''''''''''''''''''''''''''''''''' 226 227These old machine types are quite neglected nowadays and thus might have 228various pitfalls with regards to live migration. Use a newer machine type 229instead. 230 231Nios II ``10m50-ghrd`` and ``nios2-generic-nommu`` machines (since 8.2) 232''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 233 234The Nios II architecture is orphan. 235 236``shix`` (since 9.0) 237'''''''''''''''''''' 238 239The machine is no longer in existence and has been long unmaintained 240in QEMU. This also holds for the TC51828 16MiB flash that it uses. 241 242``pseries-2.1`` up to ``pseries-2.11`` (since 9.0) 243'''''''''''''''''''''''''''''''''''''''''''''''''' 244 245Older pseries machines before version 2.12 have undergone many changes 246to correct issues, mostly regarding migration compatibility. These are 247no longer maintained and removing them will make the code easier to 248read and maintain. Use versions 2.12 and above as a replacement. 249 250Backend options 251--------------- 252 253Using non-persistent backing file with pmem=on (since 6.1) 254'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 255 256This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 257device. However enabling ``memory-backend-file.pmem`` option, when backing file 258is (a) not DAX capable or (b) not on a filesystem that support direct mapping 259of persistent memory, is not safe and may lead to data loss or corruption in case 260of host crash. 261Options are: 262 263 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 264 (without persistence guaranties) with backing file on non DAX storage 265 - move backing file to NVDIMM storage and keep ``pmem=on`` 266 (to have NVDIMM with persistence guaranties). 267 268Device options 269-------------- 270 271Emulated device options 272''''''''''''''''''''''' 273 274``-device virtio-blk,scsi=on|off`` (since 5.0) 275^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 276 277The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 278and later do not support it because the virtio-scsi device was introduced for 279full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. 280 281Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an 282alias. 283 284``-device nvme-ns,eui64-default=on|off`` (since 7.1) 285^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 286 287In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 288identifier that is not globally unique. If an EUI-64 identifier is required, the 289user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 290 291``-device nvme,use-intel-id=on|off`` (since 7.1) 292^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 293 294The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 295from Intel that was not properly allocated. Since version 5.2, the controller 296has used a properly allocated identifier. Deprecate the ``use-intel-id`` 297machine compatibility parameter. 298 299``-device cxl-type3,memdev=xxxx`` (since 8.0) 300^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 301 302The ``cxl-type3`` device initially only used a single memory backend. With 303the addition of volatile memory support, it is now necessary to distinguish 304between persistent and volatile memory backends. As such, memdev is deprecated 305in favor of persistent-memdev. 306 307``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 308^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 309 310The 9p ``proxy`` filesystem backend driver has been deprecated and will be 311removed (along with its proxy helper daemon) in a future version of QEMU. Please 312use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 313backend, or alternatively consider deploying virtiofsd instead. 314 315The 9p ``proxy`` backend was originally developed as an alternative to the 9p 316``local`` backend. The idea was to enhance security by dispatching actual low 317level filesystem operations from 9p server (QEMU process) over to a separate 318process (the virtfs-proxy-helper binary). However this alternative never gained 319momentum. The proxy backend is much slower than the local backend, hasn't seen 320any development in years, and showed to be less secure, especially due to the 321fact that its helper daemon must be run as root, whereas with the local backend 322QEMU is typically run as unprivileged user and allows to tighten behaviour by 323mapping permissions et al by using its 'mapped' security model option. 324 325Nowadays it would make sense to reimplement the ``proxy`` backend by using 326QEMU's ``vhost`` feature, which would eliminate the high latency costs under 327which the 9p ``proxy`` backend currently suffers. However as of to date nobody 328has indicated plans for such kind of reimplementation unfortunately. 329 330RISC-V 'any' CPU type ``-cpu any`` (since 8.2) 331^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 332 333The 'any' CPU type was introduced back in 2018 and has been around since the 334initial RISC-V QEMU port. Its usage has always been unclear: users don't know 335what to expect from a CPU called 'any', and in fact the CPU does not do anything 336special that isn't already done by the default CPUs rv32/rv64. 337 338After the introduction of the 'max' CPU type, RISC-V now has a good coverage 339of generic CPUs: rv32 and rv64 as default CPUs and 'max' as a feature complete 340CPU for both 32 and 64 bit builds. Users are then discouraged to use the 'any' 341CPU type starting in 8.2. 342 343RISC-V CPU properties which start with capital 'Z' (since 8.2) 344^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 345 346All RISC-V CPU properties which start with capital 'Z' are being deprecated 347starting in 8.2. The reason is that they were wrongly added with capital 'Z' 348in the past. CPU properties were later added with lower-case names, which 349is the format we want to use from now on. 350 351Users which try to use these deprecated properties will receive a warning 352recommending to switch to their stable counterparts: 353 354- "Zifencei" should be replaced with "zifencei" 355- "Zicsr" should be replaced with "zicsr" 356- "Zihintntl" should be replaced with "zihintntl" 357- "Zihintpause" should be replaced with "zihintpause" 358- "Zawrs" should be replaced with "zawrs" 359- "Zfa" should be replaced with "zfa" 360- "Zfh" should be replaced with "zfh" 361- "Zfhmin" should be replaced with "zfhmin" 362- "Zve32f" should be replaced with "zve32f" 363- "Zve64f" should be replaced with "zve64f" 364- "Zve64d" should be replaced with "zve64d" 365 366``-device pvrdma`` and the rdma subsystem (since 8.2) 367^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 368 369The pvrdma device and the whole rdma subsystem are in a bad shape and 370without active maintenance. The QEMU project intends to remove this 371device and subsystem from the code base in a future release without 372replacement unless somebody steps up and improves the situation. 373 374 375Block device options 376'''''''''''''''''''' 377 378``"backing": ""`` (since 2.12) 379^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 380 381In order to prevent QEMU from automatically opening an image's backing 382chain, use ``"backing": null`` instead. 383 384``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 385^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 386 387Options for ``rbd`` should be specified according to its runtime options, 388like other block drivers. Legacy parsing of keyvalue pair encoded 389filenames is useful to open images with the old format for backing files; 390These image files should be updated to use the current format. 391 392Example of legacy encoding:: 393 394 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 395 396The above, converted to the current supported format:: 397 398 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 399 400``iscsi,password=xxx`` (since 8.0) 401^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 402 403Specifying the iSCSI password in plain text on the command line using the 404``password`` option is insecure. The ``password-secret`` option should be 405used instead, to refer to a ``--object secret...`` instance that provides 406a password via a file, or encrypted. 407 408Character device options 409'''''''''''''''''''''''' 410 411Backend ``memory`` (since 9.0) 412^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 413 414``memory`` is a deprecated synonym for ``ringbuf``. 415 416CPU device properties 417''''''''''''''''''''' 418 419``pmu-num=n`` on RISC-V CPUs (since 8.2) 420^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 421 422In order to support more flexible counter configurations this has been replaced 423by a ``pmu-mask`` property. If set of counters is continuous then the mask can 424be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 425must be left clear. 426 427 428Backwards compatibility 429----------------------- 430 431Runnability guarantee of CPU models (since 4.1) 432''''''''''''''''''''''''''''''''''''''''''''''' 433 434Previous versions of QEMU never changed existing CPU models in 435ways that introduced additional host software or hardware 436requirements to the VM. This allowed management software to 437safely change the machine type of an existing VM without 438introducing new requirements ("runnability guarantee"). This 439prevented CPU models from being updated to include CPU 440vulnerability mitigations, leaving guests vulnerable in the 441default configuration. 442 443The CPU model runnability guarantee won't apply anymore to 444existing CPU models. Management software that needs runnability 445guarantees must resolve the CPU model aliases using the 446``alias-of`` field returned by the ``query-cpu-definitions`` QMP 447command. 448 449While those guarantees are kept, the return value of 450``query-cpu-definitions`` will have existing CPU model aliases 451point to a version that doesn't break runnability guarantees 452(specifically, version 1 of those CPU models). In future QEMU 453versions, aliases will point to newer CPU model versions 454depending on the machine type, so management software must 455resolve CPU model aliases before starting a virtual machine. 456 457QEMU guest agent 458---------------- 459 460``--blacklist`` command line option (since 7.2) 461''''''''''''''''''''''''''''''''''''''''''''''' 462 463``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better 464wording for what this option does). The short form ``-b`` still stays 465the same and thus is the preferred way for scripts that should run with 466both, older and future versions of QEMU. 467 468``blacklist`` config file option (since 7.2) 469'''''''''''''''''''''''''''''''''''''''''''' 470 471The ``blacklist`` config file option has been renamed to ``block-rpcs`` 472(to be in sync with the renaming of the corresponding command line 473option). 474 475Migration 476--------- 477 478``skipped`` MigrationStats field (since 8.1) 479'''''''''''''''''''''''''''''''''''''''''''' 480 481``skipped`` field in Migration stats has been deprecated. It hasn't 482been used for more than 10 years. 483 484``inc`` migrate command option (since 8.2) 485'''''''''''''''''''''''''''''''''''''''''' 486 487Use blockdev-mirror with NBD instead. 488 489As an intermediate step the ``inc`` functionality can be achieved by 490setting the ``block-incremental`` migration parameter to ``true``. 491But this parameter is also deprecated. 492 493``blk`` migrate command option (since 8.2) 494'''''''''''''''''''''''''''''''''''''''''' 495 496Use blockdev-mirror with NBD instead. 497 498As an intermediate step the ``blk`` functionality can be achieved by 499setting the ``block`` migration capability to ``true``. But this 500capability is also deprecated. 501 502block migration (since 8.2) 503''''''''''''''''''''''''''' 504 505Block migration is too inflexible. It needs to migrate all block 506devices or none. 507 508Please see "QMP invocation for live storage migration with 509``blockdev-mirror`` + NBD" in docs/interop/live-block-operations.rst 510for a detailed explanation. 511 512old compression method (since 8.2) 513'''''''''''''''''''''''''''''''''' 514 515Compression method fails too much. Too many races. We are going to 516remove it if nobody fixes it. For starters, migration-test 517compression tests are disabled because they fail randomly. If you need 518compression, use multifd compression methods. 519