diff options
Diffstat (limited to 'docs/about')
| -rw-r--r-- | docs/about/build-platforms.rst | 112 | ||||
| -rw-r--r-- | docs/about/deprecated.rst | 399 | ||||
| -rw-r--r-- | docs/about/index.rst | 28 | ||||
| -rw-r--r-- | docs/about/license.rst | 11 | ||||
| -rw-r--r-- | docs/about/removed-features.rst | 823 |
5 files changed, 1373 insertions, 0 deletions
diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst new file mode 100644 index 00000000..1c1e7b9e --- /dev/null +++ b/docs/about/build-platforms.rst @@ -0,0 +1,112 @@ +.. _Supported-build-platforms: + +Supported build platforms +========================= + +QEMU aims to support building and executing on multiple host OS +platforms. This appendix outlines which platforms are the major build +targets. These platforms are used as the basis for deciding upon the +minimum required versions of 3rd party software QEMU depends on. The +supported platforms are the targets for automated testing performed by +the project when patches are submitted for review, and tested before and +after merge. + +If a platform is not listed here, it does not imply that QEMU won't +work. If an unlisted platform has comparable software versions to a +listed platform, there is every expectation that it will work. Bug +reports are welcome for problems encountered on unlisted platforms +unless they are clearly older vintage than what is described here. + +Note that when considering software versions shipped in distros as +support targets, QEMU considers only the version number, and assumes the +features in that distro match the upstream release with the same +version. In other words, if a distro backports extra features to the +software in their distro, QEMU upstream code will not add explicit +support for those backports, unless the feature is auto-detectable in a +manner that works for the upstream releases too. + +The `Repology`_ site is a useful resource to identify +currently shipped versions of software in various operating systems, +though it does not cover all distros listed below. + +Supported host architectures +---------------------------- + +Those hosts are officially supported, with various accelerators: + + .. list-table:: + :header-rows: 1 + + * - CPU Architecture + - Accelerators + * - Arm + - kvm (64 bit only), tcg, xen + * - MIPS (little endian only) + - kvm, tcg + * - PPC + - kvm, tcg + * - RISC-V + - kvm, tcg + * - s390x + - kvm, tcg + * - SPARC + - tcg + * - x86 + - hax, hvf (64 bit only), kvm, nvmm, tcg, whpx (64 bit only), xen + +Other host architectures are not supported. It is possible to build QEMU system +emulation on an unsupported host architecture using the configure +``--enable-tcg-interpreter`` option to enable the TCI support, but note that +this is very slow and is not recommended for normal use. QEMU user emulation +requires host-specific support for signal handling, therefore TCI won't help +on unsupported host architectures. + +Non-supported architectures may be removed in the future following the +:ref:`deprecation process<Deprecated features>`. + +Linux OS, macOS, FreeBSD, NetBSD, OpenBSD +----------------------------------------- + +The project aims to support the most recent major version at all times. Support +for the previous major version will be dropped 2 years after the new major +version is released or when the vendor itself drops support, whichever comes +first. In this context, third-party efforts to extend the lifetime of a distro +are not considered, even when they are endorsed by the vendor (eg. Debian LTS); +the same is true of repositories that contain packages backported from later +releases (e.g. Debian backports). Within each major release, only the most +recent minor release is considered. + +For the purposes of identifying supported software versions available on Linux, +the project will look at CentOS, Debian, Fedora, openSUSE, RHEL, SLES and +Ubuntu LTS. Other distros will be assumed to ship similar software versions. + +For FreeBSD and OpenBSD, decisions will be made based on the contents of the +respective ports repository, while NetBSD will use the pkgsrc repository. + +For macOS, `Homebrew`_ will be used, although `MacPorts`_ is expected to carry +similar versions. + +Windows +------- + +The project aims to support the two most recent versions of Windows that are +still supported by the vendor. The minimum Windows API that is currently +targeted is "Windows 8", so theoretically the QEMU binaries can still be run +on older versions of Windows, too. However, such old versions of Windows are +not tested anymore, so it is recommended to use one of the latest versions of +Windows instead. + +The project supports building QEMU with current versions of the MinGW +toolchain, either hosted on Linux (Debian/Fedora) or via `MSYS2`_ on Windows. +A more recent Windows version is always preferred as it is less likely to have +problems with building via MSYS2. The building process of QEMU involves some +Python scripts that call os.symlink() which needs special attention for the +build process to successfully complete. On newer versions of Windows 10, +unprivileged accounts can create symlinks if Developer Mode is enabled. +When Developer Mode is not available/enabled, the SeCreateSymbolicLinkPrivilege +privilege is required, or the process must be run as an administrator. + +.. _Homebrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/ +.. _MSYS2: https://www.msys2.org/ +.. _Repology: https://repology.org/ diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst new file mode 100644 index 00000000..93affe36 --- /dev/null +++ b/docs/about/deprecated.rst @@ -0,0 +1,399 @@ +.. _Deprecated features: + +Deprecated features +=================== + +In general features are intended to be supported indefinitely once +introduced into QEMU. In the event that a feature needs to be removed, +it will be listed in this section. The feature will remain functional for the +release in which it was deprecated and one further release. After these two +releases, the feature is liable to be removed. Deprecated features may also +generate warnings on the console when QEMU starts up, or if activated via a +monitor command, however, this is not a mandatory requirement. + +Prior to the 2.10.0 release there was no official policy on how +long features would be deprecated prior to their removal, nor +any documented list of which features were deprecated. Thus +any features deprecated prior to 2.10.0 will be treated as if +they were first deprecated in the 2.10.0 release. + +What follows is a list of all features currently marked as +deprecated. + +System emulator command line arguments +-------------------------------------- + +``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``-audiodev`` argument is now the preferred way to specify audio +backend settings instead of environment variables. To ease migration to +the new format, the ``-audiodev-help`` option can be used to convert +the current values of the environment variables to ``-audiodev`` options. + +Creating sound card devices and vnc without ``audiodev=`` property (since 4.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +When not using the deprecated legacy audio config, each sound card +should specify an ``audiodev=`` property. Additionally, when using +vnc, you should specify an ``audiodev=`` property if you plan to +transmit audio through the VNC protocol. + +``-chardev`` backend aliases ``tty`` and ``parport`` (since 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +``tty`` and ``parport`` are aliases that will be removed. Instead, the +actual backend names ``serial`` and ``parallel`` should be used. + +Short-form boolean options (since 6.0) +'''''''''''''''''''''''''''''''''''''' + +Boolean options such as ``share=on``/``share=off`` could be written +in short form as ``share`` and ``noshare``. This is now deprecated +and will cause a warning. + +``delay`` option for socket character devices (since 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The replacement for the ``nodelay`` short-form boolean option is ``nodelay=on`` +rather than ``delay=off``. + +Userspace local APIC with KVM (x86, since 6.0) +'''''''''''''''''''''''''''''''''''''''''''''' + +Using ``-M kernel-irqchip=off`` with x86 machine types that include a local +APIC is deprecated. The ``split`` setting is supported, as is using +``-M kernel-irqchip=off`` with the ISA PC machine type. + +hexadecimal sizes with scaling multipliers (since 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Input parameters that take a size value should only use a size suffix +(such as 'k' or 'M') when the base is written in decimal, and not when +the value is hexadecimal. That is, '0x20M' is deprecated, and should +be written either as '32M' or as '0x2000000'. + +``-spice password=string`` (since 6.0) +'''''''''''''''''''''''''''''''''''''' + +This option is insecure because the SPICE password remains visible in +the process listing. This is replaced by the new ``password-secret`` +option which lets the password be securely provided on the command +line using a ``secret`` object instance. + +``-smp`` ("parameter=0" SMP configurations) (since 6.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Specified CPU topology parameters must be greater than zero. + +In the SMP configuration, users should either provide a CPU topology +parameter with a reasonable value (greater than zero) or just omit it +and QEMU will compute the missing value. + +However, historically it was implicitly allowed for users to provide +a parameter with zero value, which is meaningless and could also possibly +cause unexpected results in the -smp parsing. So support for this kind of +configurations (e.g. -smp 8,sockets=0) is deprecated since 6.2 and will +be removed in the near future, users have to ensure that all the topology +members described with -smp are greater than zero. + +Plugin argument passing through ``arg=<string>`` (since 6.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Passing TCG plugins arguments through ``arg=`` is redundant is makes the +command-line less readable, especially when the argument itself consist of a +name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. +Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated +as short-form boolean values, and passed to plugins as ``arg_name=on``. +However, short-form booleans are deprecated and full explicit ``arg_name=on`` +form is preferred. + +``-drive if=none`` for the sifive_u OTP device (since 6.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Using ``-drive if=none`` to configure the OTP device of the sifive_u +RISC-V machine is deprecated. Use ``-drive if=pflash`` instead. + + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``eject`` argument ``device`` (since 2.8) +''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``blockdev-change-medium`` argument ``device`` (since 2.8) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``block_set_io_throttle`` argument ``device`` (since 2.8) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``blockdev-add`` empty string argument ``backing`` (since 2.10) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument value ``null`` instead. + +``block-commit`` arguments ``base`` and ``top`` (since 3.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use arguments ``base-node`` and ``top-node`` instead. + +``nbd-server-add`` and ``nbd-server-remove`` (since 5.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use the more generic commands ``block-export-add`` and ``block-export-del`` +instead. As part of this deprecation, where ``nbd-server-add`` used a +single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``. + +``query-qmp-schema`` return value member ``values`` (since 6.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Member ``values`` in return value elements with meta-type ``enum`` is +deprecated. Use ``members`` instead. + +``drive-backup`` (since 6.2) +'''''''''''''''''''''''''''' + +Use ``blockdev-backup`` in combination with ``blockdev-add`` instead. +This change primarily separates the creation/opening process of the backup +target with explicit, separate steps. ``blockdev-backup`` uses mostly the +same arguments as ``drive-backup``, except the ``format`` and ``mode`` +options are removed in favor of using explicit ``blockdev-create`` and +``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for +details. + +Incorrectly typed ``device_add`` arguments (since 6.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Due to shortcomings in the internal implementation of ``device_add``, QEMU +incorrectly accepts certain invalid arguments: Any object or list arguments are +silently ignored. Other argument types are not checked, but an implicit +conversion happens, so that e.g. string values can be assigned to integer +device properties or vice versa. + +This is a bug in QEMU that will be fixed in the future so that previously +accepted incorrect commands will return an error. Users should make sure that +all arguments passed to ``device_add`` are consistent with the documented +property types. + +``query-sgx`` return value member ``section-size`` (since 7.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Member ``section-size`` in return value elements with meta-type ``uint64`` is +deprecated. Use ``sections`` instead. + + +``query-sgx-capabilities`` return value member ``section-size`` (since 7.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Member ``section-size`` in return value elements with meta-type ``uint64`` is +deprecated. Use ``sections`` instead. + +System accelerators +------------------- + +MIPS ``Trap-and-Emul`` KVM support (since 6.0) +'''''''''''''''''''''''''''''''''''''''''''''' + +The MIPS ``Trap-and-Emul`` KVM host and guest support has been removed +from Linux upstream kernel, declare it deprecated. + +Host Architectures +------------------ + +BE MIPS (since 7.2) +''''''''''''''''''' + +As Debian 10 ("Buster") moved into LTS the big endian 32 bit version of +MIPS moved out of support making it hard to maintain our +cross-compilation CI tests of the architecture. As we no longer have +CI coverage support may bitrot away before the deprecation process +completes. The little endian variants of MIPS (both 32 and 64 bit) are +still a supported host architecture. + +QEMU API (QAPI) events +---------------------- + +``MEM_UNPLUG_ERROR`` (since 6.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use the more generic event ``DEVICE_UNPLUG_GUEST_ERROR`` instead. + + +System emulator machines +------------------------ + +Arm ``virt`` machine ``dtb-kaslr-seed`` property +'''''''''''''''''''''''''''''''''''''''''''''''' + +The ``dtb-kaslr-seed`` property on the ``virt`` board has been +deprecated; use the new name ``dtb-randomness`` instead. The new name +better reflects the way this property affects all random data within +the device tree blob, not just the ``kaslr-seed`` node. + +``pc-i440fx-1.4`` up to ``pc-i440fx-1.7`` (since 7.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +These old machine types are quite neglected nowadays and thus might have +various pitfalls with regards to live migration. Use a newer machine type +instead. + + +Backend options +--------------- + +Using non-persistent backing file with pmem=on (since 6.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +This option is used when ``memory-backend-file`` is consumed by emulated NVDIMM +device. However enabling ``memory-backend-file.pmem`` option, when backing file +is (a) not DAX capable or (b) not on a filesystem that support direct mapping +of persistent memory, is not safe and may lead to data loss or corruption in case +of host crash. +Options are: + + - modify VM configuration to set ``pmem=off`` to continue using fake NVDIMM + (without persistence guaranties) with backing file on non DAX storage + - move backing file to NVDIMM storage and keep ``pmem=on`` + (to have NVDIMM with persistence guaranties). + +Device options +-------------- + +Emulated device options +''''''''''''''''''''''' + +``-device virtio-blk,scsi=on|off`` (since 5.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0 +and later do not support it because the virtio-scsi device was introduced for +full SCSI support. Use virtio-scsi instead when SCSI passthrough is required. + +Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an +alias. + +``-device sga`` (since 6.2) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``sga`` device loads an option ROM for x86 targets which enables +SeaBIOS to send messages to the serial console. SeaBIOS 1.11.0 onwards +contains native support for this feature and thus use of the option +ROM approach is obsolete. The native SeaBIOS support can be activated +by using ``-machine graphics=off``. + +``-device nvme-ns,eui64-default=on|off`` (since 7.1) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In QEMU versions 6.1, 6.2 and 7.0, the ``nvme-ns`` generates an EUI-64 +identifier that is not globally unique. If an EUI-64 identifier is required, the +user must set it explicitly using the ``nvme-ns`` device parameter ``eui64``. + +``-device nvme,use-intel-id=on|off`` (since 7.1) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``nvme`` device originally used a PCI Vendor/Device Identifier combination +from Intel that was not properly allocated. Since version 5.2, the controller +has used a properly allocated identifier. Deprecate the ``use-intel-id`` +machine compatibility parameter. + + +Block device options +'''''''''''''''''''' + +``"backing": ""`` (since 2.12) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to prevent QEMU from automatically opening an image's backing +chain, use ``"backing": null`` instead. + +``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Options for ``rbd`` should be specified according to its runtime options, +like other block drivers. Legacy parsing of keyvalue pair encoded +filenames is useful to open images with the old format for backing files; +These image files should be updated to use the current format. + +Example of legacy encoding:: + + json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"} + +The above, converted to the current supported format:: + + json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"} + +Backwards compatibility +----------------------- + +Runnability guarantee of CPU models (since 4.1) +''''''''''''''''''''''''''''''''''''''''''''''' + +Previous versions of QEMU never changed existing CPU models in +ways that introduced additional host software or hardware +requirements to the VM. This allowed management software to +safely change the machine type of an existing VM without +introducing new requirements ("runnability guarantee"). This +prevented CPU models from being updated to include CPU +vulnerability mitigations, leaving guests vulnerable in the +default configuration. + +The CPU model runnability guarantee won't apply anymore to +existing CPU models. Management software that needs runnability +guarantees must resolve the CPU model aliases using the +``alias-of`` field returned by the ``query-cpu-definitions`` QMP +command. + +While those guarantees are kept, the return value of +``query-cpu-definitions`` will have existing CPU model aliases +point to a version that doesn't break runnability guarantees +(specifically, version 1 of those CPU models). In future QEMU +versions, aliases will point to newer CPU model versions +depending on the machine type, so management software must +resolve CPU model aliases before starting a virtual machine. + +Tools +----- + +virtiofsd +''''''''' + +There is a new Rust implementation of ``virtiofsd`` at +``https://gitlab.com/virtio-fs/virtiofsd``; +since this is now marked stable, new development should be done on that +rather than the existing C version in the QEMU tree. +The C version will still accept fixes and patches that +are already in development for the moment, but will eventually +be deleted from this tree. +New deployments should use the Rust version, and existing systems +should consider moving to it. The command line and feature set +is very close and moving should be simple. + + +QEMU guest agent +---------------- + +``--blacklist`` command line option (since 7.2) +''''''''''''''''''''''''''''''''''''''''''''''' + +``--blacklist`` has been replaced by ``--block-rpcs`` (which is a better +wording for what this option does). The short form ``-b`` still stays +the same and thus is the preferred way for scripts that should run with +both, older and future versions of QEMU. + +``blacklist`` config file option (since 7.2) +'''''''''''''''''''''''''''''''''''''''''''' + +The ``blacklist`` config file option has been renamed to ``block-rpcs`` +(to be in sync with the renaming of the corresponding command line +option). diff --git a/docs/about/index.rst b/docs/about/index.rst new file mode 100644 index 00000000..5bea653c --- /dev/null +++ b/docs/about/index.rst @@ -0,0 +1,28 @@ +---------- +About QEMU +---------- + +QEMU is a generic and open source machine emulator and virtualizer. + +QEMU can be used in several different ways. The most common is for +"system emulation", where it provides a virtual model of an +entire machine (CPU, memory and emulated devices) to run a guest OS. +In this mode the CPU may be fully emulated, or it may work with +a hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to +allow the guest to run directly on the host CPU. + +The second supported way to use QEMU is "user mode emulation", +where QEMU can launch processes compiled for one CPU on another CPU. +In this mode the CPU is always emulated. + +QEMU also provides a number of standalone commandline utilities, +such as the ``qemu-img`` disk image utility that allows you to create, +convert and modify disk images. + +.. toctree:: + :maxdepth: 2 + + build-platforms + deprecated + removed-features + license diff --git a/docs/about/license.rst b/docs/about/license.rst new file mode 100644 index 00000000..cde3d2d2 --- /dev/null +++ b/docs/about/license.rst @@ -0,0 +1,11 @@ +.. _License: + +License +======= + +QEMU is a trademark of Fabrice Bellard. + +QEMU is released under the `GNU General Public +License <https://www.gnu.org/licenses/gpl-2.0.txt>`__, version 2. Parts +of QEMU have specific licenses, see file +`LICENSE <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE>`__. diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst new file mode 100644 index 00000000..63df9848 --- /dev/null +++ b/docs/about/removed-features.rst @@ -0,0 +1,823 @@ + +Removed features +================ + +What follows is a record of recently removed, formerly deprecated +features that serves as a record for users who have encountered +trouble after a recent upgrade. + +System emulator command line arguments +-------------------------------------- + +``-hdachs`` (removed in 2.12) +''''''''''''''''''''''''''''' + +The geometry defined by ``-hdachs c,h,s,t`` should now be specified via +``-device ide-hd,drive=dr,cyls=c,heads=h,secs=s,bios-chs-trans=t`` +(together with ``-drive if=none,id=dr,...``). + +``-net channel`` (removed in 2.12) +'''''''''''''''''''''''''''''''''' + +This option has been replaced by ``-net user,guestfwd=...``. + +``-net dump`` (removed in 2.12) +''''''''''''''''''''''''''''''' + +``-net dump[,vlan=n][,file=filename][,len=maxlen]`` has been replaced by +``-object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=maxlen]``. +Note that the new syntax works with netdev IDs instead of the old "vlan" hubs. + +``-no-kvm-pit`` (removed in 2.12) +''''''''''''''''''''''''''''''''' + +This was just a dummy option that has been ignored, since the in-kernel PIT +cannot be disabled separately from the irqchip anymore. A similar effect +(which also disables the KVM IOAPIC) can be obtained with +``-M kernel_irqchip=split``. + +``-tdf`` (removed in 2.12) +'''''''''''''''''''''''''' + +There is no replacement, the ``-tdf`` option has just been ignored since the +behaviour that could be changed by this option in qemu-kvm is now the default +when using the KVM PIT. It still can be requested explicitly using +``-global kvm-pit.lost_tick_policy=delay``. + +``-drive secs=s``, ``-drive heads=h`` & ``-drive cyls=c`` (removed in 3.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The drive geometry should now be specified via +``-device ...,drive=dr,cyls=c,heads=h,secs=s`` (together with +``-drive if=none,id=dr,...``). + +``-drive serial=``, ``-drive trans=`` & ``-drive addr=`` (removed in 3.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-device ...,drive=dr,serial=r,bios-chs-trans=t,addr=a`` instead +(together with ``-drive if=none,id=dr,...``). + +``-net ...,vlan=x`` (removed in 3.0) +'''''''''''''''''''''''''''''''''''' + +The term "vlan" was very confusing for most users in this context (it's about +specifying a hub ID, not about IEEE 802.1Q or something similar), so this +has been removed. To connect one NIC frontend with a network backend, either +use ``-nic ...`` (e.g. for on-board NICs) or use ``-netdev ...,id=n`` together +with ``-device ...,netdev=n`` (for full control over pluggable NICs). To +connect multiple NICs or network backends via a hub device (which is what +vlan did), use ``-nic hubport,hubid=x,...`` or +``-netdev hubport,id=n,hubid=x,...`` (with ``-device ...,netdev=n``) instead. + +``-no-kvm-irqchip`` (removed in 3.0) +'''''''''''''''''''''''''''''''''''' + +Use ``-machine kernel_irqchip=off`` instead. + +``-no-kvm-pit-reinjection`` (removed in 3.0) +'''''''''''''''''''''''''''''''''''''''''''' + +Use ``-global kvm-pit.lost_tick_policy=discard`` instead. + +``-balloon`` (removed in 3.1) +''''''''''''''''''''''''''''' + +The ``-balloon virtio`` option has been replaced by ``-device virtio-balloon``. +The ``-balloon none`` option was a no-op and has no replacement. + +``-bootp`` (removed in 3.1) +''''''''''''''''''''''''''' + +The ``-bootp /some/file`` argument is replaced by either +``-netdev user,id=x,bootp=/some/file`` (for pluggable NICs, accompanied with +``-device ...,netdev=x``), or ``-nic user,bootp=/some/file`` (for on-board NICs). +The new syntax allows different settings to be provided per NIC. + +``-redir`` (removed in 3.1) +''''''''''''''''''''''''''' + +The ``-redir [tcp|udp]:hostport:[guestaddr]:guestport`` option is replaced +by either ``-netdev +user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport`` +(for pluggable NICs, accompanied with ``-device ...,netdev=x``) or by the option +``-nic user,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport`` +(for on-board NICs). The new syntax allows different settings to be provided +per NIC. + +``-smb`` (removed in 3.1) +''''''''''''''''''''''''' + +The ``-smb /some/dir`` argument is replaced by either +``-netdev user,id=x,smb=/some/dir`` (for pluggable NICs, accompanied with +``-device ...,netdev=x``), or ``-nic user,smb=/some/dir`` (for on-board NICs). +The new syntax allows different settings to be provided per NIC. + +``-tftp`` (removed in 3.1) +'''''''''''''''''''''''''' + +The ``-tftp /some/dir`` argument is replaced by either +``-netdev user,id=x,tftp=/some/dir`` (for pluggable NICs, accompanied with +``-device ...,netdev=x``), or ``-nic user,tftp=/some/dir`` (for embedded NICs). +The new syntax allows different settings to be provided per NIC. + +``-localtime`` (removed in 3.1) +''''''''''''''''''''''''''''''' + +Replaced by ``-rtc base=localtime``. + +``-nodefconfig`` (removed in 3.1) +''''''''''''''''''''''''''''''''' + +Use ``-no-user-config`` instead. + +``-rtc-td-hack`` (removed in 3.1) +''''''''''''''''''''''''''''''''' + +Use ``-rtc driftfix=slew`` instead. + +``-startdate`` (removed in 3.1) +''''''''''''''''''''''''''''''' + +Replaced by ``-rtc base=date``. + +``-vnc ...,tls=...``, ``-vnc ...,x509=...`` & ``-vnc ...,x509verify=...`` (removed in 3.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The "tls-creds" option should be used instead to point to a "tls-creds-x509" +object created using "-object". + +``-mem-path`` fallback to RAM (removed in 5.0) +'''''''''''''''''''''''''''''''''''''''''''''' + +If guest RAM allocation from file pointed by ``mem-path`` failed, +QEMU was falling back to allocating from RAM, which might have resulted +in unpredictable behavior since the backing file specified by the user +as ignored. Currently, users are responsible for making sure the backing storage +specified with ``-mem-path`` can actually provide the guest RAM configured with +``-m`` and QEMU fails to start up if RAM allocation is unsuccessful. + +``-net ...,name=...`` (removed in 5.1) +'''''''''''''''''''''''''''''''''''''' + +The ``name`` parameter of the ``-net`` option was a synonym +for the ``id`` parameter, which should now be used instead. + +``-numa node,mem=...`` (removed in 5.1) +''''''''''''''''''''''''''''''''''''''' + +The parameter ``mem`` of ``-numa node`` was used to assign a part of guest RAM +to a NUMA node. But when using it, it's impossible to manage a specified RAM +chunk on the host side (like bind it to a host node, setting bind policy, ...), +so the guest ends up with the fake NUMA configuration with suboptiomal +performance. +However since 2014 there is an alternative way to assign RAM to a NUMA node +using parameter ``memdev``, which does the same as ``mem`` and adds +means to actually manage node RAM on the host side. Use parameter ``memdev`` +with *memory-backend-ram* backend as replacement for parameter ``mem`` +to achieve the same fake NUMA effect or a properly configured +*memory-backend-file* backend to actually benefit from NUMA configuration. +New machine versions (since 5.1) will not accept the option but it will still +work with old machine types. User can check the QAPI schema to see if the legacy +option is supported by looking at MachineInfo::numa-mem-supported property. + +``-numa`` node (without memory specified) (removed in 5.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Splitting RAM by default between NUMA nodes had the same issues as ``mem`` +parameter with the difference that the role of the user plays QEMU using +implicit generic or board specific splitting rule. +Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if +it's supported by used machine type) to define mapping explicitly instead. +Users of existing VMs, wishing to preserve the same RAM distribution, should +configure it explicitly using ``-numa node,memdev`` options. Current RAM +distribution can be retrieved using HMP command ``info numa`` and if separate +memory devices (pc|nv-dimm) are present use ``info memory-device`` and subtract +device memory from output of ``info numa``. + +``-smp`` (invalid topologies) (removed in 5.2) +'''''''''''''''''''''''''''''''''''''''''''''' + +CPU topology properties should describe whole machine topology including +possible CPUs. + +However, historically it was possible to start QEMU with an incorrect topology +where *n* <= *sockets* * *cores* * *threads* < *maxcpus*, +which could lead to an incorrect topology enumeration by the guest. +Support for invalid topologies is removed, the user must ensure +topologies described with -smp include all possible cpus, i.e. +*sockets* * *cores* * *threads* = *maxcpus*. + +``-machine enforce-config-section=on|off`` (removed in 5.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``enforce-config-section`` property was replaced by the +``-global migration.send-configuration={on|off}`` option. + +``-no-kvm`` (removed in 5.2) +'''''''''''''''''''''''''''' + +The ``-no-kvm`` argument was a synonym for setting ``-machine accel=tcg``. + +``-realtime`` (removed in 6.0) +'''''''''''''''''''''''''''''' + +The ``-realtime mlock=on|off`` argument has been replaced by the +``-overcommit mem-lock=on|off`` argument. + +``-show-cursor`` option (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,show-cursor=on``, ``-display gtk,show-cursor=on`` +or ``-display default,show-cursor=on`` instead. + +``-tb-size`` option (removed in 6.0) +'''''''''''''''''''''''''''''''''''' + +QEMU 5.0 introduced an alternative syntax to specify the size of the translation +block cache, ``-accel tcg,tb-size=``. + +``-usbdevice audio`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''' + +This option lacked the possibility to specify an audio backend device. +Use ``-device usb-audio`` now instead (and specify a corresponding USB +host controller or ``-usb`` if necessary). + +``-vnc acl`` (removed in 6.0) +''''''''''''''''''''''''''''' + +The ``acl`` option to the ``-vnc`` argument has been replaced +by the ``tls-authz`` and ``sasl-authz`` options. + +``-mon ...,control=readline,pretty=on|off`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``pretty=on|off`` switch has no effect for HMP monitors and +its use is rejected. + +``-drive file=json:{...{'driver':'file'}}`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The 'file' driver for drives is no longer appropriate for character or host +devices and will only accept regular files (S_IFREG). The correct driver +for these file types is 'host_cdrom' or 'host_device' as appropriate. + +Floppy controllers' drive properties (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-device floppy,...`` instead. When configuring onboard floppy +controllers +:: + + -global isa-fdc.driveA=... + -global sysbus-fdc.driveA=... + -global SUNW,fdtwo.drive=... + +become +:: + + -device floppy,unit=0,drive=... + +and +:: + + -global isa-fdc.driveB=... + -global sysbus-fdc.driveB=... + +become +:: + + -device floppy,unit=1,drive=... + +When plugging in a floppy controller +:: + + -device isa-fdc,...,driveA=... + +becomes +:: + + -device isa-fdc,... + -device floppy,unit=0,drive=... + +and +:: + + -device isa-fdc,...,driveB=... + +becomes +:: + + -device isa-fdc,... + -device floppy,unit=1,drive=... + +``-drive`` with bogus interface type (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Drives with interface types other than ``if=none`` are for onboard +devices. Drives the board doesn't pick up can no longer be used with +-device. Use ``if=none`` instead. + +``-usbdevice ccid`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''' + +This option was undocumented and not used in the field. +Use ``-device usb-ccid`` instead. + +RISC-V firmware not booted by default (removed in 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +QEMU 5.1 changes the default behaviour from ``-bios none`` to ``-bios default`` +for the RISC-V ``virt`` machine and ``sifive_u`` machine. + +``-no-quit`` (removed in 7.0) +''''''''''''''''''''''''''''' + +The ``-no-quit`` was a synonym for ``-display ...,window-close=off`` which +should be used instead. + +``--enable-fips`` (removed in 7.1) +'''''''''''''''''''''''''''''''''' + +This option restricted usage of certain cryptographic algorithms when +the host is operating in FIPS mode. + +If FIPS compliance is required, QEMU should be built with the ``libgcrypt`` +or ``gnutls`` library enabled as a cryptography provider. + +Neither the ``nettle`` library, or the built-in cryptography provider are +supported on FIPS enabled hosts. + +``-writeconfig`` (removed in 7.1) +''''''''''''''''''''''''''''''''' + +The ``-writeconfig`` option was not able to serialize the entire contents +of the QEMU command line. It is thus considered a failed experiment +and removed without a replacement. + +``loaded`` property of ``secret`` and ``secret_keyring`` objects (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``loaded=on`` option in the command line or QMP ``object-add`` either had +no effect (if ``loaded`` was the last option) or caused options to be +effectively ignored as if they were not given. The property is therefore +useless and should simply be removed. + +``opened`` property of ``rng-*`` objects (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``opened=on`` option in the command line or QMP ``object-add`` either had +no effect (if ``opened`` was the last option) or caused errors. The property +is therefore useless and should simply be removed. + +``-display sdl,window_close=...`` (removed in 7.1) +'''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of +an underscore between "window" and "close"). + +``-alt-grab`` and ``-display sdl,alt_grab=on`` (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead. + +``-ctrl-grab`` and ``-display sdl,ctrl_grab=on`` (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,grab-mod=rctrl`` instead. + +``-sdl`` (removed in 7.1) +''''''''''''''''''''''''' + +Use ``-display sdl`` instead. + +``-curses`` (removed in 7.1) +'''''''''''''''''''''''''''' + +Use ``-display curses`` instead. + +Creating sound card devices using ``-soundhw`` (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Sound card devices should be created using ``-device`` or ``-audio``. +The exception is ``pcspk`` which can be activated using ``-machine +pcspk-audiodev=<name>``. + +``-watchdog`` (since 7.2) +''''''''''''''''''''''''' + +Use ``-device`` instead. + + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The "autoload" parameter has been ignored since 2.12.0. All bitmaps +are automatically loaded from qcow2 images. + +``cpu-add`` (removed in 5.2) +'''''''''''''''''''''''''''' + +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See +documentation of ``query-hotpluggable-cpus`` for additional details. + +``change`` (removed in 6.0) +''''''''''''''''''''''''''' + +Use ``blockdev-change-medium`` or ``change-vnc-password`` or +``display-update`` instead. + +``query-events`` (removed in 6.0) +''''''''''''''''''''''''''''''''' + +The ``query-events`` command has been superseded by the more powerful +and accurate ``query-qmp-schema`` command. + +``migrate_set_cache_size`` and ``query-migrate-cache-size`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate_set_parameter`` and ``info migrate_parameters`` instead. + +``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate_set_parameter`` instead. + +``query-cpus`` (removed in 6.0) +''''''''''''''''''''''''''''''' + +The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command. + +``query-cpus-fast`` ``arch`` output member (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``arch`` output member of the ``query-cpus-fast`` command is +replaced by the ``target`` output member. + +chardev client socket with ``wait`` option (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Character devices creating sockets in client mode should not specify +the 'wait' field, which is only applicable to sockets in server mode + +``query-named-block-nodes`` result ``encryption_key_missing`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Removed with no replacement. + +``query-block`` result ``inserted.encryption_key_missing`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Removed with no replacement. + +``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``status`` field of the ``BlockDirtyInfo`` structure, returned by +these commands is removed. Two new boolean fields, ``recording`` and +``busy`` effectively replace it. + +``query-block`` result field ``dirty-bitmaps`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by +the query-block command is itself now removed. The ``dirty-bitmaps`` +field of the ``BlockDeviceInfo`` struct should be used instead, which is the +type of the ``inserted`` field in query-block replies, as well as the +type of array items in query-named-block-nodes. + +``object-add`` option ``props`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +Specify the properties for the object as top-level arguments instead. + +Human Monitor Protocol (HMP) commands +------------------------------------- + +``usb_add`` and ``usb_remove`` (removed in 2.12) +'''''''''''''''''''''''''''''''''''''''''''''''' + +Replaced by ``device_add`` and ``device_del`` (use ``device_add help`` for a +list of available devices). + +``host_net_add`` and ``host_net_remove`` (removed in 2.12) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Replaced by ``netdev_add`` and ``netdev_del``. + +The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (removed in 5.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and +'hostfwd_remove' HMP commands has been replaced by ``netdev_id``. + +``cpu-add`` (removed in 5.2) +'''''''''''''''''''''''''''' + +Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See +documentation of ``query-hotpluggable-cpus`` for additional details. + +``change vnc TARGET`` (removed in 6.0) +'''''''''''''''''''''''''''''''''''''' + +No replacement. The ``change vnc password`` and ``change DEVICE MEDIUM`` +commands are not affected. + +``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and +``acl_remove`` commands were removed with no replacement. Authorization +for VNC should be performed using the pluggable QAuthZ objects. + +``migrate-set-cache-size`` and ``info migrate-cache-size`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate-set-parameters`` and ``info migrate-parameters`` instead. + +``migrate_set_downtime`` and ``migrate_set_speed`` (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use ``migrate-set-parameters`` instead. + +``info cpustats`` (removed in 6.1) +'''''''''''''''''''''''''''''''''' + +This command didn't produce any output already. Removed with no replacement. + +Guest Emulator ISAs +------------------- + +RISC-V ISA privilege specification version 1.09.1 (removed in 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The RISC-V ISA privilege specification version 1.09.1 has been removed. +QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these +should be used instead of the 1.09.1 version. + +System emulator CPUS +-------------------- + +KVM guest support on 32-bit Arm hosts (removed in 5.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The Linux kernel has dropped support for allowing 32-bit Arm systems +to host KVM guests as of the 5.7 kernel. Accordingly, QEMU is deprecating +its support for this configuration and will remove it in a future version. +Running 32-bit guests on a 64-bit Arm host remains supported. + +RISC-V ISA Specific CPUs (removed in 5.1) +''''''''''''''''''''''''''''''''''''''''' + +The RISC-V cpus with the ISA version in the CPU name have been removed. The +four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and +``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec`` +option when using the ``rv32`` or ``rv64`` CPUs. + +RISC-V no MMU CPUs (removed in 5.1) +''''''''''''''''''''''''''''''''''' + +The RISC-V no MMU cpus have been removed. The two CPUs: ``rv32imacu-nommu`` and +``rv64imacu-nommu`` can no longer be used. Instead the MMU status can be specified +via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs. + +``compat`` property of server class POWER CPUs (removed in 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``max-cpu-compat`` property of the ``pseries`` machine type should be used +instead. + +``moxie`` CPU (removed in 6.1) +'''''''''''''''''''''''''''''' + +Nobody was using this CPU emulation in QEMU, and there were no test images +available to make sure that the code is still working, so it has been removed +without replacement. + +``lm32`` CPUs (removed in 6.1) +'''''''''''''''''''''''''''''' + +The only public user of this architecture was the milkymist project, +which has been dead for years; there was never an upstream Linux +port. Removed without replacement. + +``unicore32`` CPUs (removed in 6.1) +''''''''''''''''''''''''''''''''''' + +Support for this CPU was removed from the upstream Linux kernel, and +there is no available upstream toolchain to build binaries for it. +Removed without replacement. + +x86 ``Icelake-Client`` CPU (removed in 7.1) +''''''''''''''''''''''''''''''''''''''''''' + +There isn't ever Icelake Client CPU, it is some wrong and imaginary one. +Use ``Icelake-Server`` instead. + +System emulator machines +------------------------ + +``s390-virtio`` (removed in 2.6) +'''''''''''''''''''''''''''''''' + +Use the ``s390-ccw-virtio`` machine instead. + +The m68k ``dummy`` machine (removed in 2.9) +''''''''''''''''''''''''''''''''''''''''''' + +Use the ``none`` machine with the ``loader`` device instead. + +``xlnx-ep108`` (removed in 3.0) +''''''''''''''''''''''''''''''' + +The EP108 was an early access development board that is no longer used. +Use the ``xlnx-zcu102`` machine instead. + +``spike_v1.9.1`` and ``spike_v1.10`` (removed in 5.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The version specific Spike machines have been removed in favour of the +generic ``spike`` machine. If you need to specify an older version of the RISC-V +spec you can use the ``-cpu rv64gcsu,priv_spec=v1.10.0`` command line argument. + +mips ``r4k`` platform (removed in 5.2) +'''''''''''''''''''''''''''''''''''''' + +This machine type was very old and unmaintained. Users should use the ``malta`` +machine type instead. + +mips ``fulong2e`` machine alias (removed in 6.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +This machine has been renamed ``fuloong2e``. + +``pc-0.10`` up to ``pc-1.3`` (removed in 4.0 up to 6.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +These machine types were very old and likely could not be used for live +migration from old QEMU versions anymore. Use a newer machine type instead. + +Raspberry Pi ``raspi2`` and ``raspi3`` machines (removed in 6.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The Raspberry Pi machines come in various models (A, A+, B, B+). To be able +to distinguish which model QEMU is implementing, the ``raspi2`` and ``raspi3`` +machines have been renamed ``raspi2b`` and ``raspi3b``. + +Aspeed ``swift-bmc`` machine (removed in 7.0) +''''''''''''''''''''''''''''''''''''''''''''' + +This machine was removed because it was unused. Alternative AST2500 based +OpenPOWER machines are ``witherspoon-bmc`` and ``romulus-bmc``. + +ppc ``taihu`` machine (removed in 7.2) +''''''''''''''''''''''''''''''''''''''''''''' + +This machine was removed because it was partially emulated and 405 +machines are very similar. Use the ``ref405ep`` machine instead. + +linux-user mode CPUs +-------------------- + +``tilegx`` CPUs (removed in 6.0) +'''''''''''''''''''''''''''''''' + +The ``tilegx`` guest CPU support has been removed without replacement. It was +only implemented in linux-user mode, but support for this CPU was removed from +the upstream Linux kernel in 2018, and it has also been dropped from glibc, so +there is no new Linux development taking place with this architecture. For +running the old binaries, you can use older versions of QEMU. + +``ppc64abi32`` CPUs (removed in 7.0) +'''''''''''''''''''''''''''''''''''' + +The ``ppc64abi32`` architecture has a number of issues which regularly +tripped up the CI testing and was suspected to be quite broken. For that +reason the maintainers strongly suspected no one actually used it. + + +TCG introspection features +-------------------------- + +TCG trace-events (since 6.2) +'''''''''''''''''''''''''''' + +The ability to add new TCG trace points had bit rotted and as the +feature can be replicated with TCG plugins it was removed. If +any user is currently using this feature and needs help with +converting to using TCG plugins they should contact the qemu-devel +mailing list. + + +System emulator devices +----------------------- + +``spapr-pci-vfio-host-bridge`` (removed in 2.12) +''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``spapr-pci-vfio-host-bridge`` device type has been replaced by the +``spapr-pci-host-bridge`` device type. + +``ivshmem`` (removed in 4.0) +'''''''''''''''''''''''''''' + +Replaced by either the ``ivshmem-plain`` or ``ivshmem-doorbell``. + +``ide-drive`` (removed in 6.0) +'''''''''''''''''''''''''''''' + +The 'ide-drive' device has been removed. Users should use 'ide-hd' or +'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed. + +``scsi-disk`` (removed in 6.0) +'''''''''''''''''''''''''''''' + +The 'scsi-disk' device has been removed. Users should use 'scsi-hd' or +'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed. + +Related binaries +---------------- + +``qemu-nbd --partition`` (removed in 5.0) +''''''''''''''''''''''''''''''''''''''''' + +The ``qemu-nbd --partition $digit`` code (also spelled ``-P``) +could only handle MBR partitions, and never correctly handled logical +partitions beyond partition 5. Exporting a partition can still be +done by utilizing the ``--image-opts`` option with a raw blockdev +using the ``offset`` and ``size`` parameters layered on top of +any other existing blockdev. For example, if partition 1 is 100MiB +long starting at 1MiB, the old command:: + + qemu-nbd -t -P 1 -f qcow2 file.qcow2 + +can be rewritten as:: + + qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2 + +``qemu-img convert -n -o`` (removed in 5.1) +''''''''''''''''''''''''''''''''''''''''''' + +All options specified in ``-o`` are image creation options, so +they are now rejected when used with ``-n`` to skip image creation. + + +``qemu-img create -b bad file $size`` (removed in 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +When creating an image with a backing file that could not be opened, +``qemu-img create`` used to issue a warning about the failure but +proceed with the image creation if an explicit size was provided. +However, as the ``-u`` option exists for this purpose, it is safer to +enforce that any failure to open the backing image (including if the +backing file is missing or an incorrect format was specified) is an +error when ``-u`` is not used. + +``qemu-img amend`` to adjust backing file (removed in 6.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The use of ``qemu-img amend`` to modify the name or format of a qcow2 +backing image was never fully documented or tested, and interferes +with other amend operations that need access to the original backing +image (such as deciding whether a v3 zero cluster may be left +unallocated when converting to a v2 image). Any changes to the +backing chain should be performed with ``qemu-img rebase -u`` either +before or after the remaining changes being performed by amend, as +appropriate. + +``qemu-img`` backing file without format (removed in 6.1) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The use of ``qemu-img create``, ``qemu-img rebase``, or ``qemu-img +convert`` to create or modify an image that depends on a backing file +now requires that an explicit backing format be provided. This is +for safety: if QEMU probes a different format than what you thought, +the data presented to the guest will be corrupt; similarly, presenting +a raw image to a guest allows a potential security exploit if a future +probe sees a non-raw image based on guest writes. + +To avoid creating unsafe backing chains, you must pass ``-o +backing_fmt=`` (or the shorthand ``-F`` during create) to specify the +intended backing format. You may use ``qemu-img rebase -u`` to +retroactively add a backing format to an existing image. However, be +aware that there are already potential security risks to blindly using +``qemu-img info`` to probe the format of an untrusted backing image, +when deciding what format to add into an existing image. + +Block devices +------------- + +VXHS backend (removed in 5.1) +''''''''''''''''''''''''''''' + +The VXHS code did not compile since v2.12.0. It was removed in 5.1. + +``sheepdog`` driver (removed in 6.0) +'''''''''''''''''''''''''''''''''''' + +The corresponding upstream server project is no longer maintained. +Users are recommended to switch to an alternative distributed block +device driver such as RBD. |