docs/about/deprecated.rst

7 introduced into QEMU. In the event that a feature needs to be removed,
11 generate warnings on the console when QEMU starts up, or if activated via a
16 supported for a period of 6 years, equivalent to 18 QEMU releases. All
18 initial 3 years (9 QEMU releases) has passed, and will then be deleted after
21 for pre-existing VM deployments. They should be scheduled for updating to a
23 should exclusively use a non-deprecated machine type, with use of the most
24 recent version highly recommended. Non-versioned machine types follow the
31 --------------------------------------
33 Short-form boolean options (since 6.0)
43 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
50 command-line less readable, especially when the argument itself consist of a
51 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
52 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
53 as short-form boolean values, and passed to plugins as ``arg_name=on``.
54 However, short-form booleans are deprecated and full explicit ``arg_name=on``
57 ``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0)
67 configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is
69 described with -smp are supported by the target machine.
71 ``-old-param`` option for booting Arm kernels via param_struct (since 10.0)
74 The ``-old-param`` command line option is specific to Arm targets:
80 kernel since 2001. None of the board types QEMU supports need
82 be removed in a future QEMU version.
84 User-mode emulator command line arguments
85 -----------------------------------------
87 ``-p`` (since 9.0)
90 The ``-p`` option pretends to control the host page size.  However,
94 QEMU Machine Protocol (QMP) commands
95 ------------------------------------
97 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
107 ``blockdev-change-medium`` argument ``device`` (since 2.8)
117 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
122 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
125 Use arguments ``base-node`` and ``top-node`` instead.
127 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
130 Use the more generic commands ``block-export-add`` and ``block-export-del``
131 instead.  As part of this deprecation, where ``nbd-server-add`` used a
132 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
134 ``query-qmp-schema`` return value member ``values`` (since 6.2)
137 Member ``values`` in return value elements with meta-type ``enum`` is
140 ``drive-backup`` (since 6.2)
143 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
145 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
146 same arguments as ``drive-backup``, except the ``format`` and ``mode``
147 options are removed in favor of using explicit ``blockdev-create`` and
148 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
151 ``query-migrationthreads`` (since 9.2)
156 without reporting any destination threads, or non-multifd source threads).
157 For debugging purpose, please use ``-name $VM,debug-threads=on`` instead.
159 ``block-job-pause`` (since 10.1)
162 Use ``job-pause`` instead. The only difference is that ``job-pause``
163 always reports GenericError on failure when ``block-job-pause`` reports
164 DeviceNotActive when block-job is not found.
166 ``block-job-resume`` (since 10.1)
169 Use ``job-resume`` instead. The only difference is that ``job-resume``
170 always reports GenericError on failure when ``block-job-resume`` reports
171 DeviceNotActive when block-job is not found.
173 ``block-job-complete`` (since 10.1)
176 Use ``job-complete`` instead. The only difference is that ``job-complete``
177 always reports GenericError on failure when ``block-job-complete`` reports
178 DeviceNotActive when block-job is not found.
180 ``block-job-dismiss`` (since 10.1)
183 Use ``job-dismiss`` instead.
185 ``block-job-finalize`` (since 10.1)
188 Use ``job-finalize`` instead.
196 ------------------
198 Big endian MIPS since 7.2; 32-bit little endian MIPS since 9.2
203 cross-compilation CI tests of the architecture. As we no longer have
212 System emulation on 32-bit x86 hosts (since 8.0)
215 Support for 32-bit x86 host deployments is increasingly uncommon in mainstream
216 OS distributions given the widespread availability of 64-bit x86 hardware.
217 The QEMU project no longer considers 32-bit x86 support for system emulation to
219 it. Since all recent x86 hardware from the past >10 years is capable of the
220 64-bit x86 extensions, a corresponding 64-bit OS should be used instead.
222 TCG Plugin support not enabled by default on 32-bit hosts (since 9.2)
225 While it is still possible to enable TCG plugin support for 32-bit
227 64-bit guests. The plugin APIs typically pass most addresses as
229 for passing as user-data will lose data. As most software analysis
231 encourage users to use 64 bit builds of QEMU for analysis work
242 32-bit host operating systems (since 10.0)
245 Keeping 32-bit host support alive is a substantial burden for the
246 QEMU project.  Thus QEMU will in future drop the support for all
247 32-bit host systems.
249 linux-user mode CPUs
250 --------------------
256 ``pxa261``, ``pxa262``, ``pxa270-a0``, ``pxa270-a1``, ``pxa270``,
257 ``pxa270-b0``, ``pxa270-b1``, ``pxa270-c0``, ``pxa270-c5``) are no
259 used these CPUs were removed in the QEMU 9.2 release. These CPUs can
260 now only be used in linux-user mode, and to do that you would have to
261 explicitly select one of these CPUs with the ``-cpu`` command line
266 known-good implementation to test against. GCC is in the process of
268 therefore deprecated in QEMU, and will be removed in a future release.
271 --------------------
277 in the QEMU object model anymore. ``power5+``, ``power5+_v2.1``,
282 ``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1)
286 in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and
287 ``Sun-UltraSparc-IV+`` are currently still supported via a workaround,
289 Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead.
295 removed in QEMU 10.0. Since the IBM POWER [8-11] processors uses an
297 is theoretically possible to use QEMU to model them. Let's keep the
301 ------------------------
310 Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1)
313 The ``dtb-kaslr-seed`` property on the ``virt`` board has been
314 deprecated; use the new name ``dtb-randomness`` instead. The new name
316 the device tree blob, not just the ``kaslr-seed`` node.
318 Arm ``ast2700a0-evb`` machine (since 10.1)
321 The ``ast2700a0-evb`` machine represents the first revision of the AST2700
323 A newer revision, A1, is now supported, and the ``ast2700a1-evb`` should
331 in QEMU: Most former MIPS-related people are working on other architectures
338 RISC-V default machine option (since 10.0)
341 RISC-V defines ``spike`` as the default machine if no machine option is
343 RISC-V machine implemented in QEMU and setting it as default was
347 (the most used RISC-V machine type in 10.0) when in fact they're
353 command line (``-M spike``).
357 ------------------------
359 ``qemu-system-microblazeel`` (since 10.1)
362 The ``qemu-system-microblaze`` binary can emulate little-endian machines
363 now, too, so the separate binary ``qemu-system-microblazeel`` (with the
364 ``el`` suffix) for little-endian targets is not required anymore. The
365 ``petalogix-s3adsp1800`` machine can now be switched to little endian by
370 ---------------
372 Using non-persistent backing file with pmem=on (since 6.1)
375 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
376 device. However enabling ``memory-backend-file.pmem`` option, when backing file
382     - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
384     - move backing file to NVDIMM storage and keep ``pmem=on``
388 --------------
393 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
396 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
397 identifier that is not globally unique. If an EUI-64 identifier is required, the
398 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
400 ``-device nvme,use-intel-id=on|off`` (since 7.1)
405 has used a properly allocated identifier. Deprecate the ``use-intel-id``
408 ``-device cxl-type3,memdev=xxxx`` (since 8.0)
411 The ``cxl-type3`` device initially only used a single memory backend.  With
414 in favor of persistent-memdev.
417 RISC-V CPU properties which start with capital 'Z' (since 8.2)
420 All RISC-V CPU properties which start with capital 'Z' are being deprecated
422 in the past. CPU properties were later added with lower-case names, which
428 - "Zifencei" should be replaced with "zifencei"
429 - "Zicsr" should be replaced with "zicsr"
430 - "Zihintntl" should be replaced with "zihintntl"
431 - "Zihintpause" should be replaced with "zihintpause"
432 - "Zawrs" should be replaced with "zawrs"
433 - "Zfa" should be replaced with "zfa"
434 - "Zfh" should be replaced with "zfh"
435 - "Zfhmin" should be replaced with "zfhmin"
436 - "Zve32f" should be replaced with "zve32f"
437 - "Zve64f" should be replaced with "zve64f"
438 - "Zve64d" should be replaced with "zve64d"
440 ``-device sd-card,spec_version=1`` (since 9.1)
444 v2.00 is the default since QEMU 3.0.0.
452 In order to prevent QEMU from automatically opening an image's backing
475 ``password`` option is insecure. The ``password-secret`` option should be
476 used instead, to refer to a ``--object secret...`` instance that provides
482 According to https://marc.info/?l=fedora-devel-list&m=171934833215726
484 gains momentum again, the QEMU project will remove the gluster backend
500 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
510 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
515 ``-device vfio-calxeda-xgmac`` (since 10.0)
517 The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank
518 10Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility
522 ``-device vfio-amd-xgbe`` (since 10.0)
524 The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller
525 to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle"
528 ``-device vfio-platform`` (since 10.0)
530 The vfio-platform device allows to assign a host platform device
532 the vfio-platform infrastructure requires some adaptation at
533 both kernel and qemu level. No such attempt has been done for years
534 and the conclusion is that vfio-platform has not got any traction.
540 ``pmu-num=n`` on RISC-V CPUs (since 8.2)
544 by a ``pmu-mask`` property. If set of counters is continuous then the mask can
545 be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits
549 ``pcommit`` on x86 (since 9.1)
553 It was implemented as a no-op instruction in TCG up to QEMU 9.0, but
554 only with ``-cpu max`` (which does not guarantee migration compatibility
558 -----------------------
563 Previous versions of QEMU never changed existing CPU models in
575 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
579 ``query-cpu-definitions`` will have existing CPU model aliases
581 (specifically, version 1 of those CPU models).  In future QEMU
586 RISC-V "virt" board "riscv,delegate" DT property (since 9.1)
589 The "riscv,delegate" DT property was added in QEMU 7.0 as part of
598 ---------
608 file descriptor being passed as an ``fdset``. Refer to the ``add-fd``
611 ``zero-blocks`` capability (since 9.2)
614 The ``zero-blocks`` capability was part of the block migration which
615 doesn't exist anymore since it was removed in QEMU v9.1.