From: Peter Maydell Date: Mon, 5 Jul 2021 09:55:44 +0000 (+0100) Subject: docs: Move deprecation, build and license info out of system/ X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=f347839258a1ace57d0b59e89bf01352b8d1c13b;p=qemu.git docs: Move deprecation, build and license info out of system/ Now that we have a single Sphinx manual rather than multiple manuals, we can provide a better place for "common to all of QEMU" information like the deprecation notices, build platforms, license information, which we currently have in the system/ manual even though it applies to all of QEMU. Create a new directory about/ on the same level as system/, user/, etc, and move these documents there. Signed-off-by: Peter Maydell Acked-by: Markus Armbruster Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Daniel P. Berrangé Message-id: 20210705095547.15790-5-peter.maydell@linaro.org --- diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst new file mode 100644 index 0000000000..692323609e --- /dev/null +++ b/docs/about/build-platforms.rst @@ -0,0 +1,62 @@ +.. _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. + +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). + +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 supports building with current versions of the MinGW toolchain, +hosted on Linux (Debian/Fedora). + +The version of the Windows API that's currently targeted is Vista / Server +2008. + +.. _HomeBrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/ +.. _Repology: https://repology.org/ diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst new file mode 100644 index 0000000000..6d438f1c8d --- /dev/null +++ b/docs/about/deprecated.rst @@ -0,0 +1,339 @@ +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. + +Creating sound card devices using ``-soundhw`` (since 5.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Sound card devices should be created using ``-device`` instead. The +names are the same for most devices. The exceptions are ``hda`` which +needs two devices (``-device intel-hda -device hda-duplex``) and +``pcspk`` which can be activated using ``-machine +pcspk-audiodev=``. + +``-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``. + +``--enable-fips`` (since 6.0) +''''''''''''''''''''''''''''' + +This option restricts 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`` +library enabled as a cryptography provider. + +Neither the ``nettle`` library, or the built-in cryptography provider are +supported on FIPS enabled hosts. + +``-writeconfig`` (since 6.0) +''''''''''''''''''''''''''''' + +The ``-writeconfig`` option is not able to serialize the entire contents +of the QEMU command line. It is thus considered a failed experiment +and deprecated, with no current replacement. + +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. + +``opened`` property of ``rng-*`` objects (since 6.0.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The only effect of specifying ``opened=on`` in the command line or QMP +``object-add`` is that the device is opened immediately, possibly before all +other options have been processed. This will either have no effect (if +``opened`` was the last option) or cause errors. The property is therefore +useless and should not be specified. + +``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The only effect of specifying ``loaded=on`` in the command line or QMP +``object-add`` is that the secret is loaded immediately, possibly before all +other options have been processed. This will either have no effect (if +``loaded`` was the last option) or cause options to be effectively ignored as +if they were not given. The property is therefore useless and should not be +specified. + +``-display sdl,window_close=...`` (since 6.1) +''''''''''''''''''''''''''''''''''''''''''''' + +Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of +an underscore between "window" and "close"). + +``-no-quit`` (since 6.1) +'''''''''''''''''''''''' + +The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which +should be used instead. + + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``eject`` argument ``device`` (since 2.8.0) +''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``blockdev-change-medium`` argument ``device`` (since 2.8.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``block_set_io_throttle`` argument ``device`` (since 2.8.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument ``id`` instead. + +``blockdev-add`` empty string argument ``backing`` (since 2.10.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use argument value ``null`` instead. + +``block-commit`` arguments ``base`` and ``top`` (since 3.1.0) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +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``. + +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. + +System emulator CPUS +-------------------- + +``Icelake-Client`` CPU Model (since 5.2.0) +'''''''''''''''''''''''''''''''''''''''''' + +``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU +Models instead. + +MIPS ``I7200`` CPU Model (since 5.2) +'''''''''''''''''''''''''''''''''''' + +The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated +(the ISA has never been upstreamed to a compiler toolchain). Therefore +this CPU is also deprecated. + +System emulator machines +------------------------ + +Raspberry Pi ``raspi2`` and ``raspi3`` machines (since 5.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 (since 6.1) +'''''''''''''''''''''''''''''''''''''''' + +This machine is deprecated because we have enough AST2500 based OpenPOWER +machines. It can be easily replaced by the ``witherspoon-bmc`` or the +``romulus-bmc`` machines. + +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.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. + +Block device options +'''''''''''''''''''' + +``"backing": ""`` (since 2.12.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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.0) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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"} + +linux-user mode CPUs +-------------------- + +``ppc64abi32`` CPUs (since 5.2.0) +''''''''''''''''''''''''''''''''' + +The ``ppc64abi32`` architecture has a number of issues which regularly +trip up our CI testing and is suspected to be quite broken. For that +reason the maintainers strongly suspect no one actually uses it. + +MIPS ``I7200`` CPU (since 5.2) +'''''''''''''''''''''''''''''' + +The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated +(the ISA has never been upstreamed to a compiler toolchain). Therefore +this CPU is also deprecated. + +Related binaries +---------------- + +Backwards compatibility +----------------------- + +Runnability guarantee of CPU models (since 4.1.0) +''''''''''''''''''''''''''''''''''''''''''''''''' + +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. + +Guest Emulator ISAs +------------------- + +nanoMIPS ISA +'''''''''''' + +The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. +As it is hard to generate binaries for it, declare it deprecated. diff --git a/docs/about/index.rst b/docs/about/index.rst new file mode 100644 index 0000000000..cd44456a6b --- /dev/null +++ b/docs/about/index.rst @@ -0,0 +1,10 @@ +About QEMU +========== + +.. 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 0000000000..cde3d2d25d --- /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 `__, version 2. Parts +of QEMU have specific licenses, see file +`LICENSE `__. diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst new file mode 100644 index 0000000000..28bb035043 --- /dev/null +++ b/docs/about/removed-features.rst @@ -0,0 +1,538 @@ + +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 +-------------------------------------- + +``-net ...,name=``\ *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. + +``-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 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. + +QEMU Machine Protocol (QMP) commands +------------------------------------ + +``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2.0) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +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`` 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 +------------------------------------- + +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.0) +'''''''''''''''''''''''''''''''' + +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 (since 6.1.0) +'''''''''''''''''''''''''''''''' + +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. + +System emulator machines +------------------------ + +``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-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (removed in 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. + + +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. + +System emulator devices +----------------------- + +``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. + +Command line options +-------------------- + +``-smp`` (invalid topologies) (removed 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*. + +``-numa`` node (without memory specified) (removed 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``. + +``-numa node,mem=``\ *size* (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. + +``-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. + +``-smp`` (invalid topologies) (removed 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 5.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``enforce-config-section`` property was replaced by the +``-global migration.send-configuration={on|off}`` option. + +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. diff --git a/docs/index.rst b/docs/index.rst index 763e3d0426..5f7eaaa632 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Welcome to QEMU's documentation! :maxdepth: 2 :caption: Contents: + about/index system/index user/index tools/index diff --git a/docs/system/build-platforms.rst b/docs/system/build-platforms.rst deleted file mode 100644 index 692323609e..0000000000 --- a/docs/system/build-platforms.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _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. - -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). - -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 supports building with current versions of the MinGW toolchain, -hosted on Linux (Debian/Fedora). - -The version of the Windows API that's currently targeted is Vista / Server -2008. - -.. _HomeBrew: https://brew.sh/ -.. _MacPorts: https://www.macports.org/ -.. _Repology: https://repology.org/ diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst deleted file mode 100644 index 6d438f1c8d..0000000000 --- a/docs/system/deprecated.rst +++ /dev/null @@ -1,339 +0,0 @@ -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. - -Creating sound card devices using ``-soundhw`` (since 5.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Sound card devices should be created using ``-device`` instead. The -names are the same for most devices. The exceptions are ``hda`` which -needs two devices (``-device intel-hda -device hda-duplex``) and -``pcspk`` which can be activated using ``-machine -pcspk-audiodev=``. - -``-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``. - -``--enable-fips`` (since 6.0) -''''''''''''''''''''''''''''' - -This option restricts 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`` -library enabled as a cryptography provider. - -Neither the ``nettle`` library, or the built-in cryptography provider are -supported on FIPS enabled hosts. - -``-writeconfig`` (since 6.0) -''''''''''''''''''''''''''''' - -The ``-writeconfig`` option is not able to serialize the entire contents -of the QEMU command line. It is thus considered a failed experiment -and deprecated, with no current replacement. - -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. - -``opened`` property of ``rng-*`` objects (since 6.0.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The only effect of specifying ``opened=on`` in the command line or QMP -``object-add`` is that the device is opened immediately, possibly before all -other options have been processed. This will either have no effect (if -``opened`` was the last option) or cause errors. The property is therefore -useless and should not be specified. - -``loaded`` property of ``secret`` and ``secret_keyring`` objects (since 6.0.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The only effect of specifying ``loaded=on`` in the command line or QMP -``object-add`` is that the secret is loaded immediately, possibly before all -other options have been processed. This will either have no effect (if -``loaded`` was the last option) or cause options to be effectively ignored as -if they were not given. The property is therefore useless and should not be -specified. - -``-display sdl,window_close=...`` (since 6.1) -''''''''''''''''''''''''''''''''''''''''''''' - -Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of -an underscore between "window" and "close"). - -``-no-quit`` (since 6.1) -'''''''''''''''''''''''' - -The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which -should be used instead. - - -QEMU Machine Protocol (QMP) commands ------------------------------------- - -``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Use argument ``id`` instead. - -``eject`` argument ``device`` (since 2.8.0) -''''''''''''''''''''''''''''''''''''''''''' - -Use argument ``id`` instead. - -``blockdev-change-medium`` argument ``device`` (since 2.8.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Use argument ``id`` instead. - -``block_set_io_throttle`` argument ``device`` (since 2.8.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Use argument ``id`` instead. - -``blockdev-add`` empty string argument ``backing`` (since 2.10.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Use argument value ``null`` instead. - -``block-commit`` arguments ``base`` and ``top`` (since 3.1.0) -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -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``. - -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. - -System emulator CPUS --------------------- - -``Icelake-Client`` CPU Model (since 5.2.0) -'''''''''''''''''''''''''''''''''''''''''' - -``Icelake-Client`` CPU Models are deprecated. Use ``Icelake-Server`` CPU -Models instead. - -MIPS ``I7200`` CPU Model (since 5.2) -'''''''''''''''''''''''''''''''''''' - -The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated -(the ISA has never been upstreamed to a compiler toolchain). Therefore -this CPU is also deprecated. - -System emulator machines ------------------------- - -Raspberry Pi ``raspi2`` and ``raspi3`` machines (since 5.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 (since 6.1) -'''''''''''''''''''''''''''''''''''''''' - -This machine is deprecated because we have enough AST2500 based OpenPOWER -machines. It can be easily replaced by the ``witherspoon-bmc`` or the -``romulus-bmc`` machines. - -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.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. - -Block device options -'''''''''''''''''''' - -``"backing": ""`` (since 2.12.0) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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.0) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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"} - -linux-user mode CPUs --------------------- - -``ppc64abi32`` CPUs (since 5.2.0) -''''''''''''''''''''''''''''''''' - -The ``ppc64abi32`` architecture has a number of issues which regularly -trip up our CI testing and is suspected to be quite broken. For that -reason the maintainers strongly suspect no one actually uses it. - -MIPS ``I7200`` CPU (since 5.2) -'''''''''''''''''''''''''''''' - -The ``I7200`` guest CPU relies on the nanoMIPS ISA, which is deprecated -(the ISA has never been upstreamed to a compiler toolchain). Therefore -this CPU is also deprecated. - -Related binaries ----------------- - -Backwards compatibility ------------------------ - -Runnability guarantee of CPU models (since 4.1.0) -''''''''''''''''''''''''''''''''''''''''''''''''' - -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. - -Guest Emulator ISAs -------------------- - -nanoMIPS ISA -'''''''''''' - -The ``nanoMIPS`` ISA has never been upstreamed to any compiler toolchain. -As it is hard to generate binaries for it, declare it deprecated. diff --git a/docs/system/index.rst b/docs/system/index.rst index 058cabd36c..fda4b1b705 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -35,7 +35,3 @@ or Hypervisor.Framework. targets security multi-process - deprecated - removed-features - build-platforms - license diff --git a/docs/system/license.rst b/docs/system/license.rst deleted file mode 100644 index cde3d2d25d..0000000000 --- a/docs/system/license.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _License: - -License -======= - -QEMU is a trademark of Fabrice Bellard. - -QEMU is released under the `GNU General Public -License `__, version 2. Parts -of QEMU have specific licenses, see file -`LICENSE `__. diff --git a/docs/system/removed-features.rst b/docs/system/removed-features.rst deleted file mode 100644 index 28bb035043..0000000000 --- a/docs/system/removed-features.rst +++ /dev/null @@ -1,538 +0,0 @@ - -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 --------------------------------------- - -``-net ...,name=``\ *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. - -``-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 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. - -QEMU Machine Protocol (QMP) commands ------------------------------------- - -``block-dirty-bitmap-add`` "autoload" parameter (removed in 4.2.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -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`` 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 -------------------------------------- - -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.0) -'''''''''''''''''''''''''''''''' - -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 (since 6.1.0) -'''''''''''''''''''''''''''''''' - -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. - -System emulator machines ------------------------- - -``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-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (removed in 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. - - -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. - -System emulator devices ------------------------ - -``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. - -Command line options --------------------- - -``-smp`` (invalid topologies) (removed 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*. - -``-numa`` node (without memory specified) (removed 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``. - -``-numa node,mem=``\ *size* (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. - -``-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. - -``-smp`` (invalid topologies) (removed 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 5.2) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The ``enforce-config-section`` property was replaced by the -``-global migration.send-configuration={on|off}`` option. - -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.