1/* $NetBSD: event_channel.h,v 1.6 2011/12/07 15:04:18 cegger Exp $ */
2/******************************************************************************
3 * event_channel.h
4 *
5 * Event channels between domains.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to
9 * deal in the Software without restriction, including without limitation the
10 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
11 * sell copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 * DEALINGS IN THE SOFTWARE.
24 *
25 * Copyright (c) 2003-2004, K A Fraser.
26 */
27
28#ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
29#define __XEN_PUBLIC_EVENT_CHANNEL_H__
30
31#include "xen.h"
32
33/*
34 * Prototype for this hypercall is:
35 * int event_channel_op(int cmd, void *args)
36 * @cmd == EVTCHNOP_??? (event-channel operation).
37 * @args == Operation-specific extra arguments (NULL if none).
38 */
39
40typedef uint32_t evtchn_port_t;
41DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
42
43/*
44 * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
45 * accepting interdomain bindings from domain <remote_dom>. A fresh port
46 * is allocated in <dom> and returned as <port>.
47 * NOTES:
48 * 1. If the caller is unprivileged then <dom> must be DOMID_SELF.
49 * 2. <rdom> may be DOMID_SELF, allowing loopback connections.
50 */
51#define EVTCHNOP_alloc_unbound 6
52struct evtchn_alloc_unbound {
53 /* IN parameters */
54 domid_t dom, remote_dom;
55 /* OUT parameters */
56 evtchn_port_t port;
57};
58typedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t;
59
60/*
61 * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
62 * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
63 * a port that is unbound and marked as accepting bindings from the calling
64 * domain. A fresh port is allocated in the calling domain and returned as
65 * <local_port>.
66 * NOTES:
67 * 2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
68 */
69#define EVTCHNOP_bind_interdomain 0
70struct evtchn_bind_interdomain {
71 /* IN parameters. */
72 domid_t remote_dom;
73 evtchn_port_t remote_port;
74 /* OUT parameters. */
75 evtchn_port_t local_port;
76};
77typedef struct evtchn_bind_interdomain evtchn_bind_interdomain_t;
78
79/*
80 * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
81 * vcpu.
82 * NOTES:
83 * 1. Virtual IRQs are classified as per-vcpu or global. See the VIRQ list
84 * in xen.h for the classification of each VIRQ.
85 * 2. Global VIRQs must be allocated on VCPU0 but can subsequently be
86 * re-bound via EVTCHNOP_bind_vcpu.
87 * 3. Per-vcpu VIRQs may be bound to at most one event channel per vcpu.
88 * The allocated event channel is bound to the specified vcpu and the
89 * binding cannot be changed.
90 */
91#define EVTCHNOP_bind_virq 1
92struct evtchn_bind_virq {
93 /* IN parameters. */
94 uint32_t virq;
95 uint32_t vcpu;
96 /* OUT parameters. */
97 evtchn_port_t port;
98};
99typedef struct evtchn_bind_virq evtchn_bind_virq_t;
100
101/*
102 * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
103 * NOTES:
104 * 1. A physical IRQ may be bound to at most one event channel per domain.
105 * 2. Only a sufficiently-privileged domain may bind to a physical IRQ.
106 */
107#define EVTCHNOP_bind_pirq 2
108struct evtchn_bind_pirq {
109 /* IN parameters. */
110 uint32_t pirq;
111#define BIND_PIRQ__WILL_SHARE 1
112 uint32_t flags; /* BIND_PIRQ__* */
113 /* OUT parameters. */
114 evtchn_port_t port;
115};
116typedef struct evtchn_bind_pirq evtchn_bind_pirq_t;
117
118/*
119 * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
120 * NOTES:
121 * 1. The allocated event channel is bound to the specified vcpu. The binding
122 * may not be changed.
123 */
124#define EVTCHNOP_bind_ipi 7
125struct evtchn_bind_ipi {
126 uint32_t vcpu;
127 /* OUT parameters. */
128 evtchn_port_t port;
129};
130typedef struct evtchn_bind_ipi evtchn_bind_ipi_t;
131
132/*
133 * EVTCHNOP_close: Close a local event channel <port>. If the channel is
134 * interdomain then the remote end is placed in the unbound state
135 * (EVTCHNSTAT_unbound), awaiting a new connection.
136 */
137#define EVTCHNOP_close 3
138struct evtchn_close {
139 /* IN parameters. */
140 evtchn_port_t port;
141};
142typedef struct evtchn_close evtchn_close_t;
143
144/*
145 * EVTCHNOP_send: Send an event to the remote end of the channel whose local
146 * endpoint is <port>.
147 */
148#define EVTCHNOP_send 4
149struct evtchn_send {
150 /* IN parameters. */
151 evtchn_port_t port;
152};
153typedef struct evtchn_send evtchn_send_t;
154
155/*
156 * EVTCHNOP_status: Get the current status of the communication channel which
157 * has an endpoint at <dom, port>.
158 * NOTES:
159 * 1. <dom> may be specified as DOMID_SELF.
160 * 2. Only a sufficiently-privileged domain may obtain the status of an event
161 * channel for which <dom> is not DOMID_SELF.
162 */
163#define EVTCHNOP_status 5
164struct evtchn_status {
165 /* IN parameters */
166 domid_t dom;
167 evtchn_port_t port;
168 /* OUT parameters */
169#define EVTCHNSTAT_closed 0 /* Channel is not in use. */
170#define EVTCHNSTAT_unbound 1 /* Channel is waiting interdom connection.*/
171#define EVTCHNSTAT_interdomain 2 /* Channel is connected to remote domain. */
172#define EVTCHNSTAT_pirq 3 /* Channel is bound to a phys IRQ line. */
173#define EVTCHNSTAT_virq 4 /* Channel is bound to a virtual IRQ line */
174#define EVTCHNSTAT_ipi 5 /* Channel is bound to a virtual IPI line */
175 uint32_t status;
176 uint32_t vcpu; /* VCPU to which this channel is bound. */
177 union {
178 struct {
179 domid_t dom;
180 } unbound; /* EVTCHNSTAT_unbound */
181 struct {
182 domid_t dom;
183 evtchn_port_t port;
184 } interdomain; /* EVTCHNSTAT_interdomain */
185 uint32_t pirq; /* EVTCHNSTAT_pirq */
186 uint32_t virq; /* EVTCHNSTAT_virq */
187 } u;
188};
189typedef struct evtchn_status evtchn_status_t;
190
191/*
192 * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an
193 * event is pending.
194 * NOTES:
195 * 1. IPI-bound channels always notify the vcpu specified at bind time.
196 * This binding cannot be changed.
197 * 2. Per-VCPU VIRQ channels always notify the vcpu specified at bind time.
198 * This binding cannot be changed.
199 * 3. All other channels notify vcpu0 by default. This default is set when
200 * the channel is allocated (a port that is freed and subsequently reused
201 * has its binding reset to vcpu0).
202 */
203#define EVTCHNOP_bind_vcpu 8
204struct evtchn_bind_vcpu {
205 /* IN parameters. */
206 evtchn_port_t port;
207 uint32_t vcpu;
208};
209typedef struct evtchn_bind_vcpu evtchn_bind_vcpu_t;
210
211/*
212 * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
213 * a notification to the appropriate VCPU if an event is pending.
214 */
215#define EVTCHNOP_unmask 9
216struct evtchn_unmask {
217 /* IN parameters. */
218 evtchn_port_t port;
219};
220typedef struct evtchn_unmask evtchn_unmask_t;
221
222/*
223 * EVTCHNOP_reset: Close all event channels associated with specified domain.
224 * NOTES:
225 * 1. <dom> may be specified as DOMID_SELF.
226 * 2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
227 */
228#define EVTCHNOP_reset 10
229struct evtchn_reset {
230 /* IN parameters. */
231 domid_t dom;
232};
233typedef struct evtchn_reset evtchn_reset_t;
234
235/*
236 * Argument to event_channel_op_compat() hypercall. Superceded by new
237 * event_channel_op() hypercall since 0x00030202.
238 */
239struct evtchn_op {
240 uint32_t cmd; /* EVTCHNOP_* */
241 union {
242 struct evtchn_alloc_unbound alloc_unbound;
243 struct evtchn_bind_interdomain bind_interdomain;
244 struct evtchn_bind_virq bind_virq;
245 struct evtchn_bind_pirq bind_pirq;
246 struct evtchn_bind_ipi bind_ipi;
247 struct evtchn_close close;
248 struct evtchn_send send;
249 struct evtchn_status status;
250 struct evtchn_bind_vcpu bind_vcpu;
251 struct evtchn_unmask unmask;
252 } u;
253};
254typedef struct evtchn_op evtchn_op_t;
255DEFINE_XEN_GUEST_HANDLE(evtchn_op_t);
256
257#endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */
258
259/*
260 * Local variables:
261 * mode: C
262 * c-set-style: "BSD"
263 * c-basic-offset: 4
264 * tab-width: 4
265 * indent-tabs-mode: nil
266 * End:
267 */
268