Commit | Line | Data |
---|---|---|
c05c4186 JF |
1 | FLIC (floating interrupt controller) |
2 | ==================================== | |
3 | ||
4 | FLIC handles floating (non per-cpu) interrupts, i.e. I/O, service and some | |
5 | machine check interruptions. All interrupts are stored in a per-vm list of | |
6 | pending interrupts. FLIC performs operations on this list. | |
7 | ||
8 | Only one FLIC instance may be instantiated. | |
9 | ||
10 | FLIC provides support to | |
11 | - add interrupts (KVM_DEV_FLIC_ENQUEUE) | |
12 | - inspect currently pending interrupts (KVM_FLIC_GET_ALL_IRQS) | |
13 | - purge all pending floating interrupts (KVM_DEV_FLIC_CLEAR_IRQS) | |
6d28f789 | 14 | - purge one pending floating I/O interrupt (KVM_DEV_FLIC_CLEAR_IO_IRQ) |
3c038e6b | 15 | - enable/disable for the guest transparent async page faults |
841b91c5 | 16 | - register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*) |
51978393 | 17 | - modify AIS (adapter-interruption-suppression) mode state (KVM_DEV_FLIC_AISM) |
a8920950 | 18 | - inject adapter interrupts on a specified adapter (KVM_DEV_FLIC_AIRQ_INJECT) |
2c1a48f2 | 19 | - get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL) |
c05c4186 JF |
20 | |
21 | Groups: | |
22 | KVM_DEV_FLIC_ENQUEUE | |
23 | Passes a buffer and length into the kernel which are then injected into | |
24 | the list of pending interrupts. | |
25 | attr->addr contains the pointer to the buffer and attr->attr contains | |
26 | the length of the buffer. | |
27 | The format of the data structure kvm_s390_irq as it is copied from userspace | |
28 | is defined in usr/include/linux/kvm.h. | |
29 | ||
30 | KVM_DEV_FLIC_GET_ALL_IRQS | |
31 | Copies all floating interrupts into a buffer provided by userspace. | |
32 | When the buffer is too small it returns -ENOMEM, which is the indication | |
33 | for userspace to try again with a bigger buffer. | |
94aa033e JF |
34 | -ENOBUFS is returned when the allocation of a kernelspace buffer has |
35 | failed. | |
36 | -EFAULT is returned when copying data to userspace failed. | |
c05c4186 JF |
37 | All interrupts remain pending, i.e. are not deleted from the list of |
38 | currently pending interrupts. | |
39 | attr->addr contains the userspace address of the buffer into which all | |
40 | interrupt data will be copied. | |
41 | attr->attr contains the size of the buffer in bytes. | |
42 | ||
43 | KVM_DEV_FLIC_CLEAR_IRQS | |
44 | Simply deletes all elements from the list of currently pending floating | |
45 | interrupts. No interrupts are injected into the guest. | |
3c038e6b | 46 | |
6d28f789 HP |
47 | KVM_DEV_FLIC_CLEAR_IO_IRQ |
48 | Deletes one (if any) I/O interrupt for a subchannel identified by the | |
49 | subsystem identification word passed via the buffer specified by | |
50 | attr->addr (address) and attr->attr (length). | |
51 | ||
3c038e6b DD |
52 | KVM_DEV_FLIC_APF_ENABLE |
53 | Enables async page faults for the guest. So in case of a major page fault | |
54 | the host is allowed to handle this async and continues the guest. | |
55 | ||
56 | KVM_DEV_FLIC_APF_DISABLE_WAIT | |
57 | Disables async page faults for the guest and waits until already pending | |
58 | async page faults are done. This is necessary to trigger a completion interrupt | |
59 | for every init interrupt before migrating the interrupt list. | |
841b91c5 CH |
60 | |
61 | KVM_DEV_FLIC_ADAPTER_REGISTER | |
62 | Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter | |
63 | describing the adapter to register: | |
64 | ||
65 | struct kvm_s390_io_adapter { | |
66 | __u32 id; | |
67 | __u8 isc; | |
68 | __u8 maskable; | |
69 | __u8 swap; | |
08fab50d | 70 | __u8 flags; |
841b91c5 CH |
71 | }; |
72 | ||
73 | id contains the unique id for the adapter, isc the I/O interruption subclass | |
08fab50d FL |
74 | to use, maskable whether this adapter may be masked (interrupts turned off), |
75 | swap whether the indicators need to be byte swapped, and flags contains | |
76 | further characteristics of the adapter. | |
77 | Currently defined values for 'flags' are: | |
78 | - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS | |
79 | (adapter-interrupt-suppression) facility. This flag only has an effect if | |
80 | the AIS capability is enabled. | |
81 | Unknown flag values are ignored. | |
841b91c5 CH |
82 | |
83 | ||
84 | KVM_DEV_FLIC_ADAPTER_MODIFY | |
85 | Modifies attributes of an existing I/O adapter interrupt source. Takes | |
1f644a73 | 86 | a kvm_s390_io_adapter_req specifying the adapter and the operation: |
841b91c5 CH |
87 | |
88 | struct kvm_s390_io_adapter_req { | |
89 | __u32 id; | |
90 | __u8 type; | |
91 | __u8 mask; | |
92 | __u16 pad0; | |
93 | __u64 addr; | |
94 | }; | |
95 | ||
96 | id specifies the adapter and type the operation. The supported operations | |
97 | are: | |
98 | ||
99 | KVM_S390_IO_ADAPTER_MASK | |
100 | mask or unmask the adapter, as specified in mask | |
101 | ||
102 | KVM_S390_IO_ADAPTER_MAP | |
103 | perform a gmap translation for the guest address provided in addr, | |
104 | pin a userspace page for the translated address and add it to the | |
105 | list of mappings | |
8a08b9c7 CH |
106 | Note: A new mapping will be created unconditionally; therefore, |
107 | the calling code should avoid making duplicate mappings. | |
841b91c5 CH |
108 | |
109 | KVM_S390_IO_ADAPTER_UNMAP | |
110 | release a userspace page for the translated address specified in addr | |
111 | from the list of mappings | |
dad7eefb | 112 | |
51978393 FL |
113 | KVM_DEV_FLIC_AISM |
114 | modify the adapter-interruption-suppression mode for a given isc if the | |
115 | AIS capability is enabled. Takes a kvm_s390_ais_req describing: | |
116 | ||
117 | struct kvm_s390_ais_req { | |
118 | __u8 isc; | |
119 | __u16 mode; | |
120 | }; | |
121 | ||
122 | isc contains the target I/O interruption subclass, mode the target | |
123 | adapter-interruption-suppression mode. The following modes are | |
124 | currently supported: | |
125 | - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection | |
126 | is always allowed; | |
127 | - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq | |
128 | injection is only allowed once and the following adapter interrupts | |
129 | will be suppressed until the mode is set again to ALL-Interruptions | |
130 | or SINGLE-Interruption mode. | |
131 | ||
a8920950 YMZ |
132 | KVM_DEV_FLIC_AIRQ_INJECT |
133 | Inject adapter interrupts on a specified adapter. | |
134 | attr->attr contains the unique id for the adapter, which allows for | |
135 | adapter-specific checks and actions. | |
136 | For adapters subject to AIS, handle the airq injection suppression for | |
137 | an isc according to the adapter-interruption-suppression mode on condition | |
138 | that the AIS capability is enabled. | |
139 | ||
2c1a48f2 YMZ |
140 | KVM_DEV_FLIC_AISM_ALL |
141 | Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes | |
142 | a kvm_s390_ais_all describing: | |
143 | ||
144 | struct kvm_s390_ais_all { | |
145 | __u8 simm; /* Single-Interruption-Mode mask */ | |
146 | __u8 nimm; /* No-Interruption-Mode mask * | |
147 | }; | |
148 | ||
149 | simm contains Single-Interruption-Mode mask for all ISCs, nimm contains | |
150 | No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds | |
151 | to an ISC (MSB0 bit 0 to ISC 0 and so on). The combination of simm bit and | |
152 | nimm bit presents AIS mode for a ISC. | |
153 | ||
da9a1446 CB |
154 | KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION. |
155 | ||
dad7eefb HP |
156 | Note: The KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR device ioctls executed on |
157 | FLIC with an unknown group or attribute gives the error code EINVAL (instead of | |
158 | ENXIO, as specified in the API documentation). It is not possible to conclude | |
159 | that a FLIC operation is unavailable based on the error code resulting from a | |
160 | usage attempt. | |
4dd6f17e MM |
161 | |
162 | Note: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a zero | |
163 | schid is specified. |