1.. SPDX-License-Identifier: GPL-2.0 2 3==================================== 4FLIC (floating interrupt controller) 5==================================== 6 7FLIC handles floating (non per-cpu) interrupts, i.e. I/O, service and some 8machine check interruptions. All interrupts are stored in a per-vm list of 9pending interrupts. FLIC performs operations on this list. 10 11Only one FLIC instance may be instantiated. 12 13FLIC 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 24Groups: 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 163Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on 164FLIC with an unknown group or attribute gives the error code EINVAL (instead of 165ENXIO, as specified in the API documentation). It is not possible to conclude 166that a FLIC operation is unavailable based on the error code resulting from a 167usage attempt. 168 169.. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a 170 zero schid is specified. 171