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 27What follows is a list of all features currently marked as 28deprecated. 29 30System emulator command line arguments 31-------------------------------------- 32 33Short-form boolean options (since 6.0) 34'''''''''''''''''''''''''''''''''''''' 35 36Boolean options such as ``share=on``/``share=off`` could be written 37in short form as ``share`` and ``noshare``. This is now deprecated 38and will cause a warning. 39 40``delay`` option for socket character devices (since 6.0) 41''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 42 43The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` 44rather than ``delay=off``. 45 46Plugin argument passing through ``arg=<string>`` (since 6.1) 47'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 48 49Passing TCG plugins arguments through ``arg=`` is redundant is makes the 50command-line less readable, especially when the argument itself consist of a 51name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. 52Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated 53as short-form boolean values, and passed to plugins as ``arg_name=on``. 54However, short-form booleans are deprecated and full explicit ``arg_name=on`` 55form is preferred. 56 57``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0) 58''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 59 60Specified CPU topology parameters must be supported by the machine. 61 62In the SMP configuration, users should provide the CPU topology parameters that 63are supported by the target machine. 64 65However, historically it was allowed for users to specify the unsupported 66topology parameter as "1", which is meaningless. So support for this kind of 67configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is 68marked deprecated since 9.0, users have to ensure that all the topology members 69described with -smp are supported by the target machine. 70 71``-old-param`` option for booting Arm kernels via param_struct (since 10.0) 72''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 73 74The ``-old-param`` command line option is specific to Arm targets: 75it is used when directly booting a guest kernel to pass it the 76command line and other information via the old ``param_struct`` ABI, 77rather than the newer ATAGS or DTB mechanisms. This option was only 78ever needed to support ancient kernels on some old board types 79like the ``akita`` or ``terrier``; it has been deprecated in the 80kernel since 2001. None of the board types QEMU supports need 81``param_struct`` support, so this option has been deprecated and will 82be removed in a future QEMU version. 83 84User-mode emulator command line arguments 85----------------------------------------- 86 87``-p`` (since 9.0) 88'''''''''''''''''' 89 90The ``-p`` option pretends to control the host page size. However, 91it is not possible to change the host page size, and using the 92option only causes failures. 93 94QEMU Machine Protocol (QMP) commands 95------------------------------------ 96 97``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 98''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 99 100Use argument ``id`` instead. 101 102``eject`` argument ``device`` (since 2.8) 103''''''''''''''''''''''''''''''''''''''''' 104 105Use argument ``id`` instead. 106 107``blockdev-change-medium`` argument ``device`` (since 2.8) 108'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 109 110Use argument ``id`` instead. 111 112``block_set_io_throttle`` argument ``device`` (since 2.8) 113''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 114 115Use argument ``id`` instead. 116 117``blockdev-add`` empty string argument ``backing`` (since 2.10) 118''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 119 120Use argument value ``null`` instead. 121 122``block-commit`` arguments ``base`` and ``top`` (since 3.1) 123''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 124 125Use arguments ``base-node`` and ``top-node`` instead. 126 127``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 128'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 129 130Use the more generic commands ``block-export-add`` and ``block-export-del`` 131instead. As part of this deprecation, where ``nbd-server-add`` used a 132single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 133 134``query-qmp-schema`` return value member ``values`` (since 6.2) 135''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 136 137Member ``values`` in return value elements with meta-type ``enum`` is 138deprecated. Use ``members`` instead. 139 140``drive-backup`` (since 6.2) 141'''''''''''''''''''''''''''' 142 143Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 144This change primarily separates the creation/opening process of the backup 145target with explicit, separate steps. ``blockdev-backup`` uses mostly the 146same arguments as ``drive-backup``, except the ``format`` and ``mode`` 147options are removed in favor of using explicit ``blockdev-create`` and 148``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 149details. 150 151``query-migrationthreads`` (since 9.2) 152'''''''''''''''''''''''''''''''''''''' 153 154To be removed with no replacement, as it reports only a limited set of 155threads (for example, it only reports source side of multifd threads, 156without reporting any destination threads, or non-multifd source threads). 157For debugging purpose, please use ``-name $VM,debug-threads=on`` instead. 158 159Incorrectly typed ``device_add`` arguments (since 6.2) 160'''''''''''''''''''''''''''''''''''''''''''''''''''''' 161 162Due to shortcomings in the internal implementation of ``device_add``, QEMU 163incorrectly accepts certain invalid arguments: Any object or list arguments are 164silently ignored. Other argument types are not checked, but an implicit 165conversion happens, so that e.g. string values can be assigned to integer 166device properties or vice versa. 167 168This is a bug in QEMU that will be fixed in the future so that previously 169accepted incorrect commands will return an error. Users should make sure that 170all arguments passed to ``device_add`` are consistent with the documented 171property types. 172 173Host Architectures 174------------------ 175 176Big endian MIPS since 7.2; 32-bit little endian MIPS since 9.2 177'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 178 179As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 180MIPS moved out of support making it hard to maintain our 181cross-compilation CI tests of the architecture. As we no longer have 182CI coverage support may bitrot away before the deprecation process 183completes. 184 185Likewise, the little endian variant of 32 bit MIPS is not supported by 186Debian 13 ("Trixie") and newer. 187 18864 bit little endian MIPS is still a supported host architecture. 189 190System emulation on 32-bit x86 hosts (since 8.0) 191'''''''''''''''''''''''''''''''''''''''''''''''' 192 193Support for 32-bit x86 host deployments is increasingly uncommon in mainstream 194OS distributions given the widespread availability of 64-bit x86 hardware. 195The QEMU project no longer considers 32-bit x86 support for system emulation to 196be an effective use of its limited resources, and thus intends to discontinue 197it. Since all recent x86 hardware from the past >10 years is capable of the 19864-bit x86 extensions, a corresponding 64-bit OS should be used instead. 199 200TCG Plugin support not enabled by default on 32-bit hosts (since 9.2) 201''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 202 203While it is still possible to enable TCG plugin support for 32-bit 204hosts there are a number of potential pitfalls when instrumenting 20564-bit guests. The plugin APIs typically pass most addresses as 206uint64_t but practices like encoding that address in a host pointer 207for passing as user-data will lose data. As most software analysis 208benefits from having plenty of host memory it seems reasonable to 209encourage users to use 64 bit builds of QEMU for analysis work 210whatever targets they are instrumenting. 211 212TCG Plugin support not enabled by default with TCI (since 9.2) 213'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 214 215While the TCG interpreter can interpret the TCG ops used by plugins it 216is going to be so much slower it wouldn't make sense for any serious 217instrumentation. Due to implementation differences there will also be 218anomalies in things like memory instrumentation. 219 22032-bit host operating systems (since 10.0) 221'''''''''''''''''''''''''''''''''''''''''' 222 223Keeping 32-bit host support alive is a substantial burden for the 224QEMU project. Thus QEMU will in future drop the support for all 22532-bit host systems. 226 227linux-user mode CPUs 228-------------------- 229 230iwMMXt emulation and the ``pxa`` CPUs (since 10.0) 231'''''''''''''''''''''''''''''''''''''''''''''''''' 232 233The ``pxa`` CPU family (``pxa250``, ``pxa255``, ``pxa260``, 234``pxa261``, ``pxa262``, ``pxa270-a0``, ``pxa270-a1``, ``pxa270``, 235``pxa270-b0``, ``pxa270-b1``, ``pxa270-c0``, ``pxa270-c5``) are no 236longer used in system emulation, because all the machine types which 237used these CPUs were removed in the QEMU 9.2 release. These CPUs can 238now only be used in linux-user mode, and to do that you would have to 239explicitly select one of these CPUs with the ``-cpu`` command line 240option or the ``QEMU_CPU`` environment variable. 241 242We don't believe that anybody is using the iwMMXt emulation, and we do 243not have any tests to validate it or any real hardware or similar 244known-good implementation to test against. GCC is in the process of 245dropping their support for iwMMXt codegen. These CPU types are 246therefore deprecated in QEMU, and will be removed in a future release. 247 248System emulator CPUs 249-------------------- 250 251``power5+`` and ``power7+`` CPU names (since 9.0) 252''''''''''''''''''''''''''''''''''''''''''''''''' 253 254The character "+" in device (and thus also CPU) names is not allowed 255in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 256``power7+`` and ``power7+_v2.1`` are currently still supported via 257an alias, but for consistency these will get removed in a future 258release, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 259 260``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1) 261''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 262 263The character "+" in device (and thus also CPU) names is not allowed 264in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and 265``Sun-UltraSparc-IV+`` are currently still supported via a workaround, 266but for consistency these will get removed in a future release, too. 267Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead. 268 269PPC 405 CPUs (since 10.0) 270''''''''''''''''''''''''' 271 272The PPC 405 CPU has no known users and the ``ref405ep`` machine was 273removed in QEMU 10.0. Since the IBM POWER [8-11] processors uses an 274embedded 405 for power management (OCC) and other internal tasks, it 275is theoretically possible to use QEMU to model them. Let's keep the 276CPU implementation for a while before removing all support. 277 278System emulator machines 279------------------------ 280 281Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 282'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 283 284The ``dtb-kaslr-seed`` property on the ``virt`` board has been 285deprecated; use the new name ``dtb-randomness`` instead. The new name 286better reflects the way this property affects all random data within 287the device tree blob, not just the ``kaslr-seed`` node. 288 289Big-Endian variants of MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines (since 9.2) 290'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 291 292Both ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` were added for little endian 293CPUs. Big endian support is not tested. 294 295Backend options 296--------------- 297 298Using non-persistent backing file with pmem=on (since 6.1) 299'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 300 301This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 302device. However enabling ``memory-backend-file.pmem`` option, when backing file 303is (a) not DAX capable or (b) not on a filesystem that support direct mapping 304of persistent memory, is not safe and may lead to data loss or corruption in case 305of host crash. 306Options are: 307 308 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 309 (without persistence guaranties) with backing file on non DAX storage 310 - move backing file to NVDIMM storage and keep ``pmem=on`` 311 (to have NVDIMM with persistence guaranties). 312 313Device options 314-------------- 315 316Emulated device options 317''''''''''''''''''''''' 318 319``-device nvme-ns,eui64-default=on|off`` (since 7.1) 320^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 321 322In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 323identifier that is not globally unique. If an EUI-64 identifier is required, the 324user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 325 326``-device nvme,use-intel-id=on|off`` (since 7.1) 327^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 328 329The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 330from Intel that was not properly allocated. Since version 5.2, the controller 331has used a properly allocated identifier. Deprecate the ``use-intel-id`` 332machine compatibility parameter. 333 334``-device cxl-type3,memdev=xxxx`` (since 8.0) 335^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 336 337The ``cxl-type3`` device initially only used a single memory backend. With 338the addition of volatile memory support, it is now necessary to distinguish 339between persistent and volatile memory backends. As such, memdev is deprecated 340in favor of persistent-memdev. 341 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 sd-card,spec_version=1`` (since 9.1) 367^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 368 369SD physical layer specification v2.00 supersedes the v1.10 one. 370v2.00 is the default since QEMU 3.0.0. 371 372Block device options 373'''''''''''''''''''' 374 375``"backing": ""`` (since 2.12) 376^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 377 378In order to prevent QEMU from automatically opening an image's backing 379chain, use ``"backing": null`` instead. 380 381``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 382^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 383 384Options for ``rbd`` should be specified according to its runtime options, 385like other block drivers. Legacy parsing of keyvalue pair encoded 386filenames is useful to open images with the old format for backing files; 387These image files should be updated to use the current format. 388 389Example of legacy encoding:: 390 391 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 392 393The above, converted to the current supported format:: 394 395 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 396 397``iscsi,password=xxx`` (since 8.0) 398^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 399 400Specifying the iSCSI password in plain text on the command line using the 401``password`` option is insecure. The ``password-secret`` option should be 402used instead, to refer to a ``--object secret...`` instance that provides 403a password via a file, or encrypted. 404 405``gluster`` backend (since 9.2) 406^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 407 408According to https://marc.info/?l=fedora-devel-list&m=171934833215726 409the GlusterFS development effectively ended. Unless the development 410gains momentum again, the QEMU project will remove the gluster backend 411in a future release. 412 413 414Character device options 415'''''''''''''''''''''''' 416 417Backend ``memory`` (since 9.0) 418^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 419 420``memory`` is a deprecated synonym for ``ringbuf``. 421 422``reconnect`` (since 9.2) 423^^^^^^^^^^^^^^^^^^^^^^^^^ 424 425The ``reconnect`` option only allows specifiying second granularity timeouts, 426which is not enough for all types of use cases, use ``reconnect-ms`` instead. 427 428 429Net device options 430'''''''''''''''''' 431 432Stream ``reconnect`` (since 9.2) 433^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 434 435The ``reconnect`` option only allows specifiying second granularity timeouts, 436which is not enough for all types of use cases, use ``reconnect-ms`` instead. 437 438VFIO device options 439''''''''''''''''''' 440 441``-device vfio-calxeda-xgmac`` (since 10.0) 442^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 443The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank 44410Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility 445string) to a guest. Calxeda HW has been ewasted now and there is no point 446keeping that device. 447 448``-device vfio-amd-xgbe`` (since 10.0) 449^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 450The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller 451to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle" 452is not supported anymore and there is no point keeping that device. 453 454``-device vfio-platform`` (since 10.0) 455^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 456The vfio-platform device allows to assign a host platform device 457to a guest in a generic manner. Integrating a new device into 458the vfio-platform infrastructure requires some adaptation at 459both kernel and qemu level. No such attempt has been done for years 460and the conclusion is that vfio-platform has not got any traction. 461PCIe passthrough shall be the mainline solution. 462 463CPU device properties 464''''''''''''''''''''' 465 466``pcommit`` on x86 (since 9.1) 467^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 468 469The PCOMMIT instruction was never included in any physical processor. 470It was implemented as a no-op instruction in TCG up to QEMU 9.0, but 471only with ``-cpu max`` (which does not guarantee migration compatibility 472across versions). 473 474``pmu-num=n`` on RISC-V CPUs (since 8.2) 475^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 476 477In order to support more flexible counter configurations this has been replaced 478by a ``pmu-mask`` property. If set of counters is continuous then the mask can 479be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 480must be left clear. 481 482 483Backwards compatibility 484----------------------- 485 486Runnability guarantee of CPU models (since 4.1) 487''''''''''''''''''''''''''''''''''''''''''''''' 488 489Previous versions of QEMU never changed existing CPU models in 490ways that introduced additional host software or hardware 491requirements to the VM. This allowed management software to 492safely change the machine type of an existing VM without 493introducing new requirements ("runnability guarantee"). This 494prevented CPU models from being updated to include CPU 495vulnerability mitigations, leaving guests vulnerable in the 496default configuration. 497 498The CPU model runnability guarantee won't apply anymore to 499existing CPU models. Management software that needs runnability 500guarantees must resolve the CPU model aliases using the 501``alias-of`` field returned by the ``query-cpu-definitions`` QMP 502command. 503 504While those guarantees are kept, the return value of 505``query-cpu-definitions`` will have existing CPU model aliases 506point to a version that doesn't break runnability guarantees 507(specifically, version 1 of those CPU models). In future QEMU 508versions, aliases will point to newer CPU model versions 509depending on the machine type, so management software must 510resolve CPU model aliases before starting a virtual machine. 511 512RISC-V "virt" board "riscv,delegate" DT property (since 9.1) 513'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 514 515The "riscv,delegate" DT property was added in QEMU 7.0 as part of 516the AIA APLIC support. The property changed name during the review 517process in Linux and the correct name ended up being 518"riscv,delegation". Changing the DT property name will break all 519available firmwares that are using the current (wrong) name. The 520property is kept as is in 9.1, together with "riscv,delegation", to 521give more time for firmware developers to change their code. 522 523Migration 524--------- 525 526``fd:`` URI when used for file migration (since 9.1) 527'''''''''''''''''''''''''''''''''''''''''''''''''''' 528 529The ``fd:`` URI can currently provide a file descriptor that 530references either a socket or a plain file. These are two different 531types of migration. In order to reduce ambiguity, the ``fd:`` URI 532usage of providing a file descriptor to a plain file has been 533deprecated in favor of explicitly using the ``file:`` URI with the 534file descriptor being passed as an ``fdset``. Refer to the ``add-fd`` 535command documentation for details on the ``fdset`` usage. 536 537``zero-blocks`` capability (since 9.2) 538'''''''''''''''''''''''''''''''''''''' 539 540The ``zero-blocks`` capability was part of the block migration which 541doesn't exist anymore since it was removed in QEMU v9.1. 542