docs/specs/ppc-spapr-xive.rst

4 The POWER9 processor comes with a new interrupt controller
5 architecture, called XIVE as "eXternal Interrupt Virtualization
6 Engine". It supports a larger number of interrupt sources and offers
11 processors can run under two interrupt modes:
13 - *Legacy Compatibility Mode*
20 - *XIVE native exploitation mode*
23   structures, and provides direct control for interrupt management
26 Which interrupt modes can be used by the machine is negotiated with
30 Both interrupt mode share the same IRQ number space. See below for the
34 ---------------
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
43 ``ic-mode`` which can be set on the command line. It can take the
49 The chosen interrupt mode is activated after a reconfiguration done
53 ---------------
59 Nevertheless, the available interrupt modes in the machine should not
76 For guest OSes supporting XIVE, the resulting interrupt modes on host
80 ic-mode                            kernel_irqchip
81 --------------  ----------------------------------------------
90 For legacy guest OSes without XIVE support, the resulting interrupt
94 ic-mode                            kernel_irqchip
95 --------------  ----------------------------------------------
104 (3) QEMU fails at CAS with ``Guest requested unavailable interrupt
105     mode (XICS), either don't set the ic-mode machine property or try
106     ic-mode=xics or ic-mode=dual``
112 For guest OSes supporting XIVE, the resulting interrupt modes on host
116 ic-mode                            kernel_irqchip
117 --------------  ----------------------------------------------
131     with ``KVM is incompatible with ic-mode=dual,kernel-irqchip=on``
136 For legacy guest OSes without XIVE support, the resulting interrupt
140 ic-mode                            kernel_irqchip
141 --------------  ----------------------------------------------
150 (3) QEMU fails at CAS with ``Guest requested unavailable interrupt
151     mode (XICS), either don't set the ic-mode machine property or try
152     ic-mode=xics or ic-mode=dual``
154     with ``KVM is incompatible with ic-mode=dual,kernel-irqchip=on``
158 ---------------------------
160 The properties for the PAPR interrupt controller node when the *XIVE
163 - ``device_type``
165   value should be "power-ivpe".
167 - ``compatible``
169   value should be "ibm,power-ivpe".
171 - ``reg``
173   contains the base address and size of the thread interrupt
177 - ``ibm,xive-eq-sizes``
182 - ``ibm,xive-lisn-ranges``
184   the IRQ interrupt number ranges assigned to the guest for the IPIs.
188 - ``ibm,plat-res-int-priorities``
194 ----------------
197 for both interrupt mode. The different ranges are defined as follow :
199 - ``0x0000 .. 0x0FFF`` 4K CPU IPIs (only used under XIVE)
200 - ``0x1000 .. 0x1000`` 1 EPOW
201 - ``0x1001 .. 0x1001`` 1 HOTPLUG
202 - ``0x1002 .. 0x10FF`` unused
203 - ``0x1100 .. 0x11FF`` 256 VIO devices
204 - ``0x1200 .. 0x127F`` 32x4 LSIs for PHB devices
205 - ``0x1280 .. 0x12FF`` unused
206 - ``0x1300 .. 0x1FFF`` PHB MSIs (dynamically allocated)
209 ---------------
211 The state of the XIVE interrupt controller can be queried through the
214 First, the state of the thread interrupt context registers is dumped
215 for each CPU :
220    CPU[0000]:   QW   NSR CPPR IPB LSMFB ACK# INC AGE PIPR  W2
221    CPU[0000]: USER    00   00  00    00   00  00  00   00  00000000
222    CPU[0000]:   OS    00   ff  00    00   ff  00  ff   ff  80000400
223    CPU[0000]: POOL    00   00  00    00   00  00  00   00  00000000
224    CPU[0000]: PHYS    00   00  00    00   00  00  00   ff  00000000
237    LISN         PQ    EISN     CPU/PRIO EQ
238    00000000 MSI --    00000010   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
239    00000001 MSI --    00000010   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
240    00000002 MSI --    00000010   2/6    220/16384 @1fc2f0000 ^1 [ 80000010 ... ]
241    00000003 MSI --    00000010   3/6    201/16384 @1fc390000 ^1 [ 80000010 ... ]
242    00000004 MSI -Q  M 00000000
243    00000005 MSI -Q  M 00000000
244    00000006 MSI -Q  M 00000000
245    00000007 MSI -Q  M 00000000
246    00001000 MSI --    00000012   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
247    00001001 MSI --    00000013   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
248    00001100 MSI --    00000100   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
249    00001101 MSI -Q  M 00000000
250    00001200 LSI -Q  M 00000000
251    00001201 LSI -Q  M 00000000
252    00001202 LSI -Q  M 00000000
253    00001203 LSI -Q  M 00000000
254    00001300 MSI --    00000102   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
255    00001301 MSI --    00000103   2/6    220/16384 @1fc2f0000 ^1 [ 80000010 ... ]
256    00001302 MSI --    00000104   3/6    201/16384 @1fc390000 ^1 [ 80000010 ... ]
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 :
264   - ``--`` source is ready to take events
265   - ``P-`` an event was sent and an EOI is PENDING
266   - ``PQ`` an event was QUEUED
267   - ``-Q`` source is OFF
273 - The ``EISN`` column is the event data that will be queued in the event
275 - The ``CPU/PRIO`` column is the tuple defining the CPU number and
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.