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