diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/devel/testing.rst | 4 | ||||
| -rw-r--r-- | docs/interop/vhost-user.rst | 21 | ||||
| -rw-r--r-- | docs/specs/ppc-spapr-xive.rst | 112 | ||||
| -rw-r--r-- | docs/specs/ppc-xive.rst | 9 |
4 files changed, 124 insertions, 22 deletions
diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 3ef50a6..bf75675 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -399,12 +399,12 @@ VM testing This test suite contains scripts that bootstrap various guest images that have necessary packages to build QEMU. The basic usage is documented in ``Makefile`` -help which is displayed with ``make vm-test``. +help which is displayed with ``make vm-help``. Quickstart ---------- -Run ``make vm-test`` to list available make targets. Invoke a specific make +Run ``make vm-help`` to list available make targets. Invoke a specific make command to run build test in an image. For example, ``make vm-build-freebsd`` will build the source tree in the FreeBSD image. The command can be executed from either the source tree or the build dir; if the former, ``./configure`` is diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index dc0ff92..5750668 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -324,19 +324,20 @@ must support changing some configuration aspects on the fly. Multiple queue support ---------------------- -Multiple queue is treated as a protocol extension, hence the slave has -to implement protocol features first. The multiple queues feature is -supported only when the protocol feature ``VHOST_USER_PROTOCOL_F_MQ`` -(bit 0) is set. +Multiple queue support allows the slave to advertise the maximum number of +queues. This is treated as a protocol extension, hence the slave has to +implement protocol features first. The multiple queues feature is supported +only when the protocol feature ``VHOST_USER_PROTOCOL_F_MQ`` (bit 0) is set. -The max number of queue pairs the slave supports can be queried with -message ``VHOST_USER_GET_QUEUE_NUM``. Master should stop when the -number of requested queues is bigger than that. +The max number of queues the slave supports can be queried with message +``VHOST_USER_GET_QUEUE_NUM``. Master should stop when the number of requested +queues is bigger than that. As all queues share one connection, the master uses a unique index for each -queue in the sent message to identify a specified queue. One queue pair -is enabled initially. More queues are enabled dynamically, by sending -message ``VHOST_USER_SET_VRING_ENABLE``. +queue in the sent message to identify a specified queue. + +The master enables queues by sending message ``VHOST_USER_SET_VRING_ENABLE``. +vhost-user-net has historically automatically enabled the first queue pair. Migration --------- diff --git a/docs/specs/ppc-spapr-xive.rst b/docs/specs/ppc-spapr-xive.rst index 539ce7c..6159bc6 100644 --- a/docs/specs/ppc-spapr-xive.rst +++ b/docs/specs/ppc-spapr-xive.rst @@ -34,19 +34,118 @@ CAS Negotiation --------------- QEMU advertises the supported interrupt modes in the device tree -property "ibm,arch-vec-5-platform-support" in byte 23 and the OS -Selection for XIVE is indicated in the "ibm,architecture-vec-5" +property ``ibm,arch-vec-5-platform-support`` in byte 23 and the OS +Selection for XIVE is indicated in the ``ibm,architecture-vec-5`` property byte 23. The interrupt modes supported by the machine depend on the CPU type (POWER9 is required for XIVE) but also on the machine property ``ic-mode`` which can be set on the command line. It can take the -following values: ``xics``, ``xive``, ``dual`` and currently ``xics`` -is the default but it may change in the future. +following values: ``xics``, ``xive``, and ``dual`` which is the +default mode. ``dual`` means that both modes XICS **and** XIVE are +supported and if the guest OS supports XIVE, this mode will be +selected. The choosen interrupt mode is activated after a reconfiguration done in a machine reset. +KVM negotiation +--------------- + +When the guest starts under KVM, the capabilities of the host kernel +and QEMU are also negotiated. Depending on the version of the host +kernel, KVM will advertise the XIVE capability to QEMU or not. + +Nevertheless, the available interrupt modes in the machine should not +depend on the XIVE KVM capability of the host. On older kernels +without XIVE KVM support, QEMU will use the emulated XIVE device as a +fallback and on newer kernels (>=5.2), the KVM XIVE device. + +As a final refinement, the user can also switch the use of the KVM +device with the machine option ``kernel_irqchip``. + + +XIVE support in KVM +~~~~~~~~~~~~~~~~~~~ + +For guest OSes supporting XIVE, the resulting interrupt modes on host +kernels with XIVE KVM support are the following: + +============== ============= ============= ================ +ic-mode kernel_irqchip +-------------- ---------------------------------------------- +/ allowed off on + (default) +============== ============= ============= ================ +dual (default) XIVE KVM XIVE emul. XIVE KVM +xive XIVE KVM XIVE emul. XIVE KVM +xics XICS KVM XICS emul. XICS KVM +============== ============= ============= ================ + +For legacy guest OSes without XIVE support, the resulting interrupt +modes are the following: + +============== ============= ============= ================ +ic-mode kernel_irqchip +-------------- ---------------------------------------------- +/ allowed off on + (default) +============== ============= ============= ================ +dual (default) XICS KVM XICS emul. XICS KVM +xive QEMU error(3) QEMU error(3) QEMU error(3) +xics XICS KVM XICS emul. XICS KVM +============== ============= ============= ================ + +(3) QEMU fails at CAS with ``Guest requested unavailable interrupt + mode (XICS), either don't set the ic-mode machine property or try + ic-mode=xics or ic-mode=dual`` + + +No XIVE support in KVM +~~~~~~~~~~~~~~~~~~~~~~ + +For guest OSes supporting XIVE, the resulting interrupt modes on host +kernels without XIVE KVM support are the following: + +============== ============= ============= ================ +ic-mode kernel_irqchip +-------------- ---------------------------------------------- +/ allowed off on + (default) +============== ============= ============= ================ +dual (default) XIVE emul.(1) XIVE emul. QEMU error (2) +xive XIVE emul.(1) XIVE emul. QEMU error (2) +xics XICS KVM XICS emul. XICS KVM +============== ============= ============= ================ + + +(1) QEMU warns with ``warning: kernel_irqchip requested but unavailable: + IRQ_XIVE capability must be present for KVM`` +(2) QEMU fails with ``kernel_irqchip requested but unavailable: + IRQ_XIVE capability must be present for KVM`` + + +For legacy guest OSes without XIVE support, the resulting interrupt +modes are the following: + +============== ============= ============= ================ +ic-mode kernel_irqchip +-------------- ---------------------------------------------- +/ allowed off on + (default) +============== ============= ============= ================ +dual (default) QEMU error(4) XICS emul. QEMU error(4) +xive QEMU error(3) QEMU error(3) QEMU error(3) +xics XICS KVM XICS emul. XICS KVM +============== ============= ============= ================ + +(3) QEMU fails at CAS with ``Guest requested unavailable interrupt + mode (XICS), either don't set the ic-mode machine property or try + ic-mode=xics or ic-mode=dual`` +(4) QEMU/KVM incompatibility due to device destruction in reset. QEMU fails + with ``KVM is too old to support ic-mode=dual,kernel-irqchip=on`` + + XIVE Device tree properties --------------------------- @@ -92,10 +191,11 @@ for both interrupt mode. The different ranges are defined as follow : - ``0x0000 .. 0x0FFF`` 4K CPU IPIs (only used under XIVE) - ``0x1000 .. 0x1000`` 1 EPOW - ``0x1001 .. 0x1001`` 1 HOTPLUG +- ``0x1002 .. 0x10FF`` unused - ``0x1100 .. 0x11FF`` 256 VIO devices -- ``0x1200 .. 0x127F`` 32 PHBs devices +- ``0x1200 .. 0x127F`` 32x4 LSIs for PHB devices - ``0x1280 .. 0x12FF`` unused -- ``0x1300 .. 0x1FFF`` PHB MSIs +- ``0x1300 .. 0x1FFF`` PHB MSIs (dynamically allocated) Monitoring XIVE --------------- diff --git a/docs/specs/ppc-xive.rst b/docs/specs/ppc-xive.rst index b997dc0..148d57e 100644 --- a/docs/specs/ppc-xive.rst +++ b/docs/specs/ppc-xive.rst @@ -20,10 +20,11 @@ The XIVE IC is composed of three sub-engines, each taking care of a processing layer of external interrupts: - Interrupt Virtualization Source Engine (IVSE), or Source Controller - (SC). These are found in PCI PHBs, in the PSI host bridge - controller, but also inside the main controller for the core IPIs - and other sub-chips (NX, CAP, NPU) of the chip/processor. They are - configured to feed the IVRE with events. + (SC). These are found in PCI PHBs, in the Processor Service + Interface (PSI) host bridge Controller, but also inside the main + controller for the core IPIs and other sub-chips (NX, CAP, NPU) of + the chip/processor. They are configured to feed the IVRE with + events. - Interrupt Virtualization Routing Engine (IVRE) or Virtualization Controller (VC). It handles event coalescing and perform interrupt routing by matching an event source number with an Event |