1 /* SPDX-License-Identifier: GPL-2.0 */
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 uint32_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__ */