1 /****************************************************************************** 2 * xenbus.h 3 * 4 * Talks to Xen Store to figure out what devices we have. 5 * 6 * Copyright (C) 2005 Rusty Russell, IBM Corporation 7 * Copyright (C) 2005 XenSource Ltd. 8 * 9 * This file may be distributed separately from the Linux kernel, or 10 * incorporated into other software packages, subject to the following license: 11 * 12 * Permission is hereby granted, free of charge, to any person obtaining a copy 13 * of this source file (the "Software"), to deal in the Software without 14 * restriction, including without limitation the rights to use, copy, modify, 15 * merge, publish, distribute, sublicense, and/or sell copies of the Software, 16 * and to permit persons to whom the Software is furnished to do so, subject to 17 * the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be included in 20 * all copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 25 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 28 * IN THE SOFTWARE. 29 * 30 * $FreeBSD$ 31 */ 32 33 #ifndef _XEN_XENBUS_XENBUSVAR_H 34 #define _XEN_XENBUS_XENBUSVAR_H 35 36 #include <sys/queue.h> 37 #include <sys/bus.h> 38 #include <sys/eventhandler.h> 39 #include <machine/xen/xen-os.h> 40 #include <xen/interface/io/xenbus.h> 41 #include <xen/interface/io/xs_wire.h> 42 43 #include "xenbus_if.h" 44 45 enum { 46 /* 47 * Path of this device node. 48 */ 49 XENBUS_IVAR_NODE, 50 51 /* 52 * The device type (e.g. vif, vbd). 53 */ 54 XENBUS_IVAR_TYPE, 55 56 /* 57 * The state of this device (not the otherend's state). 58 */ 59 XENBUS_IVAR_STATE, 60 61 /* 62 * Domain ID of the other end device. 63 */ 64 XENBUS_IVAR_OTHEREND_ID, 65 66 /* 67 * Path of the other end device. 68 */ 69 XENBUS_IVAR_OTHEREND_PATH 70 }; 71 72 /* 73 * Simplified accessors for xenbus devices 74 */ 75 #define XENBUS_ACCESSOR(var, ivar, type) \ 76 __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type) 77 78 XENBUS_ACCESSOR(node, NODE, const char *) 79 XENBUS_ACCESSOR(type, TYPE, const char *) 80 XENBUS_ACCESSOR(state, STATE, enum xenbus_state) 81 XENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int) 82 XENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *) 83 84 /* Register callback to watch this node. */ 85 struct xenbus_watch 86 { 87 LIST_ENTRY(xenbus_watch) list; 88 89 /* Path being watched. */ 90 char *node; 91 92 /* Callback (executed in a process context with no locks held). */ 93 void (*callback)(struct xenbus_watch *, 94 const char **vec, unsigned int len); 95 }; 96 97 typedef int (*xenstore_event_handler_t)(void *); 98 99 struct xenbus_transaction 100 { 101 uint32_t id; 102 }; 103 104 #define XBT_NIL ((struct xenbus_transaction) { 0 }) 105 106 int xenbus_directory(struct xenbus_transaction t, const char *dir, 107 const char *node, unsigned int *num, char ***result); 108 int xenbus_read(struct xenbus_transaction t, const char *dir, 109 const char *node, unsigned int *len, void **result); 110 int xenbus_write(struct xenbus_transaction t, const char *dir, 111 const char *node, const char *string); 112 int xenbus_mkdir(struct xenbus_transaction t, const char *dir, 113 const char *node); 114 int xenbus_exists(struct xenbus_transaction t, const char *dir, 115 const char *node); 116 int xenbus_rm(struct xenbus_transaction t, const char *dir, const char *node); 117 int xenbus_transaction_start(struct xenbus_transaction *t); 118 int xenbus_transaction_end(struct xenbus_transaction t, int abort); 119 120 /* 121 * Single read and scanf: returns errno or zero. If scancountp is 122 * non-null, then number of items scanned is returned in *scanncountp. 123 */ 124 int xenbus_scanf(struct xenbus_transaction t, 125 const char *dir, const char *node, int *scancountp, const char *fmt, ...) 126 __attribute__((format(scanf, 5, 6))); 127 128 /* Single printf and write: returns errno or 0. */ 129 int xenbus_printf(struct xenbus_transaction t, 130 const char *dir, const char *node, const char *fmt, ...) 131 __attribute__((format(printf, 4, 5))); 132 133 /* 134 * Generic read function: NULL-terminated triples of name, 135 * sprintf-style type string, and pointer. Returns 0 or errno. 136 */ 137 int xenbus_gather(struct xenbus_transaction t, const char *dir, ...); 138 139 /* notifer routines for when the xenstore comes up */ 140 int register_xenstore_notifier(xenstore_event_handler_t func, void *arg, int priority); 141 #if 0 142 void unregister_xenstore_notifier(); 143 #endif 144 int register_xenbus_watch(struct xenbus_watch *watch); 145 void unregister_xenbus_watch(struct xenbus_watch *watch); 146 void xs_suspend(void); 147 void xs_resume(void); 148 149 /* Used by xenbus_dev to borrow kernel's store connection. */ 150 int xenbus_dev_request_and_reply(struct xsd_sockmsg *msg, void **result); 151 152 #if 0 153 154 #define XENBUS_IS_ERR_READ(str) ({ \ 155 if (!IS_ERR(str) && strlen(str) == 0) { \ 156 free(str, M_DEVBUF); \ 157 str = ERR_PTR(-ERANGE); \ 158 } \ 159 IS_ERR(str); \ 160 }) 161 162 #endif 163 164 #define XENBUS_EXIST_ERR(err) ((err) == ENOENT || (err) == ERANGE) 165 166 167 /** 168 * Register a watch on the given path, using the given xenbus_watch structure 169 * for storage, and the given callback function as the callback. Return 0 on 170 * success, or errno on error. On success, the given path will be saved as 171 * watch->node, and remains the caller's to free. On error, watch->node will 172 * be NULL, the device will switch to XenbusStateClosing, and the error will 173 * be saved in the store. 174 */ 175 int xenbus_watch_path(device_t dev, char *path, 176 struct xenbus_watch *watch, 177 void (*callback)(struct xenbus_watch *, 178 const char **, unsigned int)); 179 180 181 /** 182 * Register a watch on the given path/path2, using the given xenbus_watch 183 * structure for storage, and the given callback function as the callback. 184 * Return 0 on success, or errno on error. On success, the watched path 185 * (path/path2) will be saved as watch->node, and becomes the caller's to 186 * kfree(). On error, watch->node will be NULL, so the caller has nothing to 187 * free, the device will switch to XenbusStateClosing, and the error will be 188 * saved in the store. 189 */ 190 int xenbus_watch_path2(device_t dev, const char *path, 191 const char *path2, struct xenbus_watch *watch, 192 void (*callback)(struct xenbus_watch *, 193 const char **, unsigned int)); 194 195 196 /** 197 * Advertise in the store a change of the given driver to the given new_state. 198 * which case this is performed inside its own transaction. Return 0 on 199 * success, or errno on error. On error, the device will switch to 200 * XenbusStateClosing, and the error will be saved in the store. 201 */ 202 int xenbus_switch_state(device_t dev, 203 XenbusState new_state); 204 205 206 /** 207 * Grant access to the given ring_mfn to the peer of the given device. 208 * Return 0 on success, or errno on error. On error, the device will 209 * switch to XenbusStateClosing, and the error will be saved in the 210 * store. The grant ring reference is returned in *refp. 211 */ 212 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, int *refp); 213 214 215 /** 216 * Allocate an event channel for the given xenbus_device, assigning the newly 217 * created local port to *port. Return 0 on success, or errno on error. On 218 * error, the device will switch to XenbusStateClosing, and the error will be 219 * saved in the store. 220 */ 221 int xenbus_alloc_evtchn(device_t dev, int *port); 222 223 224 /** 225 * Free an existing event channel. Returns 0 on success or errno on error. 226 */ 227 int xenbus_free_evtchn(device_t dev, int port); 228 229 230 /** 231 * Return the state of the driver rooted at the given store path, or 232 * XenbusStateClosed if no state can be read. 233 */ 234 XenbusState xenbus_read_driver_state(const char *path); 235 236 237 /*** 238 * Report the given negative errno into the store, along with the given 239 * formatted message. 240 */ 241 void xenbus_dev_error(device_t dev, int err, const char *fmt, 242 ...); 243 244 245 /*** 246 * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by 247 * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly 248 * closedown of this driver and its peer. 249 */ 250 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, 251 ...); 252 253 int xenbus_dev_init(void); 254 255 const char *xenbus_strstate(enum xenbus_state state); 256 int xenbus_dev_is_online(device_t dev); 257 int xenbus_frontend_closed(device_t dev); 258 259 #endif /* _XEN_XENBUS_XENBUSVAR_H */ 260