docs/specs/ppc-spapr-xive.rst

4 The POWER9 processor comes with a new interrupt controller
7 virtualization features which enables the HW to deliver interrupts
15   the hypervisor provides identical interfaces and similar
16   functionality to PAPR+ Version 2.7.  This is the default mode
22   the hypervisor provides new interfaces to manage the XIVE control
26 Which interrupt modes can be used by the machine is negotiated with
27 the guest O/S during the Client Architecture Support negotiation
28 sequence. The two modes are mutually exclusive.
30 Both interrupt mode share the same IRQ number space. See below for the
36 QEMU advertises the supported interrupt modes in the device tree
37 property ``ibm,arch-vec-5-platform-support`` in byte 23 and the OS
38 Selection for XIVE is indicated in the ``ibm,architecture-vec-5``
41 The interrupt modes supported by the machine depend on the CPU type
42 (POWER9 is required for XIVE) but also on the machine property
43 ``ic-mode`` which can be set on the command line. It can take the
44 following values: ``xics``, ``xive``, and ``dual`` which is the
46 supported and if the guest OS supports XIVE, this mode will be
49 The chosen interrupt mode is activated after a reconfiguration done
55 When the guest starts under KVM, the capabilities of the host kernel
56 and QEMU are also negotiated. Depending on the version of the host
57 kernel, KVM will advertise the XIVE capability to QEMU or not.
59 Nevertheless, the available interrupt modes in the machine should not
60 depend on the XIVE KVM capability of the host. On older kernels
61 without XIVE KVM support, QEMU will use the emulated XIVE device as a
62 fallback and on newer kernels (>=5.2), the KVM XIVE device.
65 VMs running under a L1 hypervisor (KVM on pSeries). In that case, the
66 hypervisor will not advertise the KVM capability and QEMU will use the
69 As a final refinement, the user can also switch the use of the KVM
70 device with the machine option ``kernel_irqchip``.
76 For guest OSes supporting XIVE, the resulting interrupt modes on host
77 kernels with XIVE KVM support are the following:
90 For legacy guest OSes without XIVE support, the resulting interrupt
91 modes are the following:
105     mode (XICS), either don't set the ic-mode machine property or try
112 For guest OSes supporting XIVE, the resulting interrupt modes on host
113 kernels without XIVE KVM support are the following:
136 For legacy guest OSes without XIVE support, the resulting interrupt
137 modes are the following:
151     mode (XICS), either don't set the ic-mode machine property or try
160 The properties for the PAPR interrupt controller node when the *XIVE
173   contains the base address and size of the thread interrupt
174   managnement areas (TIMA), for the User level and for the Guest OS
175   level. Only the Guest OS level is taken into account today.
179   the size of the event queues. One cell per size supported, contains
184   the IRQ interrupt number ranges assigned to the guest for the IPIs.
186 The root node also exports :
190   contains a list of priorities that the hypervisor has reserved for
196 IRQ Number space of the ``pseries`` machine is 8K wide and is the same
197 for both interrupt mode. The different ranges are defined as follow :
211 The state of the XIVE interrupt controller can be queried through the
212 monitor commands ``info pic``. The output comes in two parts.
214 First, the state of the thread interrupt context registers is dumped
227 In the case of a ``pseries`` machine, QEMU acts as the hypervisor and only
228 the O/S and USER register rings make sense. ``W2`` contains the vCPU CAM
229 line which is set to the VP identifier.
231 Then comes the routing information which aggregates the EAS and the
258 The source information and configuration:
260 - The ``LISN`` column outputs the interrupt number of the source in
262 - The ``PQ`` column reflects the state of the PQ bits of the source :
269   a ``M`` indicates that source is *MASKED* at the EAS level,
271 The targeting configuration :
273 - The ``EISN`` column is the event data that will be queued in the event
274   queue of the O/S.
275 - The ``CPU/PRIO`` column is the tuple defining the CPU number and
276   priority queue serving the source.
277 - The ``EQ`` column outputs :
279   - the current index of the event queue/ the max number of entries
280   - the O/S event queue address
281   - the toggle bit
282   - the last entries that were pushed in the event queue.