1 /*
2  * This library is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU Lesser General Public
4  * License as published by the Free Software Foundation;
5  * version 2.1 of the License.
6  *
7  * This library is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
10  * Lesser General Public License for more details.
11  *
12  * You should have received a copy of the GNU Lesser General Public
13  * License along with this library; If not, see <http://www.gnu.org/licenses/>.
14  *
15  * Split off from:
16  * xenctrl.h
17  *
18  * A library for low-level access to the Xen control interfaces.
19  *
20  * Copyright (c) 2003-2004, K A Fraser.
21  */
22 
23 #ifndef XENEVTCHN_H
24 #define XENEVTCHN_H
25 
26 #include <stdint.h>
27 
28 #include <xen/event_channel.h>
29 
30 /* A port identifier is guaranteed to fit in 31 bits. */
31 typedef int xenevtchn_port_or_error_t;
32 
33 typedef struct xenevtchn_handle xenevtchn_handle;
34 
35 /* Callers who don't care don't need to #include <xentoollog.h> */
36 struct xentoollog_logger;
37 
38 /*
39  * EVENT CHANNEL FUNCTIONS
40  *
41  * None of these do any logging.
42  */
43 
44 /*
45  * Opens the evtchn device node.  Return a handle to the event channel
46  * driver, or NULL on failure, in which case errno will be set
47  * appropriately.
48  *
49  * On fork(2):
50  *
51  *   After fork, a child process must not use any opened evtchn handle
52  *   inherited from their parent.  This includes operations such as
53  *   poll() on the underlying file descriptor.  Calling xenevtchn_close()
54  *   is the only safe operation on a xenevtchn_handle which has been
55  *   inherited.
56  *
57  *   The child must open a new handle if they want to interact with
58  *   evtchn.
59  *
60  * On exec(2):
61  *
62  *   Wherever possible, the device node will be opened with O_CLOEXEC,
63  *   so it is not inherited by the subsequent program.
64  *
65  *   However the XENEVTCHN_NO_CLOEXEC flag may be used to avoid opening
66  *   the device node with O_CLOEXEC.  This is intended for use by
67  *   daemons which support a self-reexec method of updating themselves.
68  *
69  *   In this case, the updated daemon should pass the underlying file
70  *   descriptor it inherited to xenevtchn_fdopen() to reconstruct the
71  *   library handle.
72  */
73 
74 /* Don't set O_CLOEXEC when opening event channel driver node. */
75 #define XENEVTCHN_NO_CLOEXEC (1 << 0)
76 
77 xenevtchn_handle *xenevtchn_open(struct xentoollog_logger *logger,
78                                  unsigned int flags);
79 
80 /* Flag XENEVTCHN_NO_CLOEXEC is rejected by xenevtchn_fdopen(). */
81 xenevtchn_handle *xenevtchn_fdopen(struct xentoollog_logger *logger,
82                                     int fd, unsigned open_flags);
83 
84 /*
85  * Close a handle previously allocated with xenevtchn_{,fd}open().
86  */
87 int xenevtchn_close(xenevtchn_handle *xce);
88 
89 /*
90  * Return an fd that can be select()ed on.
91  *
92  * Note that due to bugs, setting this fd to non blocking may not
93  * work: you would hope that it would result in xenevtchn_pending
94  * failing with EWOULDBLOCK if there are no events signaled, but in
95  * fact it may block.  (Bug is present in at least Linux 3.12, and
96  * perhaps on other platforms or later version.)
97  *
98  * To be safe, you must use poll() or select() before each call to
99  * xenevtchn_pending.  If you have multiple threads (or processes)
100  * sharing a single xce handle this will not work, and there is no
101  * straightforward workaround.  Please design your program some other
102  * way.
103  */
104 int xenevtchn_fd(xenevtchn_handle *xce);
105 
106 /*
107  * Notify the given event channel. Returns -1 on failure, in which case
108  * errno will be set appropriately.
109  */
110 int xenevtchn_notify(xenevtchn_handle *xce, evtchn_port_t port);
111 
112 /*
113  * Returns a new event port awaiting interdomain connection from the given
114  * domain ID, or -1 on failure, in which case errno will be set appropriately.
115  */
116 xenevtchn_port_or_error_t
117 xenevtchn_bind_unbound_port(xenevtchn_handle *xce, uint32_t domid);
118 
119 /*
120  * Returns a new event port bound to the remote port for the given domain ID,
121  * or -1 on failure, in which case errno will be set appropriately.
122  */
123 xenevtchn_port_or_error_t
124 xenevtchn_bind_interdomain(xenevtchn_handle *xce, uint32_t domid,
125                            evtchn_port_t remote_port);
126 
127 /*
128  * Bind an event channel to the given VIRQ. Returns the event channel bound to
129  * the VIRQ, or -1 on failure, in which case errno will be set appropriately.
130  */
131 xenevtchn_port_or_error_t
132 xenevtchn_bind_virq(xenevtchn_handle *xce, unsigned int virq);
133 
134 /*
135  * Unbind the given event channel. Returns -1 on failure, in which case errno
136  * will be set appropriately.
137  */
138 int xenevtchn_unbind(xenevtchn_handle *xce, evtchn_port_t port);
139 
140 /*
141  * Return the next event channel to become pending, or -1 on failure, in which
142  * case errno will be set appropriately.
143  *
144  * At the hypervisor level the event channel will have been masked,
145  * and then cleared, by the underlying machinery (evtchn kernel
146  * driver, or equivalent).  So if the event channel is signaled again
147  * after it is returned here, it will be queued up, and delivered
148  * again after you unmask it.  (See the documentation in the Xen
149  * public header event_channel.h.)
150  *
151  * On receiving the notification from xenevtchn_pending, you should
152  * normally: check (by other means) what work needs doing; do the
153  * necessary work (if any); unmask the event channel with
154  * xenevtchn_unmask (if you want to receive any further
155  * notifications).
156  */
157 xenevtchn_port_or_error_t
158 xenevtchn_pending(xenevtchn_handle *xce);
159 
160 /*
161  * Unmask the given event channel. Returns -1 on failure, in which case errno
162  * will be set appropriately.
163  */
164 int xenevtchn_unmask(xenevtchn_handle *xce, evtchn_port_t port);
165 
166 /**
167  * This function restricts the use of this handle to the specified
168  * domain.
169  *
170  * @parm xce handle to the open evtchn interface
171  * @parm domid the domain id
172  * @return 0 on success, -1 on failure with errno set appropriately.
173  */
174 int xenevtchn_restrict(xenevtchn_handle *xce, domid_t domid);
175 
176 #endif
177 
178 /*
179  * Local variables:
180  * mode: C
181  * c-file-style: "BSD"
182  * c-basic-offset: 4
183  * tab-width: 4
184  * indent-tabs-mode: nil
185  * End:
186  */
187