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- enable/disable for the guest transparent async page faults
15- register and modify adapter interrupt sources (KVM_DEV_FLIC_ADAPTER_*)
16
17Groups:
18  KVM_DEV_FLIC_ENQUEUE
19    Passes a buffer and length into the kernel which are then injected into
20    the list of pending interrupts.
21    attr->addr contains the pointer to the buffer and attr->attr contains
22    the length of the buffer.
23    The format of the data structure kvm_s390_irq as it is copied from userspace
24    is defined in usr/include/linux/kvm.h.
25
26  KVM_DEV_FLIC_GET_ALL_IRQS
27    Copies all floating interrupts into a buffer provided by userspace.
28    When the buffer is too small it returns -ENOMEM, which is the indication
29    for userspace to try again with a bigger buffer.
30    -ENOBUFS is returned when the allocation of a kernelspace buffer has
31    failed.
32    -EFAULT is returned when copying data to userspace failed.
33    All interrupts remain pending, i.e. are not deleted from the list of
34    currently pending interrupts.
35    attr->addr contains the userspace address of the buffer into which all
36    interrupt data will be copied.
37    attr->attr contains the size of the buffer in bytes.
38
39  KVM_DEV_FLIC_CLEAR_IRQS
40    Simply deletes all elements from the list of currently pending floating
41    interrupts.  No interrupts are injected into the guest.
42
43  KVM_DEV_FLIC_APF_ENABLE
44    Enables async page faults for the guest. So in case of a major page fault
45    the host is allowed to handle this async and continues the guest.
46
47  KVM_DEV_FLIC_APF_DISABLE_WAIT
48    Disables async page faults for the guest and waits until already pending
49    async page faults are done. This is necessary to trigger a completion interrupt
50    for every init interrupt before migrating the interrupt list.
51
52  KVM_DEV_FLIC_ADAPTER_REGISTER
53    Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter
54    describing the adapter to register:
55
56struct kvm_s390_io_adapter {
57	__u32 id;
58	__u8 isc;
59	__u8 maskable;
60	__u8 swap;
61	__u8 pad;
62};
63
64   id contains the unique id for the adapter, isc the I/O interruption subclass
65   to use, maskable whether this adapter may be masked (interrupts turned off)
66   and swap whether the indicators need to be byte swapped.
67
68
69  KVM_DEV_FLIC_ADAPTER_MODIFY
70    Modifies attributes of an existing I/O adapter interrupt source. Takes
71    a kvm_s390_io_adapter_req specifiying the adapter and the operation:
72
73struct kvm_s390_io_adapter_req {
74	__u32 id;
75	__u8 type;
76	__u8 mask;
77	__u16 pad0;
78	__u64 addr;
79};
80
81    id specifies the adapter and type the operation. The supported operations
82    are:
83
84    KVM_S390_IO_ADAPTER_MASK
85      mask or unmask the adapter, as specified in mask
86
87    KVM_S390_IO_ADAPTER_MAP
88      perform a gmap translation for the guest address provided in addr,
89      pin a userspace page for the translated address and add it to the
90      list of mappings
91
92    KVM_S390_IO_ADAPTER_UNMAP
93      release a userspace page for the translated address specified in addr
94      from the list of mappings
95