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 14As a special exception to this general timeframe, rather than have an 15indefinite lifetime, versioned machine types are only intended to be 16supported for a period of 6 years, equivalent to 18 QEMU releases. All 17versioned machine types will be automatically marked deprecated after an 18initial 3 years (9 QEMU releases) has passed, and will then be deleted after 19a further 3 year period has passed. It is recommended that a deprecated 20machine type is only used for incoming migrations and restore of saved state, 21for pre-existing VM deployments. They should be scheduled for updating to a 22newer machine type during an appropriate service window. Newly deployed VMs 23should exclusively use a non-deprecated machine type, with use of the most 24recent version highly recommended. Non-versioned machine types follow the 25general feature deprecation policy. 26 27Prior to the 2.10.0 release there was no official policy on how 28long features would be deprecated prior to their removal, nor 29any documented list of which features were deprecated. Thus 30any features deprecated prior to 2.10.0 will be treated as if 31they were first deprecated in the 2.10.0 release. 32 33What follows is a list of all features currently marked as 34deprecated. 35 36System emulator command line arguments 37-------------------------------------- 38 39Short-form boolean options (since 6.0) 40'''''''''''''''''''''''''''''''''''''' 41 42Boolean options such as ``share=on``/``share=off`` could be written 43in short form as ``share`` and ``noshare``. This is now deprecated 44and will cause a warning. 45 46``delay`` option for socket character devices (since 6.0) 47''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 48 49The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 50rather than ``delay=off``. 51 52Plugin argument passing through ``arg=<string>`` (since 6.1) 53'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 54 55Passing TCG plugins arguments through ``arg=`` is redundant is makes the 56command-line less readable, especially when the argument itself consist of a 57name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 58Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 59as short-form boolean values, and passed to plugins as ``arg_name=on``. 60However, short-form booleans are deprecated and full explicit ``arg_name=on`` 61form is preferred. 62 63``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0) 64''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 65 66Specified CPU topology parameters must be supported by the machine. 67 68In the SMP configuration, users should provide the CPU topology parameters that 69are supported by the target machine. 70 71However, historically it was allowed for users to specify the unsupported 72topology parameter as "1", which is meaningless. So support for this kind of 73configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is 74marked deprecated since 9.0, users have to ensure that all the topology members 75described with -smp are supported by the target machine. 76 77User-mode emulator command line arguments 78----------------------------------------- 79 80``-p`` (since 9.0) 81'''''''''''''''''' 82 83The ``-p`` option pretends to control the host page size. However, 84it is not possible to change the host page size, and using the 85option only causes failures. 86 87QEMU Machine Protocol (QMP) commands 88------------------------------------ 89 90``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 91''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 92 93Use argument ``id`` instead. 94 95``eject`` argument ``device`` (since 2.8) 96''''''''''''''''''''''''''''''''''''''''' 97 98Use argument ``id`` instead. 99 100``blockdev-change-medium`` argument ``device`` (since 2.8) 101'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 102 103Use argument ``id`` instead. 104 105``block_set_io_throttle`` argument ``device`` (since 2.8) 106''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 107 108Use argument ``id`` instead. 109 110``blockdev-add`` empty string argument ``backing`` (since 2.10) 111''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 112 113Use argument value ``null`` instead. 114 115``block-commit`` arguments ``base`` and ``top`` (since 3.1) 116''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 117 118Use arguments ``base-node`` and ``top-node`` instead. 119 120``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 121'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 122 123Use the more generic commands ``block-export-add`` and ``block-export-del`` 124instead. As part of this deprecation, where ``nbd-server-add`` used a 125single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 126 127``query-qmp-schema`` return value member ``values`` (since 6.2) 128''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 129 130Member ``values`` in return value elements with meta-type ``enum`` is 131deprecated. Use ``members`` instead. 132 133``drive-backup`` (since 6.2) 134'''''''''''''''''''''''''''' 135 136Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 137This change primarily separates the creation/opening process of the backup 138target with explicit, separate steps. ``blockdev-backup`` uses mostly the 139same arguments as ``drive-backup``, except the ``format`` and ``mode`` 140options are removed in favor of using explicit ``blockdev-create`` and 141``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 142details. 143 144``query-migrationthreads`` (since 9.2) 145'''''''''''''''''''''''''''''''''''''' 146 147To be removed with no replacement, as it reports only a limited set of 148threads (for example, it only reports source side of multifd threads, 149without reporting any destination threads, or non-multifd source threads). 150For debugging purpose, please use ``-name $VM,debug-threads=on`` instead. 151 152Incorrectly typed ``device_add`` arguments (since 6.2) 153'''''''''''''''''''''''''''''''''''''''''''''''''''''' 154 155Due to shortcomings in the internal implementation of ``device_add``, QEMU 156incorrectly accepts certain invalid arguments: Any object or list arguments are 157silently ignored. Other argument types are not checked, but an implicit 158conversion happens, so that e.g. string values can be assigned to integer 159device properties or vice versa. 160 161This is a bug in QEMU that will be fixed in the future so that previously 162accepted incorrect commands will return an error. Users should make sure that 163all arguments passed to ``device_add`` are consistent with the documented 164property types. 165 166Host Architectures 167------------------ 168 169Big endian MIPS since 7.2; 32-bit little endian MIPS since 9.2 170'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 171 172As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 173MIPS moved out of support making it hard to maintain our 174cross-compilation CI tests of the architecture. As we no longer have 175CI coverage support may bitrot away before the deprecation process 176completes. 177 178Likewise, the little endian variant of 32 bit MIPS is not supported by 179Debian 13 ("Trixie") and newer. 180 18164 bit little endian MIPS is still a supported host architecture. 182 183System emulation on 32-bit x86 hosts (since 8.0) 184'''''''''''''''''''''''''''''''''''''''''''''''' 185 186Support for 32-bit x86 host deployments is increasingly uncommon in mainstream 187OS distributions given the widespread availability of 64-bit x86 hardware. 188The QEMU project no longer considers 32-bit x86 support for system emulation to 189be an effective use of its limited resources, and thus intends to discontinue 190it. Since all recent x86 hardware from the past >10 years is capable of the 19164-bit x86 extensions, a corresponding 64-bit OS should be used instead. 192 193TCG Plugin support not enabled by default on 32-bit hosts (since 9.2) 194''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 195 196While it is still possible to enable TCG plugin support for 32-bit 197hosts there are a number of potential pitfalls when instrumenting 19864-bit guests. The plugin APIs typically pass most addresses as 199uint64_t but practices like encoding that address in a host pointer 200for passing as user-data will lose data. As most software analysis 201benefits from having plenty of host memory it seems reasonable to 202encourage users to use 64 bit builds of QEMU for analysis work 203whatever targets they are instrumenting. 204 205TCG Plugin support not enabled by default with TCI (since 9.2) 206'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 207 208While the TCG interpreter can interpret the TCG ops used by plugins it 209is going to be so much slower it wouldn't make sense for any serious 210instrumentation. Due to implementation differences there will also be 211anomalies in things like memory instrumentation. 212 213System emulator CPUs 214-------------------- 215 216``power5+`` and ``power7+`` CPU names (since 9.0) 217''''''''''''''''''''''''''''''''''''''''''''''''' 218 219The character "+" in device (and thus also CPU) names is not allowed 220in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 221``power7+`` and ``power7+_v2.1`` are currently still supported via 222an alias, but for consistency these will get removed in a future 223release, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 224 225``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1) 226''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 227 228The character "+" in device (and thus also CPU) names is not allowed 229in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and 230``Sun-UltraSparc-IV+`` are currently still supported via a workaround, 231but for consistency these will get removed in a future release, too. 232Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead. 233 234System emulator machines 235------------------------ 236 237Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 238'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 239 240The ``dtb-kaslr-seed`` property on the ``virt`` board has been 241deprecated; use the new name ``dtb-randomness`` instead. The new name 242better reflects the way this property affects all random data within 243the device tree blob, not just the ``kaslr-seed`` node. 244 245``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) 246'''''''''''''''''''''''''''''''''''''''''''''''''''''' 247 248These old machine types are quite neglected nowadays and thus might have 249various pitfalls with regards to live migration. Use a newer machine type 250instead. 251 252PPC 405 ``ref405ep`` machine (since 9.1) 253'''''''''''''''''''''''''''''''''''''''' 254 255The ``ref405ep`` machine and PPC 405 CPU have no known users, firmware 256images are not available, OpenWRT dropped support in 2019, U-Boot in 2572017, Linux also is dropping support in 2024. It is time to let go of 258this ancient hardware and focus on newer CPUs and platforms. 259 260Big-Endian variants of MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines (since 9.2) 261'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 262 263Both ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` were added for little endian 264CPUs. Big endian support is not tested. 265 266Backend options 267--------------- 268 269Using non-persistent backing file with pmem=on (since 6.1) 270'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 271 272This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 273device. However enabling ``memory-backend-file.pmem`` option, when backing file 274is (a) not DAX capable or (b) not on a filesystem that support direct mapping 275of persistent memory, is not safe and may lead to data loss or corruption in case 276of host crash. 277Options are: 278 279 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 280 (without persistence guaranties) with backing file on non DAX storage 281 - move backing file to NVDIMM storage and keep ``pmem=on`` 282 (to have NVDIMM with persistence guaranties). 283 284Device options 285-------------- 286 287Emulated device options 288''''''''''''''''''''''' 289 290``-device nvme-ns,eui64-default=on|off`` (since 7.1) 291^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 292 293In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 294identifier that is not globally unique. If an EUI-64 identifier is required, the 295user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 296 297``-device nvme,use-intel-id=on|off`` (since 7.1) 298^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 299 300The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 301from Intel that was not properly allocated. Since version 5.2, the controller 302has used a properly allocated identifier. Deprecate the ``use-intel-id`` 303machine compatibility parameter. 304 305``-device cxl-type3,memdev=xxxx`` (since 8.0) 306^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 307 308The ``cxl-type3`` device initially only used a single memory backend. With 309the addition of volatile memory support, it is now necessary to distinguish 310between persistent and volatile memory backends. As such, memdev is deprecated 311in favor of persistent-memdev. 312 313 314RISC-V CPU properties which start with capital 'Z' (since 8.2) 315^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 316 317All RISC-V CPU properties which start with capital 'Z' are being deprecated 318starting in 8.2. The reason is that they were wrongly added with capital 'Z' 319in the past. CPU properties were later added with lower-case names, which 320is the format we want to use from now on. 321 322Users which try to use these deprecated properties will receive a warning 323recommending to switch to their stable counterparts: 324 325- "Zifencei" should be replaced with "zifencei" 326- "Zicsr" should be replaced with "zicsr" 327- "Zihintntl" should be replaced with "zihintntl" 328- "Zihintpause" should be replaced with "zihintpause" 329- "Zawrs" should be replaced with "zawrs" 330- "Zfa" should be replaced with "zfa" 331- "Zfh" should be replaced with "zfh" 332- "Zfhmin" should be replaced with "zfhmin" 333- "Zve32f" should be replaced with "zve32f" 334- "Zve64f" should be replaced with "zve64f" 335- "Zve64d" should be replaced with "zve64d" 336 337``-device sd-card,spec_version=1`` (since 9.1) 338^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 339 340SD physical layer specification v2.00 supersedes the v1.10 one. 341v2.00 is the default since QEMU 3.0.0. 342 343Block device options 344'''''''''''''''''''' 345 346``"backing": ""`` (since 2.12) 347^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 348 349In order to prevent QEMU from automatically opening an image's backing 350chain, use ``"backing": null`` instead. 351 352``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 353^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 354 355Options for ``rbd`` should be specified according to its runtime options, 356like other block drivers. Legacy parsing of keyvalue pair encoded 357filenames is useful to open images with the old format for backing files; 358These image files should be updated to use the current format. 359 360Example of legacy encoding:: 361 362 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 363 364The above, converted to the current supported format:: 365 366 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 367 368``iscsi,password=xxx`` (since 8.0) 369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 370 371Specifying the iSCSI password in plain text on the command line using the 372``password`` option is insecure. The ``password-secret`` option should be 373used instead, to refer to a ``--object secret...`` instance that provides 374a password via a file, or encrypted. 375 376``gluster`` backend (since 9.2) 377^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 378 379According to https://marc.info/?l=fedora-devel-list&m=171934833215726 380the GlusterFS development effectively ended. Unless the development 381gains momentum again, the QEMU project will remove the gluster backend 382in a future release. 383 384 385Character device options 386'''''''''''''''''''''''' 387 388Backend ``memory`` (since 9.0) 389^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 390 391``memory`` is a deprecated synonym for ``ringbuf``. 392 393``reconnect`` (since 9.2) 394^^^^^^^^^^^^^^^^^^^^^^^^^ 395 396The ``reconnect`` option only allows specifiying second granularity timeouts, 397which is not enough for all types of use cases, use ``reconnect-ms`` instead. 398 399 400Net device options 401'''''''''''''''''' 402 403Stream ``reconnect`` (since 9.2) 404^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 405 406The ``reconnect`` option only allows specifiying second granularity timeouts, 407which is not enough for all types of use cases, use ``reconnect-ms`` instead. 408 409CPU device properties 410''''''''''''''''''''' 411 412``pcommit`` on x86 (since 9.1) 413^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 414 415The PCOMMIT instruction was never included in any physical processor. 416It was implemented as a no-op instruction in TCG up to QEMU 9.0, but 417only with ``-cpu max`` (which does not guarantee migration compatibility 418across versions). 419 420``pmu-num=n`` on RISC-V CPUs (since 8.2) 421^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 422 423In order to support more flexible counter configurations this has been replaced 424by a ``pmu-mask`` property. If set of counters is continuous then the mask can 425be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 426must be left clear. 427 428 429Backwards compatibility 430----------------------- 431 432Runnability guarantee of CPU models (since 4.1) 433''''''''''''''''''''''''''''''''''''''''''''''' 434 435Previous versions of QEMU never changed existing CPU models in 436ways that introduced additional host software or hardware 437requirements to the VM. This allowed management software to 438safely change the machine type of an existing VM without 439introducing new requirements ("runnability guarantee"). This 440prevented CPU models from being updated to include CPU 441vulnerability mitigations, leaving guests vulnerable in the 442default configuration. 443 444The CPU model runnability guarantee won't apply anymore to 445existing CPU models. Management software that needs runnability 446guarantees must resolve the CPU model aliases using the 447``alias-of`` field returned by the ``query-cpu-definitions`` QMP 448command. 449 450While those guarantees are kept, the return value of 451``query-cpu-definitions`` will have existing CPU model aliases 452point to a version that doesn't break runnability guarantees 453(specifically, version 1 of those CPU models). In future QEMU 454versions, aliases will point to newer CPU model versions 455depending on the machine type, so management software must 456resolve CPU model aliases before starting a virtual machine. 457 458RISC-V "virt" board "riscv,delegate" DT property (since 9.1) 459'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 460 461The "riscv,delegate" DT property was added in QEMU 7.0 as part of 462the AIA APLIC support. The property changed name during the review 463process in Linux and the correct name ended up being 464"riscv,delegation". Changing the DT property name will break all 465available firmwares that are using the current (wrong) name. The 466property is kept as is in 9.1, together with "riscv,delegation", to 467give more time for firmware developers to change their code. 468 469Migration 470--------- 471 472``fd:`` URI when used for file migration (since 9.1) 473'''''''''''''''''''''''''''''''''''''''''''''''''''' 474 475The ``fd:`` URI can currently provide a file descriptor that 476references either a socket or a plain file. These are two different 477types of migration. In order to reduce ambiguity, the ``fd:`` URI 478usage of providing a file descriptor to a plain file has been 479deprecated in favor of explicitly using the ``file:`` URI with the 480file descriptor being passed as an ``fdset``. Refer to the ``add-fd`` 481command documentation for details on the ``fdset`` usage. 482 483``zero-blocks`` capability (since 9.2) 484'''''''''''''''''''''''''''''''''''''' 485 486The ``zero-blocks`` capability was part of the block migration which 487doesn't exist anymore since it was removed in QEMU v9.1. 488