1 /****************************************************************************** 2 * Copyright (C) 2005 Rusty Russell, IBM Corporation 3 * Copyright (C) 2005 XenSource Ltd. 4 * 5 * This file may be distributed separately from the Linux kernel, or 6 * incorporated into other software packages, subject to the following license: 7 * 8 * Permission is hereby granted, free of charge, to any person obtaining a copy 9 * of this source file (the "Software"), to deal in the Software without 10 * restriction, including without limitation the rights to use, copy, modify, 11 * merge, publish, distribute, sublicense, and/or sell copies of the Software, 12 * and to permit persons to whom the Software is furnished to do so, subject to 13 * the following conditions: 14 * 15 * The above copyright notice and this permission notice shall be included in 16 * all copies or substantial portions of the Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 24 * IN THE SOFTWARE. 25 * 26 * $FreeBSD$ 27 */ 28 29 /** 30 * \file xenbusvar.h 31 * 32 * \brief Datastructures and function declarations for usedby device 33 * drivers operating on the XenBus. 34 */ 35 36 #ifndef _XEN_XENBUS_XENBUSVAR_H 37 #define _XEN_XENBUS_XENBUSVAR_H 38 39 #include <sys/queue.h> 40 #include <sys/bus.h> 41 #include <sys/eventhandler.h> 42 #include <sys/malloc.h> 43 #include <sys/sbuf.h> 44 45 #include <machine/stdarg.h> 46 #include <machine/xen/xen-os.h> 47 48 #include <xen/interface/grant_table.h> 49 #include <xen/interface/io/xenbus.h> 50 #include <xen/interface/io/xs_wire.h> 51 52 #include <xen/xenstore/xenstorevar.h> 53 54 /* XenBus allocations including XenStore data returned to clients. */ 55 MALLOC_DECLARE(M_XENBUS); 56 57 enum { 58 /** 59 * Path of this device node. 60 */ 61 XENBUS_IVAR_NODE, 62 63 /** 64 * The device type (e.g. vif, vbd). 65 */ 66 XENBUS_IVAR_TYPE, 67 68 /** 69 * The state of this device (not the otherend's state). 70 */ 71 XENBUS_IVAR_STATE, 72 73 /** 74 * Domain ID of the other end device. 75 */ 76 XENBUS_IVAR_OTHEREND_ID, 77 78 /** 79 * Path of the other end device. 80 */ 81 XENBUS_IVAR_OTHEREND_PATH 82 }; 83 84 /** 85 * Simplified accessors for xenbus devices 86 */ 87 #define XENBUS_ACCESSOR(var, ivar, type) \ 88 __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type) 89 90 XENBUS_ACCESSOR(node, NODE, const char *) 91 XENBUS_ACCESSOR(type, TYPE, const char *) 92 XENBUS_ACCESSOR(state, STATE, enum xenbus_state) 93 XENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int) 94 XENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *) 95 96 /** 97 * Return the state of a XenBus device. 98 * 99 * \param path The root XenStore path for the device. 100 * 101 * \return The current state of the device or XenbusStateClosed if no 102 * state can be read. 103 */ 104 XenbusState xenbus_read_driver_state(const char *path); 105 106 /** 107 * Return the state of the "other end" (peer) of a XenBus device. 108 * 109 * \param dev The XenBus device whose peer to query. 110 * 111 * \return The current state of the peer device or XenbusStateClosed if no 112 * state can be read. 113 */ 114 static inline XenbusState 115 xenbus_get_otherend_state(device_t dev) 116 { 117 return (xenbus_read_driver_state(xenbus_get_otherend_path(dev))); 118 } 119 120 /** 121 * Initialize and register a watch on the given path (client suplied storage). 122 * 123 * \param dev The XenBus device requesting the watch service. 124 * \param path The XenStore path of the object to be watched. The 125 * storage for this string must be stable for the lifetime 126 * of the watch. 127 * \param watch The watch object to use for this request. This object 128 * must be stable for the lifetime of the watch. 129 * \param callback The function to call when XenStore objects at or below 130 * path are modified. 131 * \param cb_data Client data that can be retrieved from the watch object 132 * during the callback. 133 * 134 * \return On success, 0. Otherwise an errno value indicating the 135 * type of failure. 136 * 137 * \note On error, the device 'dev' will be switched to the XenbusStateClosing 138 * state and the returned error is saved in the per-device error node 139 * for dev in the XenStore. 140 */ 141 int xenbus_watch_path(device_t dev, char *path, 142 struct xs_watch *watch, 143 xs_watch_cb_t *callback, 144 uintptr_t cb_data); 145 146 /** 147 * Initialize and register a watch at path/path2 in the XenStore. 148 * 149 * \param dev The XenBus device requesting the watch service. 150 * \param path The base XenStore path of the object to be watched. 151 * \param path2 The tail XenStore path of the object to be watched. 152 * \param watch The watch object to use for this request. This object 153 * must be stable for the lifetime of the watch. 154 * \param callback The function to call when XenStore objects at or below 155 * path are modified. 156 * \param cb_data Client data that can be retrieved from the watch object 157 * during the callback. 158 * 159 * \return On success, 0. Otherwise an errno value indicating the 160 * type of failure. 161 * 162 * \note On error, \a dev will be switched to the XenbusStateClosing 163 * state and the returned error is saved in the per-device error node 164 * for \a dev in the XenStore. 165 * 166 * Similar to xenbus_watch_path, however the storage for the path to the 167 * watched object is allocated from the heap and filled with "path '/' path2". 168 * Should a call to this function succeed, it is the callers responsibility 169 * to free watch->node using the M_XENBUS malloc type. 170 */ 171 int xenbus_watch_path2(device_t dev, const char *path, 172 const char *path2, struct xs_watch *watch, 173 xs_watch_cb_t *callback, 174 uintptr_t cb_data); 175 176 /** 177 * Grant access to the given ring_mfn to the peer of the given device. 178 * 179 * \param dev The device granting access to the ring page. 180 * \param ring_mfn The guest machine page number of the page to grant 181 * peer access rights. 182 * \param refp[out] The grant reference for the page. 183 * 184 * \return On success, 0. Otherwise an errno value indicating the 185 * type of failure. 186 * 187 * A successful call to xenbus_grant_ring should be paired with a call 188 * to gnttab_end_foreign_access() when foregn access to this page is no 189 * longer requried. 190 * 191 * \note On error, \a dev will be switched to the XenbusStateClosing 192 * state and the returned error is saved in the per-device error node 193 * for \a dev in the XenStore. 194 */ 195 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp); 196 197 /** 198 * Allocate an event channel for the given XenBus device. 199 * 200 * \param dev The device for which to allocate the event channel. 201 * \param port[out] The port identifier for the allocated event channel. 202 * 203 * \return On success, 0. Otherwise an errno value indicating the 204 * type of failure. 205 * 206 * A successfully allocated event channel should be free'd using 207 * xenbus_free_evtchn(). 208 * 209 * \note On error, \a dev will be switched to the XenbusStateClosing 210 * state and the returned error is saved in the per-device error node 211 * for \a dev in the XenStore. 212 */ 213 int xenbus_alloc_evtchn(device_t dev, evtchn_port_t *port); 214 215 /** 216 * Free an existing event channel. 217 * 218 * \param dev The device which allocated this event channel. 219 * \param port The port identifier for the event channel to free. 220 * 221 * \return On success, 0. Otherwise an errno value indicating the 222 * type of failure. 223 * 224 * \note On error, \a dev will be switched to the XenbusStateClosing 225 * state and the returned error is saved in the per-device error node 226 * for \a dev in the XenStore. 227 */ 228 int xenbus_free_evtchn(device_t dev, evtchn_port_t port); 229 230 /** 231 * Record the given errno, along with the given, printf-style, formatted 232 * message in dev's device specific error node in the XenStore. 233 * 234 * \param dev The device which encountered the error. 235 * \param err The errno value corresponding to the error. 236 * \param fmt Printf format string followed by a variable number of 237 * printf arguments. 238 */ 239 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...) 240 __attribute__((format(printf, 3, 4))); 241 242 /** 243 * va_list version of xenbus_dev_error(). 244 * 245 * \param dev The device which encountered the error. 246 * \param err The errno value corresponding to the error. 247 * \param fmt Printf format string. 248 * \param ap Va_list of printf arguments. 249 */ 250 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap) 251 __attribute__((format(printf, 3, 0))); 252 253 /** 254 * Equivalent to xenbus_dev_error(), followed by 255 * xenbus_set_state(dev, XenbusStateClosing). 256 * 257 * \param dev The device which encountered the error. 258 * \param err The errno value corresponding to the error. 259 * \param fmt Printf format string followed by a variable number of 260 * printf arguments. 261 */ 262 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...) 263 __attribute__((format(printf, 3, 4))); 264 265 /** 266 * va_list version of xenbus_dev_fatal(). 267 * 268 * \param dev The device which encountered the error. 269 * \param err The errno value corresponding to the error. 270 * \param fmt Printf format string. 271 * \param ap Va_list of printf arguments. 272 */ 273 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list) 274 __attribute__((format(printf, 3, 0))); 275 276 /** 277 * Convert a member of the xenbus_state enum into an ASCII string. 278 * 279 * /param state The XenBus state to lookup. 280 * 281 * /return A string representing state or, for unrecognized states, 282 * the string "Unknown". 283 */ 284 const char *xenbus_strstate(enum xenbus_state state); 285 286 /** 287 * Return the value of a XenBus device's "online" node within the XenStore. 288 * 289 * \param dev The XenBus device to query. 290 * 291 * \return The value of the "online" node for the device. If the node 292 * does not exist, 0 (offline) is returned. 293 */ 294 int xenbus_dev_is_online(device_t dev); 295 296 /** 297 * Default callback invoked when a change to the local XenStore sub-tree 298 * for a device is modified. 299 * 300 * \param dev The XenBus device whose tree was modified. 301 * \param path The tree relative sub-path to the modified node. The empty 302 * string indicates the root of the tree was destroyed. 303 */ 304 void xenbus_localend_changed(device_t dev, const char *path); 305 306 #include "xenbus_if.h" 307 308 #endif /* _XEN_XENBUS_XENBUSVAR_H */ 309