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 77``-runas`` (since 9.1) 78---------------------- 79 80Use ``-run-with user=..`` instead. 81 82 83User-mode emulator command line arguments 84----------------------------------------- 85 86``-p`` (since 9.0) 87'''''''''''''''''' 88 89The ``-p`` option pretends to control the host page size. However, 90it is not possible to change the host page size, and using the 91option only causes failures. 92 93QEMU Machine Protocol (QMP) commands 94------------------------------------ 95 96``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) 97''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 98 99Use argument ``id`` instead. 100 101``eject`` argument ``device`` (since 2.8) 102''''''''''''''''''''''''''''''''''''''''' 103 104Use argument ``id`` instead. 105 106``blockdev-change-medium`` argument ``device`` (since 2.8) 107'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 108 109Use argument ``id`` instead. 110 111``block_set_io_throttle`` argument ``device`` (since 2.8) 112''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 113 114Use argument ``id`` instead. 115 116``blockdev-add`` empty string argument ``backing`` (since 2.10) 117''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 118 119Use argument value ``null`` instead. 120 121``block-commit`` arguments ``base`` and ``top`` (since 3.1) 122''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 123 124Use arguments ``base-node`` and ``top-node`` instead. 125 126``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) 127'''''''''''''''''''''''''''''''''''''''''''''''''''''''' 128 129Use the more generic commands ``block-export-add`` and ``block-export-del`` 130instead. As part of this deprecation, where ``nbd-server-add`` used a 131single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. 132 133``query-qmp-schema`` return value member ``values`` (since 6.2) 134''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 135 136Member ``values`` in return value elements with meta-type ``enum`` is 137deprecated. Use ``members`` instead. 138 139``drive-backup`` (since 6.2) 140'''''''''''''''''''''''''''' 141 142Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. 143This change primarily separates the creation/opening process of the backup 144target with explicit, separate steps. ``blockdev-backup`` uses mostly the 145same arguments as ``drive-backup``, except the ``format`` and ``mode`` 146options are removed in favor of using explicit ``blockdev-create`` and 147``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for 148details. 149 150Incorrectly typed ``device_add`` arguments (since 6.2) 151'''''''''''''''''''''''''''''''''''''''''''''''''''''' 152 153Due to shortcomings in the internal implementation of ``device_add``, QEMU 154incorrectly accepts certain invalid arguments: Any object or list arguments are 155silently ignored. Other argument types are not checked, but an implicit 156conversion happens, so that e.g. string values can be assigned to integer 157device properties or vice versa. 158 159This is a bug in QEMU that will be fixed in the future so that previously 160accepted incorrect commands will return an error. Users should make sure that 161all arguments passed to ``device_add`` are consistent with the documented 162property types. 163 164Host Architectures 165------------------ 166 167BE MIPS (since 7.2) 168''''''''''''''''''' 169 170As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of 171MIPS moved out of support making it hard to maintain our 172cross-compilation CI tests of the architecture. As we no longer have 173CI coverage support may bitrot away before the deprecation process 174completes. The little endian variants of MIPS (both 32 and 64 bit) are 175still a supported host architecture. 176 177System emulation on 32-bit x86 hosts (since 8.0) 178'''''''''''''''''''''''''''''''''''''''''''''''' 179 180Support for 32-bit x86 host deployments is increasingly uncommon in mainstream 181OS distributions given the widespread availability of 64-bit x86 hardware. 182The QEMU project no longer considers 32-bit x86 support for system emulation to 183be an effective use of its limited resources, and thus intends to discontinue 184it. Since all recent x86 hardware from the past >10 years is capable of the 18564-bit x86 extensions, a corresponding 64-bit OS should be used instead. 186 187TCG Plugin support not enabled by default on 32-bit hosts (since 9.2) 188''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 189 190While it is still possible to enable TCG plugin support for 32-bit 191hosts there are a number of potential pitfalls when instrumenting 19264-bit guests. The plugin APIs typically pass most addresses as 193uint64_t but practices like encoding that address in a host pointer 194for passing as user-data will lose data. As most software analysis 195benefits from having plenty of host memory it seems reasonable to 196encourage users to use 64 bit builds of QEMU for analysis work 197whatever targets they are instrumenting. 198 199TCG Plugin support not enabled by default with TCI (since 9.2) 200'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 201 202While the TCG interpreter can interpret the TCG ops used by plugins it 203is going to be so much slower it wouldn't make sense for any serious 204instrumentation. Due to implementation differences there will also be 205anomalies in things like memory instrumentation. 206 207System emulator CPUs 208-------------------- 209 210``power5+`` and ``power7+`` CPU names (since 9.0) 211''''''''''''''''''''''''''''''''''''''''''''''''' 212 213The character "+" in device (and thus also CPU) names is not allowed 214in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``, 215``power7+`` and ``power7+_v2.1`` are currently still supported via 216an alias, but for consistency these will get removed in a future 217release, too. Use ``power5p_v2.1`` and ``power7p_v2.1`` instead. 218 219``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1) 220''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 221 222The character "+" in device (and thus also CPU) names is not allowed 223in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and 224``Sun-UltraSparc-IV+`` are currently still supported via a workaround, 225but for consistency these will get removed in a future release, too. 226Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead. 227 228System emulator machines 229------------------------ 230 231Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1) 232'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 233 234The ``dtb-kaslr-seed`` property on the ``virt`` board has been 235deprecated; use the new name ``dtb-randomness`` instead. The new name 236better reflects the way this property affects all random data within 237the device tree blob, not just the ``kaslr-seed`` node. 238 239``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) 240'''''''''''''''''''''''''''''''''''''''''''''''''''''' 241 242These old machine types are quite neglected nowadays and thus might have 243various pitfalls with regards to live migration. Use a newer machine type 244instead. 245 246``pseries-2.1`` up to ``pseries-2.12`` (since 9.0) 247'''''''''''''''''''''''''''''''''''''''''''''''''' 248 249Older pseries machines before version 3.0 have undergone many changes 250to correct issues, mostly regarding migration compatibility. These are 251no longer maintained and removing them will make the code easier to 252read and maintain. Use versions 3.0 and above as a replacement. 253 254PPC 405 ``ref405ep`` machine (since 9.1) 255'''''''''''''''''''''''''''''''''''''''' 256 257The ``ref405ep`` machine and PPC 405 CPU have no known users, firmware 258images are not available, OpenWRT dropped support in 2019, U-Boot in 2592017, Linux also is dropping support in 2024. It is time to let go of 260this ancient hardware and focus on newer CPUs and platforms. 261 262Arm ``tacoma-bmc`` machine (since 9.1) 263'''''''''''''''''''''''''''''''''''''''' 264 265The ``tacoma-bmc`` machine was a board including an AST2600 SoC based 266BMC and a witherspoon like OpenPOWER system. It was used for bring up 267of the AST2600 SoC in labs. It can be easily replaced by the 268``rainier-bmc`` machine which is a real product. 269 270Backend options 271--------------- 272 273Using non-persistent backing file with pmem=on (since 6.1) 274'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 275 276This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 277device. However enabling ``memory-backend-file.pmem`` option, when backing file 278is (a) not DAX capable or (b) not on a filesystem that support direct mapping 279of persistent memory, is not safe and may lead to data loss or corruption in case 280of host crash. 281Options are: 282 283 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 284 (without persistence guaranties) with backing file on non DAX storage 285 - move backing file to NVDIMM storage and keep ``pmem=on`` 286 (to have NVDIMM with persistence guaranties). 287 288Device options 289-------------- 290 291Emulated device options 292''''''''''''''''''''''' 293 294``-device nvme-ns,eui64-default=on|off`` (since 7.1) 295^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 296 297In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 298identifier that is not globally unique. If an EUI-64 identifier is required, the 299user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 300 301``-device nvme,use-intel-id=on|off`` (since 7.1) 302^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 303 304The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 305from Intel that was not properly allocated. Since version 5.2, the controller 306has used a properly allocated identifier. Deprecate the ``use-intel-id`` 307machine compatibility parameter. 308 309``-device cxl-type3,memdev=xxxx`` (since 8.0) 310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 311 312The ``cxl-type3`` device initially only used a single memory backend. With 313the addition of volatile memory support, it is now necessary to distinguish 314between persistent and volatile memory backends. As such, memdev is deprecated 315in favor of persistent-memdev. 316 317``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 318^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 319 320The 9p ``proxy`` filesystem backend driver has been deprecated and will be 321removed (along with its proxy helper daemon) in a future version of QEMU. Please 322use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 323backend, or alternatively consider deploying virtiofsd instead. 324 325The 9p ``proxy`` backend was originally developed as an alternative to the 9p 326``local`` backend. The idea was to enhance security by dispatching actual low 327level filesystem operations from 9p server (QEMU process) over to a separate 328process (the virtfs-proxy-helper binary). However this alternative never gained 329momentum. The proxy backend is much slower than the local backend, hasn't seen 330any development in years, and showed to be less secure, especially due to the 331fact that its helper daemon must be run as root, whereas with the local backend 332QEMU is typically run as unprivileged user and allows to tighten behaviour by 333mapping permissions et al by using its 'mapped' security model option. 334 335Nowadays it would make sense to reimplement the ``proxy`` backend by using 336QEMU's ``vhost`` feature, which would eliminate the high latency costs under 337which the 9p ``proxy`` backend currently suffers. However as of to date nobody 338has indicated plans for such kind of reimplementation unfortunately. 339 340RISC-V CPU properties which start with capital 'Z' (since 8.2) 341^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 342 343All RISC-V CPU properties which start with capital 'Z' are being deprecated 344starting in 8.2. The reason is that they were wrongly added with capital 'Z' 345in the past. CPU properties were later added with lower-case names, which 346is the format we want to use from now on. 347 348Users which try to use these deprecated properties will receive a warning 349recommending to switch to their stable counterparts: 350 351- "Zifencei" should be replaced with "zifencei" 352- "Zicsr" should be replaced with "zicsr" 353- "Zihintntl" should be replaced with "zihintntl" 354- "Zihintpause" should be replaced with "zihintpause" 355- "Zawrs" should be replaced with "zawrs" 356- "Zfa" should be replaced with "zfa" 357- "Zfh" should be replaced with "zfh" 358- "Zfhmin" should be replaced with "zfhmin" 359- "Zve32f" should be replaced with "zve32f" 360- "Zve64f" should be replaced with "zve64f" 361- "Zve64d" should be replaced with "zve64d" 362 363``-device sd-card,spec_version=1`` (since 9.1) 364^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 365 366SD physical layer specification v2.00 supersedes the v1.10 one. 367v2.00 is the default since QEMU 3.0.0. 368 369Block device options 370'''''''''''''''''''' 371 372``"backing": ""`` (since 2.12) 373^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 374 375In order to prevent QEMU from automatically opening an image's backing 376chain, use ``"backing": null`` instead. 377 378``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 379^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 380 381Options for ``rbd`` should be specified according to its runtime options, 382like other block drivers. Legacy parsing of keyvalue pair encoded 383filenames is useful to open images with the old format for backing files; 384These image files should be updated to use the current format. 385 386Example of legacy encoding:: 387 388 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 389 390The above, converted to the current supported format:: 391 392 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 393 394``iscsi,password=xxx`` (since 8.0) 395^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 396 397Specifying the iSCSI password in plain text on the command line using the 398``password`` option is insecure. The ``password-secret`` option should be 399used instead, to refer to a ``--object secret...`` instance that provides 400a password via a file, or encrypted. 401 402Character device options 403'''''''''''''''''''''''' 404 405Backend ``memory`` (since 9.0) 406^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 407 408``memory`` is a deprecated synonym for ``ringbuf``. 409 410CPU device properties 411''''''''''''''''''''' 412 413``pcommit`` on x86 (since 9.1) 414^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 415 416The PCOMMIT instruction was never included in any physical processor. 417It was implemented as a no-op instruction in TCG up to QEMU 9.0, but 418only with ``-cpu max`` (which does not guarantee migration compatibility 419across versions). 420 421``pmu-num=n`` on RISC-V CPUs (since 8.2) 422^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 423 424In order to support more flexible counter configurations this has been replaced 425by a ``pmu-mask`` property. If set of counters is continuous then the mask can 426be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 427must be left clear. 428 429 430Backwards compatibility 431----------------------- 432 433Runnability guarantee of CPU models (since 4.1) 434''''''''''''''''''''''''''''''''''''''''''''''' 435 436Previous versions of QEMU never changed existing CPU models in 437ways that introduced additional host software or hardware 438requirements to the VM. This allowed management software to 439safely change the machine type of an existing VM without 440introducing new requirements ("runnability guarantee"). This 441prevented CPU models from being updated to include CPU 442vulnerability mitigations, leaving guests vulnerable in the 443default configuration. 444 445The CPU model runnability guarantee won't apply anymore to 446existing CPU models. Management software that needs runnability 447guarantees must resolve the CPU model aliases using the 448``alias-of`` field returned by the ``query-cpu-definitions`` QMP 449command. 450 451While those guarantees are kept, the return value of 452``query-cpu-definitions`` will have existing CPU model aliases 453point to a version that doesn't break runnability guarantees 454(specifically, version 1 of those CPU models). In future QEMU 455versions, aliases will point to newer CPU model versions 456depending on the machine type, so management software must 457resolve CPU model aliases before starting a virtual machine. 458 459RISC-V "virt" board "riscv,delegate" DT property (since 9.1) 460'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 461 462The "riscv,delegate" DT property was added in QEMU 7.0 as part of 463the AIA APLIC support. The property changed name during the review 464process in Linux and the correct name ended up being 465"riscv,delegation". Changing the DT property name will break all 466available firmwares that are using the current (wrong) name. The 467property is kept as is in 9.1, together with "riscv,delegation", to 468give more time for firmware developers to change their code. 469 470Migration 471--------- 472 473``fd:`` URI when used for file migration (since 9.1) 474'''''''''''''''''''''''''''''''''''''''''''''''''''' 475 476The ``fd:`` URI can currently provide a file descriptor that 477references either a socket or a plain file. These are two different 478types of migration. In order to reduce ambiguity, the ``fd:`` URI 479usage of providing a file descriptor to a plain file has been 480deprecated in favor of explicitly using the ``file:`` URI with the 481file descriptor being passed as an ``fdset``. Refer to the ``add-fd`` 482command documentation for details on the ``fdset`` usage. 483