audio: deprecate -soundhw gus
[qemu/ar7.git] / docs / specs / ppc-spapr-xive.rst
blob6159bc6eed6205a3d5c6621ebc4fb71081c2b583
1 XIVE for sPAPR (pseries machines)
2 =================================
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
7 virtualization features which enables the HW to deliver interrupts
8 directly to virtual processors without hypervisor assistance.
10 A QEMU ``pseries`` machine (which is PAPR compliant) using POWER9
11 processors can run under two interrupt modes:
13 - *Legacy Compatibility Mode*
15   the hypervisor provides identical interfaces and similar
16   functionality to PAPR+ Version 2.7.  This is the default mode
18   It is also referred as *XICS* in QEMU.
20 - *XIVE native exploitation mode*
22   the hypervisor provides new interfaces to manage the XIVE control
23   structures, and provides direct control for interrupt management
24   through MMIO pages.
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
31 layout.
33 CAS Negotiation
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``
39 property byte 23.
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
45 default mode. ``dual`` means that both modes XICS **and** XIVE are
46 supported and if the guest OS supports XIVE, this mode will be
47 selected.
49 The choosen interrupt mode is activated after a reconfiguration done
50 in a machine reset.
52 KVM negotiation
53 ---------------
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.
64 As a final refinement, the user can also switch the use of the KVM
65 device with the machine option ``kernel_irqchip``.
68 XIVE support in KVM
69 ~~~~~~~~~~~~~~~~~~~
71 For guest OSes supporting XIVE, the resulting interrupt modes on host
72 kernels with XIVE KVM support are the following:
74 ==============  =============  =============  ================
75 ic-mode                            kernel_irqchip
76 --------------  ----------------------------------------------
77 /               allowed        off            on
78                 (default)
79 ==============  =============  =============  ================
80 dual (default)  XIVE KVM       XIVE emul.     XIVE KVM
81 xive            XIVE KVM       XIVE emul.     XIVE KVM
82 xics            XICS KVM       XICS emul.     XICS KVM
83 ==============  =============  =============  ================
85 For legacy guest OSes without XIVE support, the resulting interrupt
86 modes are the following:
88 ==============  =============  =============  ================
89 ic-mode                            kernel_irqchip
90 --------------  ----------------------------------------------
91 /               allowed        off            on
92                 (default)
93 ==============  =============  =============  ================
94 dual (default)  XICS KVM       XICS emul.     XICS KVM
95 xive            QEMU error(3)  QEMU error(3)  QEMU error(3)
96 xics            XICS KVM       XICS emul.     XICS KVM
97 ==============  =============  =============  ================
99 (3) QEMU fails at CAS with ``Guest requested unavailable interrupt
100     mode (XICS), either don't set the ic-mode machine property or try
101     ic-mode=xics or ic-mode=dual``
104 No XIVE support in KVM
105 ~~~~~~~~~~~~~~~~~~~~~~
107 For guest OSes supporting XIVE, the resulting interrupt modes on host
108 kernels without XIVE KVM support are the following:
110 ==============  =============  =============  ================
111 ic-mode                            kernel_irqchip
112 --------------  ----------------------------------------------
113 /               allowed        off            on
114                 (default)
115 ==============  =============  =============  ================
116 dual (default)  XIVE emul.(1)  XIVE emul.     QEMU error (2)
117 xive            XIVE emul.(1)  XIVE emul.     QEMU error (2)
118 xics            XICS KVM       XICS emul.     XICS KVM
119 ==============  =============  =============  ================
122 (1) QEMU warns with ``warning: kernel_irqchip requested but unavailable:
123     IRQ_XIVE capability must be present for KVM``
124 (2) QEMU fails with ``kernel_irqchip requested but unavailable:
125     IRQ_XIVE capability must be present for KVM``
128 For legacy guest OSes without XIVE support, the resulting interrupt
129 modes are the following:
131 ==============  =============  =============  ================
132 ic-mode                            kernel_irqchip
133 --------------  ----------------------------------------------
134 /               allowed        off            on
135                 (default)
136 ==============  =============  =============  ================
137 dual (default)  QEMU error(4)  XICS emul.     QEMU error(4)
138 xive            QEMU error(3)  QEMU error(3)  QEMU error(3)
139 xics            XICS KVM       XICS emul.     XICS KVM
140 ==============  =============  =============  ================
142 (3) QEMU fails at CAS with ``Guest requested unavailable interrupt
143     mode (XICS), either don't set the ic-mode machine property or try
144     ic-mode=xics or ic-mode=dual``
145 (4) QEMU/KVM incompatibility due to device destruction in reset. QEMU fails
146     with ``KVM is too old to support ic-mode=dual,kernel-irqchip=on``
149 XIVE Device tree properties
150 ---------------------------
152 The properties for the PAPR interrupt controller node when the *XIVE
153 native exploitation mode* is selected shoud contain:
155 - ``device_type``
157   value should be "power-ivpe".
159 - ``compatible``
161   value should be "ibm,power-ivpe".
163 - ``reg``
165   contains the base address and size of the thread interrupt
166   managnement areas (TIMA), for the User level and for the Guest OS
167   level. Only the Guest OS level is taken into account today.
169 - ``ibm,xive-eq-sizes``
171   the size of the event queues. One cell per size supported, contains
172   log2 of size, in ascending order.
174 - ``ibm,xive-lisn-ranges``
176   the IRQ interrupt number ranges assigned to the guest for the IPIs.
178 The root node also exports :
180 - ``ibm,plat-res-int-priorities``
182   contains a list of priorities that the hypervisor has reserved for
183   its own use.
185 IRQ number space
186 ----------------
188 IRQ Number space of the ``pseries`` machine is 8K wide and is the same
189 for both interrupt mode. The different ranges are defined as follow :
191 - ``0x0000 .. 0x0FFF`` 4K CPU IPIs (only used under XIVE)
192 - ``0x1000 .. 0x1000`` 1 EPOW
193 - ``0x1001 .. 0x1001`` 1 HOTPLUG
194 - ``0x1002 .. 0x10FF`` unused
195 - ``0x1100 .. 0x11FF`` 256 VIO devices
196 - ``0x1200 .. 0x127F`` 32x4 LSIs for PHB devices
197 - ``0x1280 .. 0x12FF`` unused
198 - ``0x1300 .. 0x1FFF`` PHB MSIs (dynamically allocated)
200 Monitoring XIVE
201 ---------------
203 The state of the XIVE interrupt controller can be queried through the
204 monitor commands ``info pic``. The output comes in two parts.
206 First, the state of the thread interrupt context registers is dumped
207 for each CPU :
211    (qemu) info pic
212    CPU[0000]:   QW   NSR CPPR IPB LSMFB ACK# INC AGE PIPR  W2
213    CPU[0000]: USER    00   00  00    00   00  00  00   00  00000000
214    CPU[0000]:   OS    00   ff  00    00   ff  00  ff   ff  80000400
215    CPU[0000]: POOL    00   00  00    00   00  00  00   00  00000000
216    CPU[0000]: PHYS    00   00  00    00   00  00  00   ff  00000000
217    ...
219 In the case of a ``pseries`` machine, QEMU acts as the hypervisor and only
220 the O/S and USER register rings make sense. ``W2`` contains the vCPU CAM
221 line which is set to the VP identifier.
223 Then comes the routing information which aggregates the EAS and the
224 END configuration:
228    ...
229    LISN         PQ    EISN     CPU/PRIO EQ
230    00000000 MSI --    00000010   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
231    00000001 MSI --    00000010   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
232    00000002 MSI --    00000010   2/6    220/16384 @1fc2f0000 ^1 [ 80000010 ... ]
233    00000003 MSI --    00000010   3/6    201/16384 @1fc390000 ^1 [ 80000010 ... ]
234    00000004 MSI -Q  M 00000000
235    00000005 MSI -Q  M 00000000
236    00000006 MSI -Q  M 00000000
237    00000007 MSI -Q  M 00000000
238    00001000 MSI --    00000012   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
239    00001001 MSI --    00000013   0/6    380/16384 @1fe3e0000 ^1 [ 80000010 ... ]
240    00001100 MSI --    00000100   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
241    00001101 MSI -Q  M 00000000
242    00001200 LSI -Q  M 00000000
243    00001201 LSI -Q  M 00000000
244    00001202 LSI -Q  M 00000000
245    00001203 LSI -Q  M 00000000
246    00001300 MSI --    00000102   1/6    305/16384 @1fc230000 ^1 [ 80000010 ... ]
247    00001301 MSI --    00000103   2/6    220/16384 @1fc2f0000 ^1 [ 80000010 ... ]
248    00001302 MSI --    00000104   3/6    201/16384 @1fc390000 ^1 [ 80000010 ... ]
250 The source information and configuration:
252 - The ``LISN`` column outputs the interrupt number of the source in
253   range ``[ 0x0 ... 0x1FFF ]`` and its type : ``MSI`` or ``LSI``
254 - The ``PQ`` column reflects the state of the PQ bits of the source :
256   - ``--`` source is ready to take events
257   - ``P-`` an event was sent and an EOI is PENDING
258   - ``PQ`` an event was QUEUED
259   - ``-Q`` source is OFF
261   a ``M`` indicates that source is *MASKED* at the EAS level,
263 The targeting configuration :
265 - The ``EISN`` column is the event data that will be queued in the event
266   queue of the O/S.
267 - The ``CPU/PRIO`` column is the tuple defining the CPU number and
268   priority queue serving the source.
269 - The ``EQ`` column outputs :
271   - the current index of the event queue/ the max number of entries
272   - the O/S event queue address
273   - the toggle bit
274   - the last entries that were pushed in the event queue.