docs/about/deprecated.rst

3 Deprecated features
9 release in which it was deprecated and one further release. After these two
10 releases, the feature is liable to be removed. Deprecated features may also
17 versioned machine types will be automatically marked deprecated after an
19 a further 3 year period has passed. It is recommended that a deprecated
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
28 deprecated.
31 --------------------------------------
33 Short-form boolean options (since 6.0)
37 in short form as ``share`` and ``noshare``.  This is now deprecated
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
68 marked deprecated since 9.0, users have to ensure that all the topology members
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:
79 like the ``akita`` or ``terrier``; it has been deprecated in the
81 ``param_struct`` support, so this option has been deprecated and will
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,
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
138 deprecated.  Use ``members`` instead.
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
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
242 32-bit host operating systems (since 10.0)
245 Keeping 32-bit host support alive is a substantial burden for the
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
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 --------------------
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
301 ------------------------
308 deprecated.
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
334 online to check that this board did not completely bitrot yet). It is
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``).
359 please write a mail to the qemu-devel mailing list). If you just want to
360 boot a Cortex-A15 or Cortex-A9 Linux, use the ``virt`` machine instead.
364 ------------------------
366 ``qemu-system-microblazeel`` (since 10.1)
369 The ``qemu-system-microblaze`` binary can emulate little-endian machines
370 now, too, so the separate binary ``qemu-system-microblazeel`` (with the
371 ``el`` suffix) for little-endian targets is not required anymore. The
372 ``petalogix-s3adsp1800`` machine can now be switched to little endian by
377 ---------------
379 Using non-persistent backing file with pmem=on (since 6.1)
382 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
383 device. However enabling ``memory-backend-file.pmem`` option, when backing file
389     - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
391     - move backing file to NVDIMM storage and keep ``pmem=on``
395 --------------
400 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
403 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
404 identifier that is not globally unique. If an EUI-64 identifier is required, the
405 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
407 ``-device nvme,use-intel-id=on|off`` (since 7.1)
412 has used a properly allocated identifier. Deprecate the ``use-intel-id``
415 ``-device cxl-type3,memdev=xxxx`` (since 8.0)
418 The ``cxl-type3`` device initially only used a single memory backend.  With
420 between persistent and volatile memory backends.  As such, memdev is deprecated
421 in favor of persistent-memdev.
424 RISC-V CPU properties which start with capital 'Z' (since 8.2)
427 All RISC-V CPU properties which start with capital 'Z' are being deprecated
429 in the past. CPU properties were later added with lower-case names, which
432 Users which try to use these deprecated properties will receive a warning
435 - "Zifencei" should be replaced with "zifencei"
436 - "Zicsr" should be replaced with "zicsr"
437 - "Zihintntl" should be replaced with "zihintntl"
438 - "Zihintpause" should be replaced with "zihintpause"
439 - "Zawrs" should be replaced with "zawrs"
440 - "Zfa" should be replaced with "zfa"
441 - "Zfh" should be replaced with "zfh"
442 - "Zfhmin" should be replaced with "zfhmin"
443 - "Zve32f" should be replaced with "zve32f"
444 - "Zve64f" should be replaced with "zve64f"
445 - "Zve64d" should be replaced with "zve64d"
447 ``-device sd-card,spec_version=1`` (since 9.1)
482 ``password`` option is insecure. The ``password-secret`` option should be
483 used instead, to refer to a ``--object secret...`` instance that provides
489 According to https://marc.info/?l=fedora-devel-list&m=171934833215726
501 ``memory`` is a deprecated synonym for ``ringbuf``.
507 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
517 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
522 ``-device vfio-calxeda-xgmac`` (since 10.0)
524 The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank
525 10Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility
529 ``-device vfio-amd-xgbe`` (since 10.0)
531 The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller
532 to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle"
535 ``-device vfio-platform`` (since 10.0)
537 The vfio-platform device allows to assign a host platform device
539 the vfio-platform infrastructure requires some adaptation at
541 and the conclusion is that vfio-platform has not got any traction.
547 ``pmu-num=n`` on RISC-V CPUs (since 8.2)
551 by a ``pmu-mask`` property. If set of counters is continuous then the mask can
552 be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits
560 It was implemented as a no-op instruction in TCG up to QEMU 9.0, but
561 only with ``-cpu max`` (which does not guarantee migration compatibility
565 -----------------------
582 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
586 ``query-cpu-definitions`` will have existing CPU model aliases
593 RISC-V "virt" board "riscv,delegate" DT property (since 9.1)
605 ---------
614 deprecated in favor of explicitly using the ``file:`` URI with the
615 file descriptor being passed as an ``fdset``. Refer to the ``add-fd``
618 ``zero-blocks`` capability (since 9.2)
621 The ``zero-blocks`` capability was part of the block migration which