Documentation/virt/kvm/devices/xive.txt

   1 POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1)
   2 ==========================================================
   3
   4 Device types supported:
   5   KVM_DEV_TYPE_XIVE     POWER9 XIVE Interrupt Controller generation 1
   6
   7 This device acts as a VM interrupt controller. It provides the KVM
   8 interface to configure the interrupt sources of a VM in the underlying
   9 POWER9 XIVE interrupt controller.
  10
  11 Only one XIVE instance may be instantiated. A guest XIVE device
  12 requires a POWER9 host and the guest OS should have support for the
  13 XIVE native exploitation interrupt mode. If not, it should run using
  14 the legacy interrupt mode, referred as XICS (POWER7/8).
  15
  16 * Device Mappings
  17
  18   The KVM device exposes different MMIO ranges of the XIVE HW which
  19   are required for interrupt management. These are exposed to the
  20   guest in VMAs populated with a custom VM fault handler.
  21
  22   1. Thread Interrupt Management Area (TIMA)
  23
  24   Each thread has an associated Thread Interrupt Management context
  25   composed of a set of registers. These registers let the thread
  26   handle priority management and interrupt acknowledgment. The most
  27   important are :
  28
  29       - Interrupt Pending Buffer     (IPB)
  30       - Current Processor Priority   (CPPR)
  31       - Notification Source Register (NSR)
  32
  33   They are exposed to software in four different pages each proposing
  34   a view with a different privilege. The first page is for the
  35   physical thread context and the second for the hypervisor. Only the
  36   third (operating system) and the fourth (user level) are exposed the
  37   guest.
  38
  39   2. Event State Buffer (ESB)
  40
  41   Each source is associated with an Event State Buffer (ESB) with
  42   either a pair of even/odd pair of pages which provides commands to
  43   manage the source: to trigger, to EOI, to turn off the source for
  44   instance.
  45
  46   3. Device pass-through
  47
  48   When a device is passed-through into the guest, the source
  49   interrupts are from a different HW controller (PHB4) and the ESB
  50   pages exposed to the guest should accommadate this change.
  51
  52   The passthru_irq helpers, kvmppc_xive_set_mapped() and
  53   kvmppc_xive_clr_mapped() are called when the device HW irqs are
  54   mapped into or unmapped from the guest IRQ number space. The KVM
  55   device extends these helpers to clear the ESB pages of the guest IRQ
  56   number being mapped and then lets the VM fault handler repopulate.
  57   The handler will insert the ESB page corresponding to the HW
  58   interrupt of the device being passed-through or the initial IPI ESB
  59   page if the device has being removed.
  60
  61   The ESB remapping is fully transparent to the guest and the OS
  62   device driver. All handling is done within VFIO and the above
  63   helpers in KVM-PPC.
  64
  65 * Groups:
  66
  67   1. KVM_DEV_XIVE_GRP_CTRL
  68   Provides global controls on the device
  69   Attributes:
  70     1.1 KVM_DEV_XIVE_RESET (write only)
  71     Resets the interrupt controller configuration for sources and event
  72     queues. To be used by kexec and kdump.
  73     Errors: none
  74
  75     1.2 KVM_DEV_XIVE_EQ_SYNC (write only)
  76     Sync all the sources and queues and mark the EQ pages dirty. This
  77     to make sure that a consistent memory state is captured when
  78     migrating the VM.
  79     Errors: none
  80
  81     1.3 KVM_DEV_XIVE_NR_SERVERS (write only)
  82     The kvm_device_attr.addr points to a __u32 value which is the number of
  83     interrupt server numbers (ie, highest possible vcpu id plus one).
  84     Errors:
  85       -EINVAL: Value greater than KVM_MAX_VCPU_ID.
  86       -EFAULT: Invalid user pointer for attr->addr.
  87       -EBUSY:  A vCPU is already connected to the device.
  88
  89   2. KVM_DEV_XIVE_GRP_SOURCE (write only)
  90   Initializes a new source in the XIVE device and mask it.
  91   Attributes:
  92     Interrupt source number  (64-bit)
  93   The kvm_device_attr.addr points to a __u64 value:
  94   bits:     | 63   ....  2 |   1   |   0
  95   values:   |    unused    | level | type
  96   - type:  0:MSI 1:LSI
  97   - level: assertion level in case of an LSI.
  98   Errors:
  99     -E2BIG:  Interrupt source number is out of range
 100     -ENOMEM: Could not create a new source block
 101     -EFAULT: Invalid user pointer for attr->addr.
 102     -ENXIO:  Could not allocate underlying HW interrupt
 103
 104   3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only)
 105   Configures source targeting
 106   Attributes:
 107     Interrupt source number  (64-bit)
 108   The kvm_device_attr.addr points to a __u64 value:
 109   bits:     | 63   ....  33 |  32  | 31 .. 3 |  2 .. 0
 110   values:   |    eisn       | mask |  server | priority
 111   - priority: 0-7 interrupt priority level
 112   - server: CPU number chosen to handle the interrupt
 113   - mask: mask flag (unused)
 114   - eisn: Effective Interrupt Source Number
 115   Errors:
 116     -ENOENT: Unknown source number
 117     -EINVAL: Not initialized source number
 118     -EINVAL: Invalid priority
 119     -EINVAL: Invalid CPU number.
 120     -EFAULT: Invalid user pointer for attr->addr.
 121     -ENXIO:  CPU event queues not configured or configuration of the
 122              underlying HW interrupt failed
 123     -EBUSY:  No CPU available to serve interrupt
 124
 125   4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write)
 126   Configures an event queue of a CPU
 127   Attributes:
 128     EQ descriptor identifier (64-bit)
 129   The EQ descriptor identifier is a tuple (server, priority) :
 130   bits:     | 63   ....  32 | 31 .. 3 |  2 .. 0
 131   values:   |    unused     |  server | priority
 132   The kvm_device_attr.addr points to :
 133     struct kvm_ppc_xive_eq {
 134         __u32 flags;
 135         __u32 qshift;
 136         __u64 qaddr;
 137         __u32 qtoggle;
 138         __u32 qindex;
 139         __u8  pad[40];
 140     };
 141   - flags: queue flags
 142     KVM_XIVE_EQ_ALWAYS_NOTIFY (required)
 143         forces notification without using the coalescing mechanism
 144         provided by the XIVE END ESBs.
 145   - qshift: queue size (power of 2)
 146   - qaddr: real address of queue
 147   - qtoggle: current queue toggle bit
 148   - qindex: current queue index
 149   - pad: reserved for future use
 150   Errors:
 151     -ENOENT: Invalid CPU number
 152     -EINVAL: Invalid priority
 153     -EINVAL: Invalid flags
 154     -EINVAL: Invalid queue size
 155     -EINVAL: Invalid queue address
 156     -EFAULT: Invalid user pointer for attr->addr.
 157     -EIO:    Configuration of the underlying HW failed
 158
 159   5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only)
 160   Synchronize the source to flush event notifications
 161   Attributes:
 162     Interrupt source number  (64-bit)
 163   Errors:
 164     -ENOENT: Unknown source number
 165     -EINVAL: Not initialized source number
 166
 167 * VCPU state
 168
 169   The XIVE IC maintains VP interrupt state in an internal structure
 170   called the NVT. When a VP is not dispatched on a HW processor
 171   thread, this structure can be updated by HW if the VP is the target
 172   of an event notification.
 173
 174   It is important for migration to capture the cached IPB from the NVT
 175   as it synthesizes the priorities of the pending interrupts. We
 176   capture a bit more to report debug information.
 177
 178   KVM_REG_PPC_VP_STATE (2 * 64bits)
 179   bits:     |  63  ....  32  |  31  ....  0  |
 180   values:   |   TIMA word0   |   TIMA word1  |
 181   bits:     | 127       ..........       64  |
 182   values:   |            unused              |
 183
 184 * Migration:
 185
 186   Saving the state of a VM using the XIVE native exploitation mode
 187   should follow a specific sequence. When the VM is stopped :
 188
 189   1. Mask all sources (PQ=01) to stop the flow of events.
 190
 191   2. Sync the XIVE device with the KVM control KVM_DEV_XIVE_EQ_SYNC to
 192   flush any in-flight event notification and to stabilize the EQs. At
 193   this stage, the EQ pages are marked dirty to make sure they are
 194   transferred in the migration sequence.
 195
 196   3. Capture the state of the source targeting, the EQs configuration
 197   and the state of thread interrupt context registers.
 198
 199   Restore is similar :
 200
 201   1. Restore the EQ configuration. As targeting depends on it.
 202   2. Restore targeting
 203   3. Restore the thread interrupt contexts
 204   4. Restore the source states
 205   5. Let the vCPU run