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
25 general feature deprecation policy.
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:
75 it is used when directly booting a guest kernel to pass it the
80 kernel since 2001. None of the board types QEMU supports need
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 ------------------------
306 In accordance with our versioned machine type deprecation policy, all machine
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.
321 Linux dropped support for this virtual machine type in kernel v3.7, and
323 in QEMU: Most former MIPS-related people are working on other architectures
330 RISC-V default machine option (since 10.0)
333 RISC-V defines ``spike`` as the default machine if no machine option is
335 RISC-V machine implemented in QEMU and setting it as default was
339 (the most used RISC-V machine type in 10.0) when in fact they're
345 command line (``-M spike``).
349 ------------------------
351 ``qemu-system-microblazeel`` (since 10.1)
354 The ``qemu-system-microblaze`` binary can emulate little-endian machines
355 now, too, so the separate binary ``qemu-system-microblazeel`` (with the
356 ``el`` suffix) for little-endian targets is not required anymore. The
357 ``petalogix-s3adsp1800`` machine can now be switched to little endian by
362 ---------------
364 Using non-persistent backing file with pmem=on (since 6.1)
367 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
368 device. However enabling ``memory-backend-file.pmem`` option, when backing file
374     - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
376     - move backing file to NVDIMM storage and keep ``pmem=on``
380 --------------
385 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
388 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
389 identifier that is not globally unique. If an EUI-64 identifier is required, the
390 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
392 ``-device nvme,use-intel-id=on|off`` (since 7.1)
397 has used a properly allocated identifier. Deprecate the ``use-intel-id``
400 ``-device cxl-type3,memdev=xxxx`` (since 8.0)
403 The ``cxl-type3`` device initially only used a single memory backend.  With
406 in favor of persistent-memdev.
409 RISC-V CPU properties which start with capital 'Z' (since 8.2)
412 All RISC-V CPU properties which start with capital 'Z' are being deprecated
414 in the past. CPU properties were later added with lower-case names, which
420 - "Zifencei" should be replaced with "zifencei"
421 - "Zicsr" should be replaced with "zicsr"
422 - "Zihintntl" should be replaced with "zihintntl"
423 - "Zihintpause" should be replaced with "zihintpause"
424 - "Zawrs" should be replaced with "zawrs"
425 - "Zfa" should be replaced with "zfa"
426 - "Zfh" should be replaced with "zfh"
427 - "Zfhmin" should be replaced with "zfhmin"
428 - "Zve32f" should be replaced with "zve32f"
429 - "Zve64f" should be replaced with "zve64f"
430 - "Zve64d" should be replaced with "zve64d"
432 ``-device sd-card,spec_version=1`` (since 9.1)
467 ``password`` option is insecure. The ``password-secret`` option should be
468 used instead, to refer to a ``--object secret...`` instance that provides
474 According to https://marc.info/?l=fedora-devel-list&m=171934833215726
492 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
502 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
507 ``-device vfio-calxeda-xgmac`` (since 10.0)
509 The vfio-calxeda-xgmac device allows to assign a host Calxeda Highbank
510 10Gb XGMAC Ethernet controller device ("calxeda,hb-xgmac" compatibility
514 ``-device vfio-amd-xgbe`` (since 10.0)
516 The vfio-amd-xgbe device allows to assign a host AMD 10GbE controller
517 to a guest ("amd,xgbe-seattle-v1a" compatibility string). AMD "Seattle"
520 ``-device vfio-platform`` (since 10.0)
522 The vfio-platform device allows to assign a host platform device
524 the vfio-platform infrastructure requires some adaptation at
525 both kernel and qemu level. No such attempt has been done for years
526 and the conclusion is that vfio-platform has not got any traction.
532 ``pmu-num=n`` on RISC-V CPUs (since 8.2)
536 by a ``pmu-mask`` property. If set of counters is continuous then the mask can
537 be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits
545 It was implemented as a no-op instruction in TCG up to QEMU 9.0, but
546 only with ``-cpu max`` (which does not guarantee migration compatibility
550 -----------------------
567 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
571 ``query-cpu-definitions`` will have existing CPU model aliases
578 RISC-V "virt" board "riscv,delegate" DT property (since 9.1)
590 ---------
600 file descriptor being passed as an ``fdset``. Refer to the ``add-fd``
603 ``zero-blocks`` capability (since 9.2)
606 The ``zero-blocks`` capability was part of the block migration which