docs/about/deprecated.rst

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:
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
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
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 ------------------------
303 Versioned machine types (aarch64, arm, i386, m68k, ppc64, s390x, x86_64)
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
329 Linux dropped support for this virtual machine type in kernel v3.7, and
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``).
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
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
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
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)
598 process in Linux and the correct name ended up being
605 ---------
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