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