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
15typedef uint32_t evtchn_port_t;
16DEFINE_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
27struct 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
44struct 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
61struct 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
76struct 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
92struct 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
104struct 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
114struct 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
128struct 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
165struct 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
176struct 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
188struct evtchn_reset {
189	/* IN parameters. */
190	domid_t dom;
191};
192typedef 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
198struct 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
212struct 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
221struct evtchn_set_priority {
222	/* IN parameters. */
223	evtchn_port_t port;
224	uint32_t priority;
225};
226
227struct 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};
242DEFINE_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
261typedef 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
273struct 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