docs/about/deprecated.rst

8 it will be listed in this section. The feature will remain functional for the
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
36 System emulator command line arguments
37 --------------------------------------
39 Short-form boolean options (since 6.0)
49 The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on``
56 command-line less readable, especially when the argument itself consist of a
57 name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``.
58 Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated
59 as short-form boolean values, and passed to plugins as ``arg_name=on``.
60 However, short-form booleans are deprecated and full explicit ``arg_name=on``
63 ``-smp`` (Unsupported "parameter=1" SMP configurations) (since 9.0)
73 configurations (e.g. -smp drawers=1,books=1,clusters=1 for x86 PC machine) is
75 described with -smp are supported by the target machine.
77 ``-runas`` (since 9.1)
80 Use ``-run-with user=..`` instead.
83 User-mode emulator command line arguments
84 -----------------------------------------
86 ``-p`` (since 9.0)
89 The ``-p`` option pretends to control the host page size.  However,
94 ------------------------------------
96 ``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8)
106 ``blockdev-change-medium`` argument ``device`` (since 2.8)
116 ``blockdev-add`` empty string argument ``backing`` (since 2.10)
121 ``block-commit`` arguments ``base`` and ``top`` (since 3.1)
124 Use arguments ``base-node`` and ``top-node`` instead.
126 ``nbd-server-add`` and ``nbd-server-remove`` (since 5.2)
129 Use the more generic commands ``block-export-add`` and ``block-export-del``
130 instead.  As part of this deprecation, where ``nbd-server-add`` used a
131 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
133 ``query-qmp-schema`` return value member ``values`` (since 6.2)
136 Member ``values`` in return value elements with meta-type ``enum`` is
139 ``drive-backup`` (since 6.2)
142 Use ``blockdev-backup`` in combination with ``blockdev-add`` instead.
144 target with explicit, separate steps. ``blockdev-backup`` uses mostly the
145 same arguments as ``drive-backup``, except the ``format`` and ``mode``
146 options are removed in favor of using explicit ``blockdev-create`` and
147 ``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
150 ``query-migrationthreads`` (since 9.2)
155 without reporting any destination threads, or non-multifd source threads).
156 For debugging purpose, please use ``-name $VM,debug-threads=on`` instead.
173 ------------------
175 Big endian MIPS since 7.2; 32-bit little endian MIPS since 9.2
180 cross-compilation CI tests of the architecture. As we no longer have
189 System emulation on 32-bit x86 hosts (since 8.0)
192 Support for 32-bit x86 host deployments is increasingly uncommon in mainstream
193 OS distributions given the widespread availability of 64-bit x86 hardware.
194 The QEMU project no longer considers 32-bit x86 support for system emulation to
197 64-bit x86 extensions, a corresponding 64-bit OS should be used instead.
199 TCG Plugin support not enabled by default on 32-bit hosts (since 9.2)
202 While it is still possible to enable TCG plugin support for 32-bit
204 64-bit guests. The plugin APIs typically pass most addresses as
206 for passing as user-data will lose data. As most software analysis
219 System emulator CPUs
220 --------------------
231 ``Sun-UltraSparc-IIIi+`` and ``Sun-UltraSparc-IV+`` CPU names (since 9.1)
235 in the QEMU object model anymore. ``Sun-UltraSparc-IIIi+`` and
236 ``Sun-UltraSparc-IV+`` are currently still supported via a workaround,
238 Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead.
240 System emulator machines
241 ------------------------
243 Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1)
246 The ``dtb-kaslr-seed`` property on the ``virt`` board has been
247 deprecated; use the new name ``dtb-randomness`` instead. The new name
249 the device tree blob, not just the ``kaslr-seed`` node.
251 ``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1)
262 images are not available, OpenWRT dropped support in 2019, U-Boot in
266 Big-Endian variants of MicroBlaze ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` machines (since 9.2)
269 Both ``petalogix-ml605`` and ``xlnx-zynqmp-pmu`` were added for little endian
273 ---------------
275 Using non-persistent backing file with pmem=on (since 6.1)
278 This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM
279 device. However enabling ``memory-backend-file.pmem`` option, when backing file
285     - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM
287     - move backing file to NVDIMM storage and keep ``pmem=on``
291 --------------
296 ``-device nvme-ns,eui64-default=on|off`` (since 7.1)
299 In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64
300 identifier that is not globally unique. If an EUI-64 identifier is required, the
301 user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``.
303 ``-device nvme,use-intel-id=on|off`` (since 7.1)
308 has used a properly allocated identifier. Deprecate the ``use-intel-id``
311 ``-device cxl-type3,memdev=xxxx`` (since 8.0)
314 The ``cxl-type3`` device initially only used a single memory backend.  With
317 in favor of persistent-memdev.
320 RISC-V CPU properties which start with capital 'Z' (since 8.2)
323 All RISC-V CPU properties which start with capital 'Z' are being deprecated
325 in the past. CPU properties were later added with lower-case names, which
331 - "Zifencei" should be replaced with "zifencei"
332 - "Zicsr" should be replaced with "zicsr"
333 - "Zihintntl" should be replaced with "zihintntl"
334 - "Zihintpause" should be replaced with "zihintpause"
335 - "Zawrs" should be replaced with "zawrs"
336 - "Zfa" should be replaced with "zfa"
337 - "Zfh" should be replaced with "zfh"
338 - "Zfhmin" should be replaced with "zfhmin"
339 - "Zve32f" should be replaced with "zve32f"
340 - "Zve64f" should be replaced with "zve64f"
341 - "Zve64d" should be replaced with "zve64d"
343 ``-device sd-card,spec_version=1`` (since 9.1)
378 ``password`` option is insecure. The ``password-secret`` option should be
379 used instead, to refer to a ``--object secret...`` instance that provides
385 According to https://marc.info/?l=fedora-devel-list&m=171934833215726
403 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
413 which is not enough for all types of use cases, use ``reconnect-ms`` instead.
422 It was implemented as a no-op instruction in TCG up to QEMU 9.0, but
423 only with ``-cpu max`` (which does not guarantee migration compatibility
426 ``pmu-num=n`` on RISC-V CPUs (since 8.2)
430 by a ``pmu-mask`` property. If set of counters is continuous then the mask can
431 be calculated with ``((2 ^ n) - 1) << 3``. The least significant three bits
436 -----------------------
453 ``alias-of`` field returned by the ``query-cpu-definitions`` QMP
457 ``query-cpu-definitions`` will have existing CPU model aliases
464 RISC-V "virt" board "riscv,delegate" DT property (since 9.1)
476 ---------
486 file descriptor being passed as an ``fdset``. Refer to the ``add-fd``
489 ``zero-blocks`` capability (since 9.2)
492 The ``zero-blocks`` capability was part of the block migration which