| 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 |
-EINVAL is returned when called on the FLIC of a ucontrol VM. |
| 62 |
|
| 63 |
KVM_DEV_FLIC_APF_DISABLE_WAIT |
| 64 |
Disables async page faults for the guest and waits until already pending |
| 65 |
async page faults are done. This is necessary to trigger a completion interrupt |
| 66 |
for every init interrupt before migrating the interrupt list. |
| 67 |
|
| 68 |
-EINVAL is returned when called on the FLIC of a ucontrol VM. |
| 69 |
|
| 70 |
KVM_DEV_FLIC_ADAPTER_REGISTER |
| 71 |
Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter |
| 72 |
describing the adapter to register:: |
| 73 |
|
| 74 |
struct kvm_s390_io_adapter { |
| 75 |
__u32 id; |
| 76 |
__u8 isc; |
| 77 |
__u8 maskable; |
| 78 |
__u8 swap; |
| 79 |
__u8 flags; |
| 80 |
}; |
| 81 |
|
| 82 |
id contains the unique id for the adapter, isc the I/O interruption subclass |
| 83 |
to use, maskable whether this adapter may be masked (interrupts turned off), |
| 84 |
swap whether the indicators need to be byte swapped, and flags contains |
| 85 |
further characteristics of the adapter. |
| 86 |
|
| 87 |
Currently defined values for 'flags' are: |
| 88 |
|
| 89 |
- KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS |
| 90 |
(adapter-interrupt-suppression) facility. This flag only has an effect if |
| 91 |
the AIS capability is enabled. |
| 92 |
|
| 93 |
Unknown flag values are ignored. |
| 94 |
|
| 95 |
|
| 96 |
KVM_DEV_FLIC_ADAPTER_MODIFY |
| 97 |
Modifies attributes of an existing I/O adapter interrupt source. Takes |
| 98 |
a kvm_s390_io_adapter_req specifying the adapter and the operation:: |
| 99 |
|
| 100 |
struct kvm_s390_io_adapter_req { |
| 101 |
__u32 id; |
| 102 |
__u8 type; |
| 103 |
__u8 mask; |
| 104 |
__u16 pad0; |
| 105 |
__u64 addr; |
| 106 |
}; |
| 107 |
|
| 108 |
id specifies the adapter and type the operation. The supported operations |
| 109 |
are: |
| 110 |
|
| 111 |
KVM_S390_IO_ADAPTER_MASK |
| 112 |
mask or unmask the adapter, as specified in mask |
| 113 |
|
| 114 |
KVM_S390_IO_ADAPTER_MAP |
| 115 |
This is now a no-op. The mapping is purely done by the irq route. |
| 116 |
KVM_S390_IO_ADAPTER_UNMAP |
| 117 |
This is now a no-op. The mapping is purely done by the irq route. |
| 118 |
|
| 119 |
KVM_DEV_FLIC_AISM |
| 120 |
modify the adapter-interruption-suppression mode for a given isc if the |
| 121 |
AIS capability is enabled. Takes a kvm_s390_ais_req describing:: |
| 122 |
|
| 123 |
struct kvm_s390_ais_req { |
| 124 |
__u8 isc; |
| 125 |
__u16 mode; |
| 126 |
}; |
| 127 |
|
| 128 |
isc contains the target I/O interruption subclass, mode the target |
| 129 |
adapter-interruption-suppression mode. The following modes are |
| 130 |
currently supported: |
| 131 |
|
| 132 |
- KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection |
| 133 |
is always allowed; |
| 134 |
- KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq |
| 135 |
injection is only allowed once and the following adapter interrupts |
| 136 |
will be suppressed until the mode is set again to ALL-Interruptions |
| 137 |
or SINGLE-Interruption mode. |
| 138 |
|
| 139 |
KVM_DEV_FLIC_AIRQ_INJECT |
| 140 |
Inject adapter interrupts on a specified adapter. |
| 141 |
attr->attr contains the unique id for the adapter, which allows for |
| 142 |
adapter-specific checks and actions. |
| 143 |
For adapters subject to AIS, handle the airq injection suppression for |
| 144 |
an isc according to the adapter-interruption-suppression mode on condition |
| 145 |
that the AIS capability is enabled. |
| 146 |
|
| 147 |
KVM_DEV_FLIC_AISM_ALL |
| 148 |
Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes |
| 149 |
a kvm_s390_ais_all describing:: |
| 150 |
|
| 151 |
struct kvm_s390_ais_all { |
| 152 |
__u8 simm; /* Single-Interruption-Mode mask */ |
| 153 |
__u8 nimm; /* No-Interruption-Mode mask * |
| 154 |
}; |
| 155 |
|
| 156 |
simm contains Single-Interruption-Mode mask for all ISCs, nimm contains |
| 157 |
No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds |
| 158 |
to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and |
| 159 |
nimm bit presents AIS mode for a ISC. |
| 160 |
|
| 161 |
KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION. |
| 162 |
|
| 163 |
Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on |
| 164 |
FLIC with an unknown group or attribute gives the error code EINVAL (instead of |
| 165 |
ENXIO, as specified in the API documentation). It is not possible to conclude |
| 166 |
that a FLIC operation is unavailable based on the error code resulting from a |
| 167 |
usage attempt. |
| 168 |
|
| 169 |
.. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a |
| 170 |
zero schid is specified. |