diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/build-platforms.rst | 3 | ||||
| -rw-r--r-- | docs/about/deprecated.rst | 20 | ||||
| -rw-r--r-- | docs/config/mach-virt-graphical.cfg | 4 | ||||
| -rw-r--r-- | docs/config/mach-virt-serial.cfg | 4 | ||||
| -rw-r--r-- | docs/config/q35-emulated.cfg | 2 | ||||
| -rw-r--r-- | docs/config/q35-virtio-graphical.cfg | 2 | ||||
| -rw-r--r-- | docs/config/q35-virtio-serial.cfg | 2 | ||||
| -rw-r--r-- | docs/devel/atomics.rst | 42 | ||||
| -rw-r--r-- | docs/devel/vfio-migration.rst | 46 | ||||
| -rw-r--r-- | docs/meson.build | 2 | ||||
| -rw-r--r-- | docs/sphinx/kerneldoc.py | 5 | ||||
| -rw-r--r-- | docs/system/arm/cpu-features.rst | 76 | ||||
| -rw-r--r-- | docs/system/device-emulation.rst | 1 | ||||
| -rw-r--r-- | docs/system/devices/igb.rst | 71 | ||||
| -rw-r--r-- | docs/system/i386/xen.rst | 30 | ||||
| -rw-r--r-- | docs/system/target-mips.rst | 14 |
16 files changed, 232 insertions, 92 deletions
diff --git a/docs/about/build-platforms.rst b/docs/about/build-platforms.rst index 20b97c3310..89cae5a6bb 100644 --- a/docs/about/build-platforms.rst +++ b/docs/about/build-platforms.rst @@ -67,7 +67,8 @@ Non-supported architectures may be removed in the future following the Linux OS, macOS, FreeBSD, NetBSD, OpenBSD ----------------------------------------- -The project aims to support the most recent major version at all times. Support +The project aims to support the most recent major version at all times for +up to five years after its initial release. 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 diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index 15084f7bea..33b942283f 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -196,6 +196,26 @@ 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. +System emulation on 32-bit x86 hosts (since 8.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +Support for 32-bit x86 host deployments is increasingly uncommon in mainstream +OS distributions given the widespread availability of 64-bit x86 hardware. +The QEMU project no longer considers 32-bit x86 support for system emulation to +be an effective use of its limited resources, and thus intends to discontinue +it. Since all recent x86 hardware from the past >10 years is capable of the +64-bit x86 extensions, a corresponding 64-bit OS should be used instead. + +System emulation on 32-bit arm hosts (since 8.0) +'''''''''''''''''''''''''''''''''''''''''''''''' + +Since QEMU needs a strong host machine for running full system emulation, and +all recent powerful arm hosts support 64-bit, the QEMU project deprecates the +support for running any system emulation on 32-bit arm hosts in general. Use +64-bit arm hosts for system emulation instead. (Note: "user" mode emulation +continues to be supported on 32-bit arm hosts, too) + + QEMU API (QAPI) events ---------------------- diff --git a/docs/config/mach-virt-graphical.cfg b/docs/config/mach-virt-graphical.cfg index d6d31b17f5..eba76eb198 100644 --- a/docs/config/mach-virt-graphical.cfg +++ b/docs/config/mach-virt-graphical.cfg @@ -56,9 +56,11 @@ [machine] type = "virt" - accel = "kvm" gic-version = "host" +[accel] + accel = "kvm" + [memory] size = "1024" diff --git a/docs/config/mach-virt-serial.cfg b/docs/config/mach-virt-serial.cfg index 18a7c83731..324b0542ff 100644 --- a/docs/config/mach-virt-serial.cfg +++ b/docs/config/mach-virt-serial.cfg @@ -62,9 +62,11 @@ [machine] type = "virt" - accel = "kvm" gic-version = "host" +[accel] + accel = "kvm" + [memory] size = "1024" diff --git a/docs/config/q35-emulated.cfg b/docs/config/q35-emulated.cfg index 99ac918e78..c8806e6d36 100644 --- a/docs/config/q35-emulated.cfg +++ b/docs/config/q35-emulated.cfg @@ -61,6 +61,8 @@ [machine] type = "q35" + +[accel] accel = "kvm" [memory] diff --git a/docs/config/q35-virtio-graphical.cfg b/docs/config/q35-virtio-graphical.cfg index 4207f11e4f..148b5d2c5e 100644 --- a/docs/config/q35-virtio-graphical.cfg +++ b/docs/config/q35-virtio-graphical.cfg @@ -55,6 +55,8 @@ [machine] type = "q35" + +[accel] accel = "kvm" [memory] diff --git a/docs/config/q35-virtio-serial.cfg b/docs/config/q35-virtio-serial.cfg index d2830aec5e..023291390e 100644 --- a/docs/config/q35-virtio-serial.cfg +++ b/docs/config/q35-virtio-serial.cfg @@ -60,6 +60,8 @@ [machine] type = "q35" + +[accel] accel = "kvm" [memory] diff --git a/docs/devel/atomics.rst b/docs/devel/atomics.rst index 7957310071..81ec26be17 100644 --- a/docs/devel/atomics.rst +++ b/docs/devel/atomics.rst @@ -27,7 +27,8 @@ provides macros that fall in three camps: - weak atomic access and manual memory barriers: ``qatomic_read()``, ``qatomic_set()``, ``smp_rmb()``, ``smp_wmb()``, ``smp_mb()``, - ``smp_mb_acquire()``, ``smp_mb_release()``, ``smp_read_barrier_depends()``; + ``smp_mb_acquire()``, ``smp_mb_release()``, ``smp_read_barrier_depends()``, + ``smp_mb__before_rmw()``, ``smp_mb__after_rmw()``; - sequentially consistent atomic access: everything else. @@ -468,13 +469,19 @@ and memory barriers, and the equivalents in QEMU: In QEMU, the second kind is named ``atomic_OP_fetch``. - different atomic read-modify-write operations in Linux imply - a different set of memory barriers; in QEMU, all of them enforce - sequential consistency. + a different set of memory barriers. In QEMU, all of them enforce + sequential consistency: there is a single order in which the + program sees them happen. -- in QEMU, ``qatomic_read()`` and ``qatomic_set()`` do not participate in - the total ordering enforced by sequentially-consistent operations. - This is because QEMU uses the C11 memory model. The following example - is correct in Linux but not in QEMU: +- however, according to the C11 memory model that QEMU uses, this order + does not propagate to other memory accesses on either side of the + read-modify-write operation. As far as those are concerned, the + operation consist of just a load-acquire followed by a store-release. + Stores that precede the RMW operation, and loads that follow it, can + still be reordered and will happen *in the middle* of the read-modify-write + operation! + + Therefore, the following example is correct in Linux but not in QEMU: +----------------------------------+--------------------------------+ | Linux (correct) | QEMU (incorrect) | @@ -488,9 +495,24 @@ and memory barriers, and the equivalents in QEMU: because the read of ``y`` can be moved (by either the processor or the compiler) before the write of ``x``. - Fixing this requires an ``smp_mb()`` memory barrier between the write - of ``x`` and the read of ``y``. In the common case where only one thread - writes ``x``, it is also possible to write it like this: + Fixing this requires a full memory barrier between the write of ``x`` and + the read of ``y``. QEMU provides ``smp_mb__before_rmw()`` and + ``smp_mb__after_rmw()``; they act both as an optimization, + avoiding the memory barrier on processors where it is unnecessary, + and as a clarification of this corner case of the C11 memory model: + + +--------------------------------+ + | QEMU (correct) | + +================================+ + | :: | + | | + | a = qatomic_fetch_add(&x, 2);| + | smp_mb__after_rmw(); | + | b = qatomic_read(&y); | + +--------------------------------+ + + In the common case where only one thread writes ``x``, it is also possible + to write it like this: +--------------------------------+ | QEMU (correct) | diff --git a/docs/devel/vfio-migration.rst b/docs/devel/vfio-migration.rst index c214c73e28..1b68ccf115 100644 --- a/docs/devel/vfio-migration.rst +++ b/docs/devel/vfio-migration.rst @@ -59,22 +59,37 @@ System memory dirty pages tracking ---------------------------------- A ``log_global_start`` and ``log_global_stop`` memory listener callback informs -the VFIO IOMMU module to start and stop dirty page tracking. A ``log_sync`` -memory listener callback marks those system memory pages as dirty which are -used for DMA by the VFIO device. The dirty pages bitmap is queried per -container. All pages pinned by the vendor driver through external APIs have to -be marked as dirty during migration. When there are CPU writes, CPU dirty page -tracking can identify dirtied pages, but any page pinned by the vendor driver -can also be written by the device. There is currently no device or IOMMU -support for dirty page tracking in hardware. +the VFIO dirty tracking module to start and stop dirty page tracking. A +``log_sync`` memory listener callback queries the dirty page bitmap from the +dirty tracking module and marks system memory pages which were DMA-ed by the +VFIO device as dirty. The dirty page bitmap is queried per container. + +Currently there are two ways dirty page tracking can be done: +(1) Device dirty tracking: +In this method the device is responsible to log and report its DMAs. This +method can be used only if the device is capable of tracking its DMAs. +Discovering device capability, starting and stopping dirty tracking, and +syncing the dirty bitmaps from the device are done using the DMA logging uAPI. +More info about the uAPI can be found in the comments of the +``vfio_device_feature_dma_logging_control`` and +``vfio_device_feature_dma_logging_report`` structures in the header file +linux-headers/linux/vfio.h. + +(2) VFIO IOMMU module: +In this method dirty tracking is done by IOMMU. However, there is currently no +IOMMU support for dirty page tracking. For this reason, all pages are +perpetually marked dirty, unless the device driver pins pages through external +APIs in which case only those pinned pages are perpetually marked dirty. + +If the above two methods are not supported, all pages are perpetually marked +dirty by QEMU. By default, dirty pages are tracked during pre-copy as well as stop-and-copy -phase. So, a page pinned by the vendor driver will be copied to the destination -in both phases. Copying dirty pages in pre-copy phase helps QEMU to predict if -it can achieve its downtime tolerances. If QEMU during pre-copy phase keeps -finding dirty pages continuously, then it understands that even in stop-and-copy -phase, it is likely to find dirty pages and can predict the downtime -accordingly. +phase. So, a page marked as dirty will be copied to the destination in both +phases. Copying dirty pages in pre-copy phase helps QEMU to predict if it can +achieve its downtime tolerances. If QEMU during pre-copy phase keeps finding +dirty pages continuously, then it understands that even in stop-and-copy phase, +it is likely to find dirty pages and can predict the downtime accordingly. QEMU also provides a per device opt-out option ``pre-copy-dirty-page-tracking`` which disables querying the dirty bitmap during pre-copy phase. If it is set to @@ -89,7 +104,8 @@ phase of migration. In that case, the unmap ioctl returns any dirty pages in that range and QEMU reports corresponding guest physical pages dirty. During stop-and-copy phase, an IOMMU notifier is used to get a callback for mapped pages and then dirty pages bitmap is fetched from VFIO IOMMU modules for those -mapped ranges. +mapped ranges. If device dirty tracking is enabled with vIOMMU, live migration +will be blocked. Flow of state changes during Live migration =========================================== diff --git a/docs/meson.build b/docs/meson.build index bb72c10ea8..f220800e3e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -7,7 +7,7 @@ if sphinx_build.found() SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q'] # If we're making warnings fatal, apply this to Sphinx runs as well if get_option('werror') - SPHINX_ARGS += [ '-W' ] + SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ] endif # This is a bit awkward but works: create a trivial document and diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py index bf44215016..72c403a737 100644 --- a/docs/sphinx/kerneldoc.py +++ b/docs/sphinx/kerneldoc.py @@ -74,6 +74,10 @@ class KernelDocDirective(Directive): # Sphinx versions cmd += ['-sphinx-version', sphinx.__version__] + # Pass through the warnings-as-errors flag + if env.config.kerneldoc_werror: + cmd += ['-Werror'] + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] export_file_patterns = [] @@ -167,6 +171,7 @@ def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') app.add_config_value('kerneldoc_verbosity', 1, 'env') + app.add_config_value('kerneldoc_werror', 0, 'env') app.add_directive('kernel-doc', KernelDocDirective) diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst index 00c444042f..f4524b6d3e 100644 --- a/docs/system/arm/cpu-features.rst +++ b/docs/system/arm/cpu-features.rst @@ -177,39 +177,32 @@ are named with the prefix "kvm-". KVM VCPU features may be probed, enabled, and disabled in the same way as other CPU features. Below is the list of KVM VCPU features and their descriptions. - kvm-no-adjvtime By default kvm-no-adjvtime is disabled. This - means that by default the virtual time - adjustment is enabled (vtime is not *not* - adjusted). - - When virtual time adjustment is enabled each - time the VM transitions back to running state - the VCPU's virtual counter is updated to ensure - stopped time is not counted. This avoids time - jumps surprising guest OSes and applications, - as long as they use the virtual counter for - timekeeping. However it has the side effect of - the virtual and physical counters diverging. - All timekeeping based on the virtual counter - will appear to lag behind any timekeeping that - does not subtract VM stopped time. The guest - may resynchronize its virtual counter with - other time sources as needed. - - Enable kvm-no-adjvtime to disable virtual time - adjustment, also restoring the legacy (pre-5.0) - behavior. - - kvm-steal-time Since v5.2, kvm-steal-time is enabled by - default when KVM is enabled, the feature is - supported, and the guest is 64-bit. - - When kvm-steal-time is enabled a 64-bit guest - can account for time its CPUs were not running - due to the host not scheduling the corresponding - VCPU threads. The accounting statistics may - influence the guest scheduler behavior and/or be - exposed to the guest userspace. +``kvm-no-adjvtime`` + By default kvm-no-adjvtime is disabled. This means that by default + the virtual time adjustment is enabled (vtime is not *not* adjusted). + + When virtual time adjustment is enabled each time the VM transitions + back to running state the VCPU's virtual counter is updated to + ensure stopped time is not counted. This avoids time jumps + surprising guest OSes and applications, as long as they use the + virtual counter for timekeeping. However it has the side effect of + the virtual and physical counters diverging. All timekeeping based + on the virtual counter will appear to lag behind any timekeeping + that does not subtract VM stopped time. The guest may resynchronize + its virtual counter with other time sources as needed. + + Enable kvm-no-adjvtime to disable virtual time adjustment, also + restoring the legacy (pre-5.0) behavior. + +``kvm-steal-time`` + Since v5.2, kvm-steal-time is enabled by default when KVM is + enabled, the feature is supported, and the guest is 64-bit. + + When kvm-steal-time is enabled a 64-bit guest can account for time + its CPUs were not running due to the host not scheduling the + corresponding VCPU threads. The accounting statistics may influence + the guest scheduler behavior and/or be exposed to the guest + userspace. TCG VCPU Features ================= @@ -217,16 +210,15 @@ TCG VCPU Features TCG VCPU features are CPU features that are specific to TCG. Below is the list of TCG VCPU features and their descriptions. - pauth-impdef When ``FEAT_Pauth`` is enabled, either the - *impdef* (Implementation Defined) algorithm - is enabled or the *architected* QARMA algorithm - is enabled. By default the impdef algorithm - is disabled, and QARMA is enabled. +``pauth-impdef`` + When ``FEAT_Pauth`` is enabled, either the *impdef* (Implementation + Defined) algorithm is enabled or the *architected* QARMA algorithm + is enabled. By default the impdef algorithm is disabled, and QARMA + is enabled. - The architected QARMA algorithm has good - cryptographic properties, but can be quite slow - to emulate. The impdef algorithm used by QEMU - is non-cryptographic but significantly faster. + The architected QARMA algorithm has good cryptographic properties, + but can be quite slow to emulate. The impdef algorithm used by QEMU + is non-cryptographic but significantly faster. SVE CPU Properties ================== diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index 0506006056..c1b1934e3d 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -93,3 +93,4 @@ Emulated Devices devices/virtio-pmem.rst devices/vhost-user-rng.rst devices/canokey.rst + devices/igb.rst diff --git a/docs/system/devices/igb.rst b/docs/system/devices/igb.rst new file mode 100644 index 0000000000..70edadd574 --- /dev/null +++ b/docs/system/devices/igb.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later +.. _igb: + +igb +--- + +igb is a family of Intel's gigabit ethernet controllers. In QEMU, 82576 +emulation is implemented in particular. Its datasheet is available at [1]_. + +This implementation is expected to be useful to test SR-IOV networking without +requiring physical hardware. + +Limitations +=========== + +This igb implementation was tested with Linux Test Project [2]_ and Windows HLK +[3]_ during the initial development. The command used when testing with LTP is: + +.. code-block:: shell + + network.sh -6mta + +Be aware that this implementation lacks many functionalities available with the +actual hardware, and you may experience various failures if you try to use it +with a different operating system other than Linux and Windows or if you try +functionalities not covered by the tests. + +Using igb +========= + +Using igb should be nothing different from using another network device. See +:ref:`pcsys_005fnetwork` in general. + +However, you may also need to perform additional steps to activate SR-IOV +feature on your guest. For Linux, refer to [4]_. + +Developing igb +============== + +igb is the successor of e1000e, and e1000e is the successor of e1000 in turn. +As these devices are very similar, if you make a change for igb and the same +change can be applied to e1000e and e1000, please do so. + +Please do not forget to run tests before submitting a change. As tests included +in QEMU is very minimal, run some application which is likely to be affected by +the change to confirm it works in an integrated system. + +Testing igb +=========== + +A qtest of the basic functionality is available. Run the below at the build +directory: + +.. code-block:: shell + + meson test qtest-x86_64/qos-test + +ethtool can test register accesses, interrupts, etc. It is automated as an +Avocado test and can be ran with the following command: + +.. code:: shell + + make check-avocado AVOCADO_TESTS=tests/avocado/igb.py + +References +========== + +.. [1] https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/82576eb-gigabit-ethernet-controller-datasheet.pdf +.. [2] https://github.com/linux-test-project/ltp +.. [3] https://learn.microsoft.com/en-us/windows-hardware/test/hlk/ +.. [4] https://docs.kernel.org/PCI/pci-iov-howto.html diff --git a/docs/system/i386/xen.rst b/docs/system/i386/xen.rst index a00523b492..f06765e88c 100644 --- a/docs/system/i386/xen.rst +++ b/docs/system/i386/xen.rst @@ -9,6 +9,8 @@ KVM has support for hosting Xen guests, intercepting Xen hypercalls and event channel (Xen PV interrupt) delivery. This allows guests which expect to be run under Xen to be hosted in QEMU under Linux/KVM instead. +Using the split irqchip is mandatory for Xen support. + Setup ----- @@ -17,14 +19,14 @@ accelerator, for example for Xen 4.10: .. parsed-literal:: - |qemu_system| --accel kvm,xen-version=0x4000a + |qemu_system| --accel kvm,xen-version=0x4000a,kernel-irqchip=split Additionally, virtual APIC support can be advertised to the guest through the ``xen-vapic`` CPU flag: .. parsed-literal:: - |qemu_system| --accel kvm,xen-version=0x4000a --cpu host,+xen_vapic + |qemu_system| --accel kvm,xen-version=0x4000a,kernel-irqchip=split --cpu host,+xen_vapic When Xen support is enabled, QEMU changes hypervisor identification (CPUID 0x40000000..0x4000000A) to Xen. The KVM identification and features are not @@ -33,11 +35,25 @@ moves to leaves 0x40000100..0x4000010A. The Xen platform device is enabled automatically for a Xen guest. This allows a guest to unplug all emulated devices, in order to use Xen PV block and network -drivers instead. Note that until the Xen PV device back ends are enabled to work -with Xen mode in QEMU, that is unlikely to cause significant joy. Linux guests -can be dissuaded from this by adding 'xen_emul_unplug=never' on their command -line, and it can also be noted that AHCI disk controllers are exempt from being -unplugged, as are passthrough VFIO PCI devices. +drivers instead. Under Xen, the boot disk is typically available both via IDE +emulation, and as a PV block device. Guest bootloaders typically use IDE to load +the guest kernel, which then unplugs the IDE and continues with the Xen PV block +device. + +This configuration can be achieved as follows + +.. parsed-literal:: + + |qemu_system| -M pc --accel kvm,xen-version=0x4000a,kernel-irqchip=split \\ + -drive file=${GUEST_IMAGE},if=none,id=disk,file.locking=off -device xen-disk,drive=disk,vdev=xvda \\ + -drive file=${GUEST_IMAGE},index=2,media=disk,file.locking=off,if=ide + +It is necessary to use the pc machine type, as the q35 machine uses AHCI instead +of legacy IDE, and AHCI disks are not unplugged through the Xen PV unplug +mechanism. + +VirtIO devices can also be used; Linux guests may need to be dissuaded from +umplugging them by adding 'xen_emul_unplug=never' on their command line. Properties ---------- diff --git a/docs/system/target-mips.rst b/docs/system/target-mips.rst index 138441bdec..83239fb9df 100644 --- a/docs/system/target-mips.rst +++ b/docs/system/target-mips.rst @@ -8,8 +8,6 @@ endian options, ``qemu-system-mips``, ``qemu-system-mipsel`` ``qemu-system-mips64`` and ``qemu-system-mips64el``. Five different machine types are emulated: -- A generic ISA PC-like machine \"mips\" - - The MIPS Malta prototype board \"malta\" - An ACER Pica \"pica61\". This machine needs the 64-bit emulator. @@ -19,18 +17,6 @@ machine types are emulated: - A MIPS Magnum R4000 machine \"magnum\". This machine needs the 64-bit emulator. -The generic emulation is supported by Debian 'Etch' and is able to -install Debian into a virtual disk image. The following devices are -emulated: - -- A range of MIPS CPUs, default is the 24Kf - -- PC style serial port - -- PC style IDE disk - -- NE2000 network card - The Malta emulation supports the following devices: - Core board with MIPS 24Kf CPU and Galileo system controller |