xref: /linux/include/xen/interface/event_channel.h (revision 9e2b3e83)
1 /* SPDX-License-Identifier: MIT */
2 /******************************************************************************
3  * event_channel.h
4  *
5  * Event channels between domains.
6  *
7  * Copyright (c) 2003-2004, K A Fraser.
8  */
9 
10 #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
11 #define __XEN_PUBLIC_EVENT_CHANNEL_H__
12 
13 #include <xen/interface/xen.h>
14 
15 typedef uint32_t evtchn_port_t;
16 DEFINE_GUEST_HANDLE(evtchn_port_t);
17 
18 /*
19  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
20  * accepting interdomain bindings from domain <remote_dom>. A fresh port
21  * is allocated in <dom> and returned as <port>.
22  * NOTES:
23  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
24  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
25  */
26 #define EVTCHNOP_alloc_unbound	  6
27 struct evtchn_alloc_unbound {
28 	/* IN parameters */
29 	domid_t dom, remote_dom;
30 	/* OUT parameters */
31 	evtchn_port_t port;
32 };
33 
34 /*
35  * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
36  * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
37  * a port that is unbound and marked as accepting bindings from the calling
38  * domain. A fresh port is allocated in the calling domain and returned as
39  * <local_port>.
40  * NOTES:
41  *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
42  */
43 #define EVTCHNOP_bind_interdomain 0
44 struct evtchn_bind_interdomain {
45 	/* IN parameters. */
46 	domid_t remote_dom;
47 	evtchn_port_t remote_port;
48 	/* OUT parameters. */
49 	evtchn_port_t local_port;
50 };
51 
52 /*
53  * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
54  * vcpu.
55  * NOTES:
56  *  1. A virtual IRQ may be bound to at most one event channel per vcpu.
57  *  2. The allocated event channel is bound to the specified vcpu. The binding
58  *     may not be changed.
59  */
60 #define EVTCHNOP_bind_virq	  1
61 struct evtchn_bind_virq {
62 	/* IN parameters. */
63 	uint32_t virq;
64 	uint32_t vcpu;
65 	/* OUT parameters. */
66 	evtchn_port_t port;
67 };
68 
69 /*
70  * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
71  * NOTES:
72  *  1. A physical IRQ may be bound to at most one event channel per domain.
73  *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
74  */
75 #define EVTCHNOP_bind_pirq	  2
76 struct evtchn_bind_pirq {
77 	/* IN parameters. */
78 	uint32_t pirq;
79 #define BIND_PIRQ__WILL_SHARE 1
80 	uint32_t flags; /* BIND_PIRQ__* */
81 	/* OUT parameters. */
82 	evtchn_port_t port;
83 };
84 
85 /*
86  * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
87  * NOTES:
88  *  1. The allocated event channel is bound to the specified vcpu. The binding
89  *     may not be changed.
90  */
91 #define EVTCHNOP_bind_ipi	  7
92 struct evtchn_bind_ipi {
93 	uint32_t vcpu;
94 	/* OUT parameters. */
95 	evtchn_port_t port;
96 };
97 
98 /*
99  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
100  * interdomain then the remote end is placed in the unbound state
101  * (EVTCHNSTAT_unbound), awaiting a new connection.
102  */
103 #define EVTCHNOP_close		  3
104 struct evtchn_close {
105 	/* IN parameters. */
106 	evtchn_port_t port;
107 };
108 
109 /*
110  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
111  * endpoint is <port>.
112  */
113 #define EVTCHNOP_send		  4
114 struct evtchn_send {
115 	/* IN parameters. */
116 	evtchn_port_t port;
117 };
118 
119 /*
120  * EVTCHNOP_status: Get the current status of the communication channel which
121  * has an endpoint at <dom, port>.
122  * NOTES:
123  *  1. <dom> may be specified as DOMID_SELF.
124  *  2. Only a sufficiently-privileged domain may obtain the status of an event
125  *     channel for which <dom> is not DOMID_SELF.
126  */
127 #define EVTCHNOP_status		  5
128 struct evtchn_status {
129 	/* IN parameters */
130 	domid_t  dom;
131 	evtchn_port_t port;
132 	/* OUT parameters */
133 #define EVTCHNSTAT_closed	0  /* Channel is not in use.		     */
134 #define EVTCHNSTAT_unbound	1  /* Channel is waiting interdom connection.*/
135 #define EVTCHNSTAT_interdomain	2  /* Channel is connected to remote domain. */
136 #define EVTCHNSTAT_pirq		3  /* Channel is bound to a phys IRQ line.   */
137 #define EVTCHNSTAT_virq		4  /* Channel is bound to a virtual IRQ line */
138 #define EVTCHNSTAT_ipi		5  /* Channel is bound to a virtual IPI line */
139 	uint32_t status;
140 	uint32_t vcpu;		   /* VCPU to which this channel is bound.   */
141 	union {
142 		struct {
143 			domid_t dom;
144 		} unbound; /* EVTCHNSTAT_unbound */
145 		struct {
146 			domid_t dom;
147 			evtchn_port_t port;
148 		} interdomain; /* EVTCHNSTAT_interdomain */
149 		uint32_t pirq;	    /* EVTCHNSTAT_pirq	      */
150 		uint32_t virq;	    /* EVTCHNSTAT_virq	      */
151 	} u;
152 };
153 
154 /*
155  * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an
156  * event is pending.
157  * NOTES:
158  *  1. IPI- and VIRQ-bound channels always notify the vcpu that initialised
159  *     the binding. This binding cannot be changed.
160  *  2. All other channels notify vcpu0 by default. This default is set when
161  *     the channel is allocated (a port that is freed and subsequently reused
162  *     has its binding reset to vcpu0).
163  */
164 #define EVTCHNOP_bind_vcpu	  8
165 struct evtchn_bind_vcpu {
166 	/* IN parameters. */
167 	evtchn_port_t port;
168 	uint32_t vcpu;
169 };
170 
171 /*
172  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
173  * a notification to the appropriate VCPU if an event is pending.
174  */
175 #define EVTCHNOP_unmask		  9
176 struct evtchn_unmask {
177 	/* IN parameters. */
178 	evtchn_port_t port;
179 };
180 
181 /*
182  * EVTCHNOP_reset: Close all event channels associated with specified domain.
183  * NOTES:
184  *  1. <dom> may be specified as DOMID_SELF.
185  *  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
186  */
187 #define EVTCHNOP_reset		 10
188 struct evtchn_reset {
189 	/* IN parameters. */
190 	domid_t dom;
191 };
192 typedef struct evtchn_reset evtchn_reset_t;
193 
194 /*
195  * EVTCHNOP_init_control: initialize the control block for the FIFO ABI.
196  */
197 #define EVTCHNOP_init_control    11
198 struct evtchn_init_control {
199 	/* IN parameters. */
200 	uint64_t control_gfn;
201 	uint32_t offset;
202 	uint32_t vcpu;
203 	/* OUT parameters. */
204 	uint8_t link_bits;
205 	uint8_t _pad[7];
206 };
207 
208 /*
209  * EVTCHNOP_expand_array: add an additional page to the event array.
210  */
211 #define EVTCHNOP_expand_array    12
212 struct evtchn_expand_array {
213 	/* IN parameters. */
214 	uint64_t array_gfn;
215 };
216 
217 /*
218  * EVTCHNOP_set_priority: set the priority for an event channel.
219  */
220 #define EVTCHNOP_set_priority    13
221 struct evtchn_set_priority {
222 	/* IN parameters. */
223 	evtchn_port_t port;
224 	uint32_t priority;
225 };
226 
227 struct evtchn_op {
228 	uint32_t cmd; /* EVTCHNOP_* */
229 	union {
230 		struct evtchn_alloc_unbound    alloc_unbound;
231 		struct evtchn_bind_interdomain bind_interdomain;
232 		struct evtchn_bind_virq	       bind_virq;
233 		struct evtchn_bind_pirq	       bind_pirq;
234 		struct evtchn_bind_ipi	       bind_ipi;
235 		struct evtchn_close	       close;
236 		struct evtchn_send	       send;
237 		struct evtchn_status	       status;
238 		struct evtchn_bind_vcpu	       bind_vcpu;
239 		struct evtchn_unmask	       unmask;
240 	} u;
241 };
242 DEFINE_GUEST_HANDLE_STRUCT(evtchn_op);
243 
244 /*
245  * 2-level ABI
246  */
247 
248 #define EVTCHN_2L_NR_CHANNELS (sizeof(xen_ulong_t) * sizeof(xen_ulong_t) * 64)
249 
250 /*
251  * FIFO ABI
252  */
253 
254 /* Events may have priorities from 0 (highest) to 15 (lowest). */
255 #define EVTCHN_FIFO_PRIORITY_MAX     0
256 #define EVTCHN_FIFO_PRIORITY_DEFAULT 7
257 #define EVTCHN_FIFO_PRIORITY_MIN     15
258 
259 #define EVTCHN_FIFO_MAX_QUEUES (EVTCHN_FIFO_PRIORITY_MIN + 1)
260 
261 typedef uint32_t event_word_t;
262 
263 #define EVTCHN_FIFO_PENDING 31
264 #define EVTCHN_FIFO_MASKED  30
265 #define EVTCHN_FIFO_LINKED  29
266 #define EVTCHN_FIFO_BUSY    28
267 
268 #define EVTCHN_FIFO_LINK_BITS 17
269 #define EVTCHN_FIFO_LINK_MASK ((1 << EVTCHN_FIFO_LINK_BITS) - 1)
270 
271 #define EVTCHN_FIFO_NR_CHANNELS (1 << EVTCHN_FIFO_LINK_BITS)
272 
273 struct evtchn_fifo_control_block {
274 	uint32_t     ready;
275 	uint32_t     _rsvd;
276 	event_word_t head[EVTCHN_FIFO_MAX_QUEUES];
277 };
278 
279 #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */
280