Documentation/virt/kvm/devices/s390_flic.txt

   1 FLIC (floating interrupt controller)
   2 ====================================
   3
   4 FLIC handles floating (non per-cpu) interrupts, i.e. I/O, service and some
   5 machine check interruptions. All interrupts are stored in a per-vm list of
   6 pending interrupts. FLIC performs operations on this list.
   7
   8 Only one FLIC instance may be instantiated.
   9
  10 FLIC provides support to
  11 - add interrupts (KVM_DEV_FLIC_ENQUEUE)
  12 - inspect currently pending interrupts (KVM_FLIC_GET_ALL_IRQS)
  13 - purge all pending floating interrupts (KVM_DEV_FLIC_CLEAR_IRQS)
  14 - purge one pending floating I/O interrupt (KVM_DEV_FLIC_CLEAR_IO_IRQ)
  15 - enable/disable for the guest transparent async page faults
  16 - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*)
  17 - modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM)
  18 - inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT)
  19 - get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL)
  20
  21 Groups:
  22   KVM_DEV_FLIC_ENQUEUE
  23     Passes a buffer and length into the kernel which are then injected into
  24     the list of pending interrupts.
  25     attr->addr contains the pointer to the buffer and attr->attr contains
  26     the length of the buffer.
  27     The format of the data structure kvm_s390_irq as it is copied from userspace
  28     is defined in usr/include/linux/kvm.h.
  29
  30   KVM_DEV_FLIC_GET_ALL_IRQS
  31     Copies all floating interrupts into a buffer provided by userspace.
  32     When the buffer is too small it returns -ENOMEM, which is the indication
  33     for userspace to try again with a bigger buffer.
  34     -ENOBUFS is returned when the allocation of a kernelspace buffer has
  35     failed.
  36     -EFAULT is returned when copying data to userspace failed.
  37     All interrupts remain pending, i.e. are not deleted from the list of
  38     currently pending interrupts.
  39     attr->addr contains the userspace address of the buffer into which all
  40     interrupt data will be copied.
  41     attr->attr contains the size of the buffer in bytes.
  42
  43   KVM_DEV_FLIC_CLEAR_IRQS
  44     Simply deletes all elements from the list of currently pending floating
  45     interrupts.  No interrupts are injected into the guest.
  46
  47   KVM_DEV_FLIC_CLEAR_IO_IRQ
  48     Deletes one (if any) I/O interrupt for a subchannel identified by the
  49     subsystem identification word passed via the buffer specified by
  50     attr->addr (address) and attr->attr (length).
  51
  52   KVM_DEV_FLIC_APF_ENABLE
  53     Enables async page faults for the guest. So in case of a major page fault
  54     the host is allowed to handle this async and continues the guest.
  55
  56   KVM_DEV_FLIC_APF_DISABLE_WAIT
  57     Disables async page faults for the guest and waits until already pending
  58     async page faults are done. This is necessary to trigger a completion interrupt
  59     for every init interrupt before migrating the interrupt list.
  60
  61   KVM_DEV_FLIC_ADAPTER_REGISTER
  62     Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
  63     describing the adapter to register:
  64
  65 struct kvm_s390_io_adapter {
  66         __u32 id;
  67         __u8 isc;
  68         __u8 maskable;
  69         __u8 swap;
  70         __u8 flags;
  71 };
  72
  73    id contains the unique id for the adapter, isc the I/O interruption subclass
  74    to use, maskable whether this adapter may be masked (interrupts turned off),
  75    swap whether the indicators need to be byte swapped, and flags contains
  76    further characteristics of the adapter.
  77    Currently defined values for 'flags' are:
  78    - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS
  79      (adapter-interrupt-suppression) facility. This flag only has an effect if
  80      the AIS capability is enabled.
  81    Unknown flag values are ignored.
  82
  83
  84   KVM_DEV_FLIC_ADAPTER_MODIFY
  85     Modifies attributes of an existing I/O adapter interrupt source. Takes
  86     a kvm_s390_io_adapter_req specifying the adapter and the operation:
  87
  88 struct kvm_s390_io_adapter_req {
  89         __u32 id;
  90         __u8 type;
  91         __u8 mask;
  92         __u16 pad0;
  93         __u64 addr;
  94 };
  95
  96     id specifies the adapter and type the operation. The supported operations
  97     are:
  98
  99     KVM_S390_IO_ADAPTER_MASK
 100       mask or unmask the adapter, as specified in mask
 101
 102     KVM_S390_IO_ADAPTER_MAP
 103       perform a gmap translation for the guest address provided in addr,
 104       pin a userspace page for the translated address and add it to the
 105       list of mappings
 106       Note: A new mapping will be created unconditionally; therefore,
 107             the calling code should avoid making duplicate mappings.
 108
 109     KVM_S390_IO_ADAPTER_UNMAP
 110       release a userspace page for the translated address specified in addr
 111       from the list of mappings
 112
 113   KVM_DEV_FLIC_AISM
 114     modify the adapter-interruption-suppression mode for a given isc if the
 115     AIS capability is enabled. Takes a kvm_s390_ais_req describing:
 116
 117 struct kvm_s390_ais_req {
 118         __u8 isc;
 119         __u16 mode;
 120 };
 121
 122     isc contains the target I/O interruption subclass, mode the target
 123     adapter-interruption-suppression mode. The following modes are
 124     currently supported:
 125     - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection
 126       is always allowed;
 127     - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq
 128       injection is only allowed once and the following adapter interrupts
 129       will be suppressed until the mode is set again to ALL-Interruptions
 130       or SINGLE-Interruption mode.
 131
 132   KVM_DEV_FLIC_AIRQ_INJECT
 133     Inject adapter interrupts on a specified adapter.
 134     attr->attr contains the unique id for the adapter, which allows for
 135     adapter-specific checks and actions.
 136     For adapters subject to AIS, handle the airq injection suppression for
 137     an isc according to the adapter-interruption-suppression mode on condition
 138     that the AIS capability is enabled.
 139
 140   KVM_DEV_FLIC_AISM_ALL
 141     Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes
 142     a kvm_s390_ais_all describing:
 143
 144 struct kvm_s390_ais_all {
 145        __u8 simm; /* Single-Interruption-Mode mask */
 146        __u8 nimm; /* No-Interruption-Mode mask *
 147 };
 148
 149     simm contains Single-Interruption-Mode mask for all ISCs, nimm contains
 150     No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds
 151     to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and
 152     nimm bit presents AIS mode for a ISC.
 153
 154     KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION.
 155
 156 Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on
 157 FLIC with an unknown group or attribute gives the error code EINVAL (instead of
 158 ENXIO, as specified in the API documentation). It is not possible to conclude
 159 that a FLIC operation is unavailable based on the error code resulting from a
 160 usage attempt.
 161
 162 Note: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a zero
 163 schid is specified.