Documentation/virtual/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
  18 Groups:
  19   KVM_DEV_FLIC_ENQUEUE
  20     Passes a buffer and length into the kernel which are then injected into
  21     the list of pending interrupts.
  22     attr->addr contains the pointer to the buffer and attr->attr contains
  23     the length of the buffer.
  24     The format of the data structure kvm_s390_irq as it is copied from userspace
  25     is defined in usr/include/linux/kvm.h.
  26
  27   KVM_DEV_FLIC_GET_ALL_IRQS
  28     Copies all floating interrupts into a buffer provided by userspace.
  29     When the buffer is too small it returns -ENOMEM, which is the indication
  30     for userspace to try again with a bigger buffer.
  31     -ENOBUFS is returned when the allocation of a kernelspace buffer has
  32     failed.
  33     -EFAULT is returned when copying data to userspace failed.
  34     All interrupts remain pending, i.e. are not deleted from the list of
  35     currently pending interrupts.
  36     attr->addr contains the userspace address of the buffer into which all
  37     interrupt data will be copied.
  38     attr->attr contains the size of the buffer in bytes.
  39
  40   KVM_DEV_FLIC_CLEAR_IRQS
  41     Simply deletes all elements from the list of currently pending floating
  42     interrupts.  No interrupts are injected into the guest.
  43
  44   KVM_DEV_FLIC_CLEAR_IO_IRQ
  45     Deletes one (if any) I/O interrupt for a subchannel identified by the
  46     subsystem identification word passed via the buffer specified by
  47     attr->addr (address) and attr->attr (length).
  48
  49   KVM_DEV_FLIC_APF_ENABLE
  50     Enables async page faults for the guest. So in case of a major page fault
  51     the host is allowed to handle this async and continues the guest.
  52
  53   KVM_DEV_FLIC_APF_DISABLE_WAIT
  54     Disables async page faults for the guest and waits until already pending
  55     async page faults are done. This is necessary to trigger a completion interrupt
  56     for every init interrupt before migrating the interrupt list.
  57
  58   KVM_DEV_FLIC_ADAPTER_REGISTER
  59     Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
  60     describing the adapter to register:
  61
  62 struct kvm_s390_io_adapter {
  63         __u32 id;
  64         __u8 isc;
  65         __u8 maskable;
  66         __u8 swap;
  67         __u8 pad;
  68 };
  69
  70    id contains the unique id for the adapter, isc the I/O interruption subclass
  71    to use, maskable whether this adapter may be masked (interrupts turned off)
  72    and swap whether the indicators need to be byte swapped.
  73
  74
  75   KVM_DEV_FLIC_ADAPTER_MODIFY
  76     Modifies attributes of an existing I/O adapter interrupt source. Takes
  77     a kvm_s390_io_adapter_req specifying the adapter and the operation:
  78
  79 struct kvm_s390_io_adapter_req {
  80         __u32 id;
  81         __u8 type;
  82         __u8 mask;
  83         __u16 pad0;
  84         __u64 addr;
  85 };
  86
  87     id specifies the adapter and type the operation. The supported operations
  88     are:
  89
  90     KVM_S390_IO_ADAPTER_MASK
  91       mask or unmask the adapter, as specified in mask
  92
  93     KVM_S390_IO_ADAPTER_MAP
  94       perform a gmap translation for the guest address provided in addr,
  95       pin a userspace page for the translated address and add it to the
  96       list of mappings
  97       Note: A new mapping will be created unconditionally; therefore,
  98             the calling code should avoid making duplicate mappings.
  99
 100     KVM_S390_IO_ADAPTER_UNMAP
 101       release a userspace page for the translated address specified in addr
 102       from the list of mappings
 103
 104 Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on
 105 FLIC with an unknown group or attribute gives the error code EINVAL (instead of
 106 ENXIO, as specified in the API documentation). It is not possible to conclude
 107 that a FLIC operation is unavailable based on the error code resulting from a
 108 usage attempt.