0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================================
0004 FLIC (floating interrupt controller)
0005 ====================================
0006
0007 FLIC handles floating (non per-cpu) interrupts, i.e. I/O, service and some
0008 machine check interruptions. All interrupts are stored in a per-vm list of
0009 pending interrupts. FLIC performs operations on this list.
0010
0011 Only one FLIC instance may be instantiated.
0012
0013 FLIC provides support to
0014 - add interrupts (KVM_DEV_FLIC_ENQUEUE)
0015 - inspect currently pending interrupts (KVM_FLIC_GET_ALL_IRQS)
0016 - purge all pending floating interrupts (KVM_DEV_FLIC_CLEAR_IRQS)
0017 - purge one pending floating I/O interrupt (KVM_DEV_FLIC_CLEAR_IO_IRQ)
0018 - enable/disable for the guest transparent async page faults
0019 - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*)
0020 - modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM)
0021 - inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT)
0022 - get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL)
0023
0024 Groups:
0025 KVM_DEV_FLIC_ENQUEUE
0026 Passes a buffer and length into the kernel which are then injected into
0027 the list of pending interrupts.
0028 attr->addr contains the pointer to the buffer and attr->attr contains
0029 the length of the buffer.
0030 The format of the data structure kvm_s390_irq as it is copied from userspace
0031 is defined in usr/include/linux/kvm.h.
0032
0033 KVM_DEV_FLIC_GET_ALL_IRQS
0034 Copies all floating interrupts into a buffer provided by userspace.
0035 When the buffer is too small it returns -ENOMEM, which is the indication
0036 for userspace to try again with a bigger buffer.
0037
0038 -ENOBUFS is returned when the allocation of a kernelspace buffer has
0039 failed.
0040
0041 -EFAULT is returned when copying data to userspace failed.
0042 All interrupts remain pending, i.e. are not deleted from the list of
0043 currently pending interrupts.
0044 attr->addr contains the userspace address of the buffer into which all
0045 interrupt data will be copied.
0046 attr->attr contains the size of the buffer in bytes.
0047
0048 KVM_DEV_FLIC_CLEAR_IRQS
0049 Simply deletes all elements from the list of currently pending floating
0050 interrupts. No interrupts are injected into the guest.
0051
0052 KVM_DEV_FLIC_CLEAR_IO_IRQ
0053 Deletes one (if any) I/O interrupt for a subchannel identified by the
0054 subsystem identification word passed via the buffer specified by
0055 attr->addr (address) and attr->attr (length).
0056
0057 KVM_DEV_FLIC_APF_ENABLE
0058 Enables async page faults for the guest. So in case of a major page fault
0059 the host is allowed to handle this async and continues the guest.
0060
0061 KVM_DEV_FLIC_APF_DISABLE_WAIT
0062 Disables async page faults for the guest and waits until already pending
0063 async page faults are done. This is necessary to trigger a completion interrupt
0064 for every init interrupt before migrating the interrupt list.
0065
0066 KVM_DEV_FLIC_ADAPTER_REGISTER
0067 Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
0068 describing the adapter to register::
0069
0070 struct kvm_s390_io_adapter {
0071 __u32 id;
0072 __u8 isc;
0073 __u8 maskable;
0074 __u8 swap;
0075 __u8 flags;
0076 };
0077
0078 id contains the unique id for the adapter, isc the I/O interruption subclass
0079 to use, maskable whether this adapter may be masked (interrupts turned off),
0080 swap whether the indicators need to be byte swapped, and flags contains
0081 further characteristics of the adapter.
0082
0083 Currently defined values for 'flags' are:
0084
0085 - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS
0086 (adapter-interrupt-suppression) facility. This flag only has an effect if
0087 the AIS capability is enabled.
0088
0089 Unknown flag values are ignored.
0090
0091
0092 KVM_DEV_FLIC_ADAPTER_MODIFY
0093 Modifies attributes of an existing I/O adapter interrupt source. Takes
0094 a kvm_s390_io_adapter_req specifying the adapter and the operation::
0095
0096 struct kvm_s390_io_adapter_req {
0097 __u32 id;
0098 __u8 type;
0099 __u8 mask;
0100 __u16 pad0;
0101 __u64 addr;
0102 };
0103
0104 id specifies the adapter and type the operation. The supported operations
0105 are:
0106
0107 KVM_S390_IO_ADAPTER_MASK
0108 mask or unmask the adapter, as specified in mask
0109
0110 KVM_S390_IO_ADAPTER_MAP
0111 This is now a no-op. The mapping is purely done by the irq route.
0112 KVM_S390_IO_ADAPTER_UNMAP
0113 This is now a no-op. The mapping is purely done by the irq route.
0114
0115 KVM_DEV_FLIC_AISM
0116 modify the adapter-interruption-suppression mode for a given isc if the
0117 AIS capability is enabled. Takes a kvm_s390_ais_req describing::
0118
0119 struct kvm_s390_ais_req {
0120 __u8 isc;
0121 __u16 mode;
0122 };
0123
0124 isc contains the target I/O interruption subclass, mode the target
0125 adapter-interruption-suppression mode. The following modes are
0126 currently supported:
0127
0128 - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection
0129 is always allowed;
0130 - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq
0131 injection is only allowed once and the following adapter interrupts
0132 will be suppressed until the mode is set again to ALL-Interruptions
0133 or SINGLE-Interruption mode.
0134
0135 KVM_DEV_FLIC_AIRQ_INJECT
0136 Inject adapter interrupts on a specified adapter.
0137 attr->attr contains the unique id for the adapter, which allows for
0138 adapter-specific checks and actions.
0139 For adapters subject to AIS, handle the airq injection suppression for
0140 an isc according to the adapter-interruption-suppression mode on condition
0141 that the AIS capability is enabled.
0142
0143 KVM_DEV_FLIC_AISM_ALL
0144 Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes
0145 a kvm_s390_ais_all describing::
0146
0147 struct kvm_s390_ais_all {
0148 __u8 simm; /* Single-Interruption-Mode mask */
0149 __u8 nimm; /* No-Interruption-Mode mask *
0150 };
0151
0152 simm contains Single-Interruption-Mode mask for all ISCs, nimm contains
0153 No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds
0154 to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and
0155 nimm bit presents AIS mode for a ISC.
0156
0157 KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION.
0158
0159 Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on
0160 FLIC with an unknown group or attribute gives the error code EINVAL (instead of
0161 ENXIO, as specified in the API documentation). It is not possible to conclude
0162 that a FLIC operation is unavailable based on the error code resulting from a
0163 usage attempt.
0164
0165 .. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a
0166 zero schid is specified.
