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 - enable/disable for the guest transparent async page faults
  15 - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*)
  16
  17 Groups:
  18   KVM_DEV_FLIC_ENQUEUE
  19     Passes a buffer and length into the kernel which are then injected into
  20     the list of pending interrupts.
  21     attr->addr contains the pointer to the buffer and attr->attr contains
  22     the length of the buffer.
  23     The format of the data structure kvm_s390_irq as it is copied from userspace
  24     is defined in usr/include/linux/kvm.h.
  25
  26   KVM_DEV_FLIC_GET_ALL_IRQS
  27     Copies all floating interrupts into a buffer provided by userspace.
  28     When the buffer is too small it returns -ENOMEM, which is the indication
  29     for userspace to try again with a bigger buffer.
  30     -ENOBUFS is returned when the allocation of a kernelspace buffer has
  31     failed.
  32     -EFAULT is returned when copying data to userspace failed.
  33     All interrupts remain pending, i.e. are not deleted from the list of
  34     currently pending interrupts.
  35     attr->addr contains the userspace address of the buffer into which all
  36     interrupt data will be copied.
  37     attr->attr contains the size of the buffer in bytes.
  38
  39   KVM_DEV_FLIC_CLEAR_IRQS
  40     Simply deletes all elements from the list of currently pending floating
  41     interrupts.  No interrupts are injected into the guest.
  42
  43   KVM_DEV_FLIC_APF_ENABLE
  44     Enables async page faults for the guest. So in case of a major page fault
  45     the host is allowed to handle this async and continues the guest.
  46
  47   KVM_DEV_FLIC_APF_DISABLE_WAIT
  48     Disables async page faults for the guest and waits until already pending
  49     async page faults are done. This is necessary to trigger a completion interrupt
  50     for every init interrupt before migrating the interrupt list.
  51
  52   KVM_DEV_FLIC_ADAPTER_REGISTER
  53     Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
  54     describing the adapter to register:
  55
  56 struct kvm_s390_io_adapter {
  57         __u32 id;
  58         __u8 isc;
  59         __u8 maskable;
  60         __u8 swap;
  61         __u8 pad;
  62 };
  63
  64    id contains the unique id for the adapter, isc the I/O interruption subclass
  65    to use, maskable whether this adapter may be masked (interrupts turned off)
  66    and swap whether the indicators need to be byte swapped.
  67
  68
  69   KVM_DEV_FLIC_ADAPTER_MODIFY
  70     Modifies attributes of an existing I/O adapter interrupt source. Takes
  71     a kvm_s390_io_adapter_req specifiying the adapter and the operation:
  72
  73 struct kvm_s390_io_adapter_req {
  74         __u32 id;
  75         __u8 type;
  76         __u8 mask;
  77         __u16 pad0;
  78         __u64 addr;
  79 };
  80
  81     id specifies the adapter and type the operation. The supported operations
  82     are:
  83
  84     KVM_S390_IO_ADAPTER_MASK
  85       mask or unmask the adapter, as specified in mask
  86
  87     KVM_S390_IO_ADAPTER_MAP
  88       perform a gmap translation for the guest address provided in addr,
  89       pin a userspace page for the translated address and add it to the
  90       list of mappings
  91
  92     KVM_S390_IO_ADAPTER_UNMAP
  93       release a userspace page for the translated address specified in addr
  94       from the list of mappings