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 254Arm machines ``akita``, ``borzoi``, ``cheetah``, ``connex``, ``mainstone``, ``n800``, ``n810``, ``spitz``, ``terrier``, ``tosa``, ``verdex``, ``z2`` (since 9.0) 255'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 256 257QEMU includes models of some machine types where the QEMU code that 258emulates their SoCs is very old and unmaintained. This code is now 259blocking our ability to move forward with various changes across 260the codebase, and over many years nobody has been interested in 261trying to modernise it. We don't expect any of these machines to have 262a large number of users, because they're all modelling hardware that 263has now passed away into history. We are therefore dropping support 264for all machine types using the PXA2xx and OMAP2 SoCs. We are also 265dropping the ``cheetah`` OMAP1 board, because we don't have any 266test images for it and don't know of anybody who does; the ``sx1`` 267and ``sx1-v1`` OMAP1 machines remain supported for now. 268 269PPC 405 ``ref405ep`` machine (since 9.1) 270'''''''''''''''''''''''''''''''''''''''' 271 272The ``ref405ep`` machine and PPC 405 CPU have no known users, firmware 273images are not available, OpenWRT dropped support in 2019, U-Boot in 2742017, Linux also is dropping support in 2024. It is time to let go of 275this ancient hardware and focus on newer CPUs and platforms. 276 277Arm ``tacoma-bmc`` machine (since 9.1) 278'''''''''''''''''''''''''''''''''''''''' 279 280The ``tacoma-bmc`` machine was a board including an AST2600 SoC based 281BMC and a witherspoon like OpenPOWER system. It was used for bring up 282of the AST2600 SoC in labs. It can be easily replaced by the 283``rainier-bmc`` machine which is a real product. 284 285Backend options 286--------------- 287 288Using non-persistent backing file with pmem=on (since 6.1) 289'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 290 291This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM 292device. However enabling ``memory-backend-file.pmem`` option, when backing file 293is (a) not DAX capable or (b) not on a filesystem that support direct mapping 294of persistent memory, is not safe and may lead to data loss or corruption in case 295of host crash. 296Options are: 297 298 - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM 299 (without persistence guaranties) with backing file on non DAX storage 300 - move backing file to NVDIMM storage and keep ``pmem=on`` 301 (to have NVDIMM with persistence guaranties). 302 303Device options 304-------------- 305 306Emulated device options 307''''''''''''''''''''''' 308 309``-device nvme-ns,eui64-default=on|off`` (since 7.1) 310^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 311 312In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 313identifier that is not globally unique. If an EUI-64 identifier is required, the 314user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. 315 316``-device nvme,use-intel-id=on|off`` (since 7.1) 317^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 318 319The ``nvme`` device originally used a PCI Vendor/Device Identifier combination 320from Intel that was not properly allocated. Since version 5.2, the controller 321has used a properly allocated identifier. Deprecate the ``use-intel-id`` 322machine compatibility parameter. 323 324``-device cxl-type3,memdev=xxxx`` (since 8.0) 325^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 326 327The ``cxl-type3`` device initially only used a single memory backend. With 328the addition of volatile memory support, it is now necessary to distinguish 329between persistent and volatile memory backends. As such, memdev is deprecated 330in favor of persistent-memdev. 331 332``-fsdev proxy`` and ``-virtfs proxy`` (since 8.1) 333^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 334 335The 9p ``proxy`` filesystem backend driver has been deprecated and will be 336removed (along with its proxy helper daemon) in a future version of QEMU. Please 337use ``-fsdev local`` or ``-virtfs local`` for using the 9p ``local`` filesystem 338backend, or alternatively consider deploying virtiofsd instead. 339 340The 9p ``proxy`` backend was originally developed as an alternative to the 9p 341``local`` backend. The idea was to enhance security by dispatching actual low 342level filesystem operations from 9p server (QEMU process) over to a separate 343process (the virtfs-proxy-helper binary). However this alternative never gained 344momentum. The proxy backend is much slower than the local backend, hasn't seen 345any development in years, and showed to be less secure, especially due to the 346fact that its helper daemon must be run as root, whereas with the local backend 347QEMU is typically run as unprivileged user and allows to tighten behaviour by 348mapping permissions et al by using its 'mapped' security model option. 349 350Nowadays it would make sense to reimplement the ``proxy`` backend by using 351QEMU's ``vhost`` feature, which would eliminate the high latency costs under 352which the 9p ``proxy`` backend currently suffers. However as of to date nobody 353has indicated plans for such kind of reimplementation unfortunately. 354 355RISC-V CPU properties which start with capital 'Z' (since 8.2) 356^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 357 358All RISC-V CPU properties which start with capital 'Z' are being deprecated 359starting in 8.2. The reason is that they were wrongly added with capital 'Z' 360in the past. CPU properties were later added with lower-case names, which 361is the format we want to use from now on. 362 363Users which try to use these deprecated properties will receive a warning 364recommending to switch to their stable counterparts: 365 366- "Zifencei" should be replaced with "zifencei" 367- "Zicsr" should be replaced with "zicsr" 368- "Zihintntl" should be replaced with "zihintntl" 369- "Zihintpause" should be replaced with "zihintpause" 370- "Zawrs" should be replaced with "zawrs" 371- "Zfa" should be replaced with "zfa" 372- "Zfh" should be replaced with "zfh" 373- "Zfhmin" should be replaced with "zfhmin" 374- "Zve32f" should be replaced with "zve32f" 375- "Zve64f" should be replaced with "zve64f" 376- "Zve64d" should be replaced with "zve64d" 377 378``-device sd-card,spec_version=1`` (since 9.1) 379^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 380 381SD physical layer specification v2.00 supersedes the v1.10 one. 382v2.00 is the default since QEMU 3.0.0. 383 384Block device options 385'''''''''''''''''''' 386 387``"backing": ""`` (since 2.12) 388^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 389 390In order to prevent QEMU from automatically opening an image's backing 391chain, use ``"backing": null`` instead. 392 393``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) 394^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 395 396Options for ``rbd`` should be specified according to its runtime options, 397like other block drivers. Legacy parsing of keyvalue pair encoded 398filenames is useful to open images with the old format for backing files; 399These image files should be updated to use the current format. 400 401Example of legacy encoding:: 402 403 json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} 404 405The above, converted to the current supported format:: 406 407 json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} 408 409``iscsi,password=xxx`` (since 8.0) 410^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 411 412Specifying the iSCSI password in plain text on the command line using the 413``password`` option is insecure. The ``password-secret`` option should be 414used instead, to refer to a ``--object secret...`` instance that provides 415a password via a file, or encrypted. 416 417Character device options 418'''''''''''''''''''''''' 419 420Backend ``memory`` (since 9.0) 421^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 422 423``memory`` is a deprecated synonym for ``ringbuf``. 424 425CPU device properties 426''''''''''''''''''''' 427 428``pcommit`` on x86 (since 9.1) 429^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 430 431The PCOMMIT instruction was never included in any physical processor. 432It was implemented as a no-op instruction in TCG up to QEMU 9.0, but 433only with ``-cpu max`` (which does not guarantee migration compatibility 434across versions). 435 436``pmu-num=n`` on RISC-V CPUs (since 8.2) 437^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 438 439In order to support more flexible counter configurations this has been replaced 440by a ``pmu-mask`` property. If set of counters is continuous then the mask can 441be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits 442must be left clear. 443 444 445Backwards compatibility 446----------------------- 447 448Runnability guarantee of CPU models (since 4.1) 449''''''''''''''''''''''''''''''''''''''''''''''' 450 451Previous versions of QEMU never changed existing CPU models in 452ways that introduced additional host software or hardware 453requirements to the VM. This allowed management software to 454safely change the machine type of an existing VM without 455introducing new requirements ("runnability guarantee"). This 456prevented CPU models from being updated to include CPU 457vulnerability mitigations, leaving guests vulnerable in the 458default configuration. 459 460The CPU model runnability guarantee won't apply anymore to 461existing CPU models. Management software that needs runnability 462guarantees must resolve the CPU model aliases using the 463``alias-of`` field returned by the ``query-cpu-definitions`` QMP 464command. 465 466While those guarantees are kept, the return value of 467``query-cpu-definitions`` will have existing CPU model aliases 468point to a version that doesn't break runnability guarantees 469(specifically, version 1 of those CPU models). In future QEMU 470versions, aliases will point to newer CPU model versions 471depending on the machine type, so management software must 472resolve CPU model aliases before starting a virtual machine. 473 474RISC-V "virt" board "riscv,delegate" DT property (since 9.1) 475'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 476 477The "riscv,delegate" DT property was added in QEMU 7.0 as part of 478the AIA APLIC support. The property changed name during the review 479process in Linux and the correct name ended up being 480"riscv,delegation". Changing the DT property name will break all 481available firmwares that are using the current (wrong) name. The 482property is kept as is in 9.1, together with "riscv,delegation", to 483give more time for firmware developers to change their code. 484 485Migration 486--------- 487 488``fd:`` URI when used for file migration (since 9.1) 489'''''''''''''''''''''''''''''''''''''''''''''''''''' 490 491The ``fd:`` URI can currently provide a file descriptor that 492references either a socket or a plain file. These are two different 493types of migration. In order to reduce ambiguity, the ``fd:`` URI 494usage of providing a file descriptor to a plain file has been 495deprecated in favor of explicitly using the ``file:`` URI with the 496file descriptor being passed as an ``fdset``. Refer to the ``add-fd`` 497command documentation for details on the ``fdset`` usage. 498