About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / virtual / kvm / devices / s390_flic.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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)
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	- get/set all AIS mode states (KVM_DEV_FLIC_AISM_ALL)
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.
34	    -ENOBUFS is returned when the allocation of a kernelspace buffer has
35	    failed.
36	    -EFAULT is returned when copying data to userspace failed.
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.
46	
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	
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.
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;
70		__u8 flags;
71	};
72	
73	   id contains the unique id for the adapter, isc the I/O interruption subclass
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.
82	
83	
84	  KVM_DEV_FLIC_ADAPTER_MODIFY
85	    Modifies attributes of an existing I/O adapter interrupt source. Takes
86	    a kvm_s390_io_adapter_req specifying the adapter and the operation:
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
106	      Note: A new mapping will be created unconditionally; therefore,
107	            the calling code should avoid making duplicate mappings.
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
112	
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	
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	
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	
154	    KVM_DEV_FLIC_AISM_ALL is indicated by KVM_CAP_S390_AIS_MIGRATION.
155	
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.
161	
162	Note: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a zero
163	schid is specified.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog