Documentation/virt/kvm/devices/s390_flic.rst

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