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 * Return a handle to the event channel driver, or NULL on failure, in 46 * which case errno will be set appropriately. 47 * 48 * Note: After fork(2) a child process must not use any opened evtchn 49 * handle inherited from their parent, nor access any grant mapped 50 * areas associated with that handle. 51 * 52 * The child must open a new handle if they want to interact with 53 * evtchn. 54 * 55 * Calling exec(2) in a child will safely (and reliably) reclaim any 56 * allocated resources via a xenevtchn_handle in the parent. 57 * 58 * A child which does not call exec(2) may safely call 59 * xenevtchn_close() on a xenevtchn_handle inherited from their 60 * parent. This will attempt to reclaim any resources associated with 61 * that handle. Note that in some implementations this reclamation may 62 * not be completely effective, in this case any affected resources 63 * remain allocated. 64 * 65 * Calling xenevtchn_close() is the only safe operation on a 66 * xenevtchn_handle which has been inherited. 67 */ 68 /* Currently no flags are defined */ 69 xenevtchn_handle *xenevtchn_open(struct xentoollog_logger *logger, 70 unsigned open_flags); 71 72 /* 73 * Close a handle previously allocated with xenevtchn_open(). 74 */ 75 int xenevtchn_close(xenevtchn_handle *xce); 76 77 /* 78 * Return an fd that can be select()ed on. 79 * 80 * Note that due to bugs, setting this fd to non blocking may not 81 * work: you would hope that it would result in xenevtchn_pending 82 * failing with EWOULDBLOCK if there are no events signaled, but in 83 * fact it may block. (Bug is present in at least Linux 3.12, and 84 * perhaps on other platforms or later version.) 85 * 86 * To be safe, you must use poll() or select() before each call to 87 * xenevtchn_pending. If you have multiple threads (or processes) 88 * sharing a single xce handle this will not work, and there is no 89 * straightforward workaround. Please design your program some other 90 * way. 91 */ 92 int xenevtchn_fd(xenevtchn_handle *xce); 93 94 /* 95 * Notify the given event channel. Returns -1 on failure, in which case 96 * errno will be set appropriately. 97 */ 98 int xenevtchn_notify(xenevtchn_handle *xce, evtchn_port_t port); 99 100 /* 101 * Returns a new event port awaiting interdomain connection from the given 102 * domain ID, or -1 on failure, in which case errno will be set appropriately. 103 */ 104 xenevtchn_port_or_error_t 105 xenevtchn_bind_unbound_port(xenevtchn_handle *xce, uint32_t domid); 106 107 /* 108 * Returns a new event port bound to the remote port for the given domain ID, 109 * or -1 on failure, in which case errno will be set appropriately. 110 */ 111 xenevtchn_port_or_error_t 112 xenevtchn_bind_interdomain(xenevtchn_handle *xce, uint32_t domid, 113 evtchn_port_t remote_port); 114 115 /* 116 * Bind an event channel to the given VIRQ. Returns the event channel bound to 117 * the VIRQ, or -1 on failure, in which case errno will be set appropriately. 118 */ 119 xenevtchn_port_or_error_t 120 xenevtchn_bind_virq(xenevtchn_handle *xce, unsigned int virq); 121 122 /* 123 * Unbind the given event channel. Returns -1 on failure, in which case errno 124 * will be set appropriately. 125 */ 126 int xenevtchn_unbind(xenevtchn_handle *xce, evtchn_port_t port); 127 128 /* 129 * Return the next event channel to become pending, or -1 on failure, in which 130 * case errno will be set appropriately. 131 * 132 * At the hypervisor level the event channel will have been masked, 133 * and then cleared, by the underlying machinery (evtchn kernel 134 * driver, or equivalent). So if the event channel is signaled again 135 * after it is returned here, it will be queued up, and delivered 136 * again after you unmask it. (See the documentation in the Xen 137 * public header event_channel.h.) 138 * 139 * On receiving the notification from xenevtchn_pending, you should 140 * normally: check (by other means) what work needs doing; do the 141 * necessary work (if any); unmask the event channel with 142 * xenevtchn_unmask (if you want to receive any further 143 * notifications). 144 */ 145 xenevtchn_port_or_error_t 146 xenevtchn_pending(xenevtchn_handle *xce); 147 148 /* 149 * Unmask the given event channel. Returns -1 on failure, in which case errno 150 * will be set appropriately. 151 */ 152 int xenevtchn_unmask(xenevtchn_handle *xce, evtchn_port_t port); 153 154 /** 155 * This function restricts the use of this handle to the specified 156 * domain. 157 * 158 * @parm xce handle to the open evtchn interface 159 * @parm domid the domain id 160 * @return 0 on success, -1 on failure with errno set appropriately. 161 */ 162 int xenevtchn_restrict(xenevtchn_handle *xce, domid_t domid); 163 164 #endif 165 166 /* 167 * Local variables: 168 * mode: C 169 * c-file-style: "BSD" 170 * c-basic-offset: 4 171 * tab-width: 4 172 * indent-tabs-mode: nil 173 * End: 174 */ 175