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