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       perform a gmap translation for the guest address provided in addr,
 112       pin a userspace page for the translated address and add it to the
 113       list of mappings
 114
 115       .. note:: A new mapping will be created unconditionally; therefore,
 116                 the calling code should avoid making duplicate mappings.
 117
 118     KVM_S390_IO_ADAPTER_UNMAP
 119       release a userspace page for the translated address specified in addr
 120       from the list of mappings
 121
 122   KVM_DEV_FLIC_AISM
 123     modify the adapter-interruption-suppression mode for a given isc if the
 124     AIS capability is enabled. Takes a kvm_s390_ais_req describing::
 125
 126         struct kvm_s390_ais_req {
 127                 __u8 isc;
 128                 __u16 mode;
 129         };
 130
 131     isc contains the target I/O interruption subclass, mode the target
 132     adapter-interruption-suppression mode. The following modes are
 133     currently supported:
 134
 135     - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection
 136       is always allowed;
 137     - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq
 138       injection is only allowed once and the following adapter interrupts
 139       will be suppressed until the mode is set again to ALL-Interruptions
 140       or SINGLE-Interruption mode.
 141
 142   KVM_DEV_FLIC_AIRQ_INJECT
 143     Inject adapter interrupts on a specified adapter.
 144     attr->attr contains the unique id for the adapter, which allows for
 145     adapter-specific checks and actions.
 146     For adapters subject to AIS, handle the airq injection suppression for
 147     an isc according to the adapter-interruption-suppression mode on condition
 148     that the AIS capability is enabled.
 149
 150   KVM_DEV_FLIC_AISM_ALL
 151     Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes
 152     a kvm_s390_ais_all describing::
 153
 154         struct kvm_s390_ais_all {
 155                __u8 simm; /* Single-Interruption-Mode mask */
 156                __u8 nimm; /* No-Interruption-Mode mask *
 157         };
 158
 159     simm contains Single-Interruption-Mode mask for all ISCs, nimm contains
 160     No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds
 161     to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and
 162     nimm bit presents AIS mode for a ISC.
 163
 164     KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION.
 165
 166 Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on
 167 FLIC with an unknown group or attribute gives the error code EINVAL (instead of
 168 ENXIO, as specified in the API documentation). It is not possible to conclude
 169 that a FLIC operation is unavailable based on the error code resulting from a
 170 usage attempt.
 171
 172 .. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a
 173           zero schid is specified.