POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1)
==========================================================

Device types supported:
  KVM_DEV_TYPE_XIVE     POWER9 XIVE Interrupt Controller generation 1

This device acts as a VM interrupt controller. It provides the KVM
interface to configure the interrupt sources of a VM in the underlying
POWER9 XIVE interrupt controller.

Only one XIVE instance may be instantiated. A guest XIVE device
requires a POWER9 host and the guest OS should have support for the
XIVE native exploitation interrupt mode. If not, it should run using
the legacy interrupt mode, referred as XICS (POWER7/8).

* Groups:

  1. KVM_DEV_XIVE_GRP_CTRL
  Provides global controls on the device
  Attributes:
    1.1 KVM_DEV_XIVE_RESET (write only)
    Resets the interrupt controller configuration for sources and event
    queues. To be used by kexec and kdump.
    Errors: none

  2. KVM_DEV_XIVE_GRP_SOURCE (write only)
  Initializes a new source in the XIVE device and mask it.
  Attributes:
    Interrupt source number  (64-bit)
  The kvm_device_attr.addr points to a __u64 value:
  bits:     | 63   ....  2 |   1   |   0
  values:   |    unused    | level | type
  - type:  0:MSI 1:LSI
  - level: assertion level in case of an LSI.
  Errors:
    -E2BIG:  Interrupt source number is out of range
    -ENOMEM: Could not create a new source block
    -EFAULT: Invalid user pointer for attr->addr.
    -ENXIO:  Could not allocate underlying HW interrupt

  3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only)
  Configures source targeting
  Attributes:
    Interrupt source number  (64-bit)
  The kvm_device_attr.addr points to a __u64 value:
  bits:     | 63   ....  33 |  32  | 31 .. 3 |  2 .. 0
  values:   |    eisn       | mask |  server | priority
  - priority: 0-7 interrupt priority level
  - server: CPU number chosen to handle the interrupt
  - mask: mask flag (unused)
  - eisn: Effective Interrupt Source Number
  Errors:
    -ENOENT: Unknown source number
    -EINVAL: Not initialized source number
    -EINVAL: Invalid priority
    -EINVAL: Invalid CPU number.
    -EFAULT: Invalid user pointer for attr->addr.
    -ENXIO:  CPU event queues not configured or configuration of the
             underlying HW interrupt failed
    -EBUSY:  No CPU available to serve interrupt

  4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write)
  Configures an event queue of a CPU
  Attributes:
    EQ descriptor identifier (64-bit)
  The EQ descriptor identifier is a tuple (server, priority) :
  bits:     | 63   ....  32 | 31 .. 3 |  2 .. 0
  values:   |    unused     |  server | priority
  The kvm_device_attr.addr points to :
    struct kvm_ppc_xive_eq {
	__u32 flags;
	__u32 qshift;
	__u64 qaddr;
	__u32 qtoggle;
	__u32 qindex;
	__u8  pad[40];
    };
  - flags: queue flags
    KVM_XIVE_EQ_ALWAYS_NOTIFY (required)
	forces notification without using the coalescing mechanism
	provided by the XIVE END ESBs.
  - qshift: queue size (power of 2)
  - qaddr: real address of queue
  - qtoggle: current queue toggle bit
  - qindex: current queue index
  - pad: reserved for future use
  Errors:
    -ENOENT: Invalid CPU number
    -EINVAL: Invalid priority
    -EINVAL: Invalid flags
    -EINVAL: Invalid queue size
    -EINVAL: Invalid queue address
    -EFAULT: Invalid user pointer for attr->addr.
    -EIO:    Configuration of the underlying HW failed

  5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only)
  Synchronize the source to flush event notifications
  Attributes:
    Interrupt source number  (64-bit)
  Errors:
    -ENOENT: Unknown source number
    -EINVAL: Not initialized source number