1 /****************************************************************************** 2 * xenstorevar.h 3 * 4 * Method declarations and structures for accessing the XenStore.h 5 * 6 * Copyright (C) 2005 Rusty Russell, IBM Corporation 7 * Copyright (C) 2005 XenSource Ltd. 8 * Copyright (C) 2009,2010 Spectra Logic Corporation 9 * 10 * This file may be distributed separately from the Linux kernel, or 11 * incorporated into other software packages, subject to the following license: 12 * 13 * Permission is hereby granted, free of charge, to any person obtaining a copy 14 * of this source file (the "Software"), to deal in the Software without 15 * restriction, including without limitation the rights to use, copy, modify, 16 * merge, publish, distribute, sublicense, and/or sell copies of the Software, 17 * and to permit persons to whom the Software is furnished to do so, subject to 18 * the following conditions: 19 * 20 * The above copyright notice and this permission notice shall be included in 21 * all copies or substantial portions of the Software. 22 * 23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 28 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 29 * IN THE SOFTWARE. 30 * 31 * $FreeBSD$ 32 */ 33 34 #ifndef _XEN_XENSTORE_XENSTOREVAR_H 35 #define _XEN_XENSTORE_XENSTOREVAR_H 36 37 #include <sys/queue.h> 38 #include <sys/bus.h> 39 #include <sys/eventhandler.h> 40 #include <sys/malloc.h> 41 #include <sys/sbuf.h> 42 43 #include <machine/stdarg.h> 44 #include <machine/xen/xen-os.h> 45 46 #include <xen/interface/grant_table.h> 47 #include <xen/interface/io/xenbus.h> 48 #include <xen/interface/io/xs_wire.h> 49 50 #include "xenbus_if.h" 51 52 /* XenStore allocations including XenStore data returned to clients. */ 53 MALLOC_DECLARE(M_XENSTORE); 54 55 struct xenstore_domain_interface; 56 struct xs_watch; 57 extern struct xenstore_domain_interface *xen_store; 58 59 typedef void (xs_watch_cb_t)(struct xs_watch *, 60 const char **vec, unsigned int len); 61 62 /* Register callback to watch subtree (node) in the XenStore. */ 63 struct xs_watch 64 { 65 LIST_ENTRY(xs_watch) list; 66 67 /* Path being watched. */ 68 char *node; 69 70 /* Callback (executed in a process context with no locks held). */ 71 xs_watch_cb_t *callback; 72 }; 73 LIST_HEAD(xs_watch_list, xs_watch); 74 75 typedef int (*xs_event_handler_t)(void *); 76 77 struct xs_transaction 78 { 79 uint32_t id; 80 }; 81 82 #define XST_NIL ((struct xs_transaction) { 0 }) 83 84 /** 85 * Fetch the contents of a directory in the XenStore. 86 * 87 * \param t The XenStore transaction covering this request. 88 * \param dir The dirname of the path to read. 89 * \param node The basename of the path to read. 90 * \param num The returned number of directory entries. 91 * \param result An array of directory entry strings. 92 * 93 * \return On success, 0. Otherwise an errno value indicating the 94 * type of failure. 95 * 96 * \note The results buffer is malloced and should be free'd by the 97 * caller with 'free(*result, M_XENSTORE)'. 98 */ 99 int xs_directory(struct xs_transaction t, const char *dir, 100 const char *node, unsigned int *num, const char ***result); 101 102 /** 103 * Determine if a path exists in the XenStore. 104 * 105 * \param t The XenStore transaction covering this request. 106 * \param dir The dirname of the path to read. 107 * \param node The basename of the path to read. 108 * 109 * \retval 1 The path exists. 110 * \retval 0 The path does not exist or an error occurred attempting 111 * to make that determination. 112 */ 113 int xs_exists(struct xs_transaction t, const char *dir, const char *node); 114 115 /** 116 * Get the contents of a single "file". Returns the contents in 117 * *result which should be freed with free(*result, M_XENSTORE) after 118 * use. The length of the value in bytes is returned in *len. 119 * 120 * \param t The XenStore transaction covering this request. 121 * \param dir The dirname of the file to read. 122 * \param node The basename of the file to read. 123 * \param len The amount of data read. 124 * \param result The returned contents from this file. 125 * 126 * \return On success, 0. Otherwise an errno value indicating the 127 * type of failure. 128 * 129 * \note The results buffer is malloced and should be free'd by the 130 * caller with 'free(*result, M_XENSTORE)'. 131 */ 132 int xs_read(struct xs_transaction t, const char *dir, 133 const char *node, unsigned int *len, void **result); 134 135 /** 136 * Write to a single file. 137 * 138 * \param t The XenStore transaction covering this request. 139 * \param dir The dirname of the file to write. 140 * \param node The basename of the file to write. 141 * \param string The NUL terminated string of data to write. 142 * 143 * \return On success, 0. Otherwise an errno value indicating the 144 * type of failure. 145 */ 146 int xs_write(struct xs_transaction t, const char *dir, 147 const char *node, const char *string); 148 149 /** 150 * Create a new directory. 151 * 152 * \param t The XenStore transaction covering this request. 153 * \param dir The dirname of the directory to create. 154 * \param node The basename of the directory to create. 155 * 156 * \return On success, 0. Otherwise an errno value indicating the 157 * type of failure. 158 */ 159 int xs_mkdir(struct xs_transaction t, const char *dir, 160 const char *node); 161 162 /** 163 * Remove a file or directory (directories must be empty). 164 * 165 * \param t The XenStore transaction covering this request. 166 * \param dir The dirname of the directory to remove. 167 * \param node The basename of the directory to remove. 168 * 169 * \return On success, 0. Otherwise an errno value indicating the 170 * type of failure. 171 */ 172 int xs_rm(struct xs_transaction t, const char *dir, const char *node); 173 174 /** 175 * Destroy a tree of files rooted at dir/node. 176 * 177 * \param t The XenStore transaction covering this request. 178 * \param dir The dirname of the directory to remove. 179 * \param node The basename of the directory to remove. 180 * 181 * \return On success, 0. Otherwise an errno value indicating the 182 * type of failure. 183 */ 184 int xs_rm_tree(struct xs_transaction t, const char *dir, 185 const char *node); 186 187 /** 188 * Start a transaction. 189 * 190 * Changes by others will not be seen during the lifetime of this 191 * transaction, and changes will not be visible to others until it 192 * is committed (xs_transaction_end). 193 * 194 * \param t The returned transaction. 195 * 196 * \return On success, 0. Otherwise an errno value indicating the 197 * type of failure. 198 */ 199 int xs_transaction_start(struct xs_transaction *t); 200 201 /** 202 * End a transaction. 203 * 204 * \param t The transaction to end/commit. 205 * \param abort If non-zero, the transaction is discarded 206 * instead of committed. 207 * 208 * \return On success, 0. Otherwise an errno value indicating the 209 * type of failure. 210 */ 211 int xs_transaction_end(struct xs_transaction t, int abort); 212 213 /* 214 * Single file read and scanf parsing of the result. 215 * 216 * \param t The XenStore transaction covering this request. 217 * \param dir The dirname of the path to read. 218 * \param node The basename of the path to read. 219 * \param scancountp The number of input values assigned (i.e. the result 220 * of scanf). 221 * \param fmt Scanf format string followed by a variable number of 222 * scanf input arguments. 223 * 224 * \return On success, 0. Otherwise an errno value indicating the 225 * type of failure. 226 */ 227 int xs_scanf(struct xs_transaction t, 228 const char *dir, const char *node, int *scancountp, const char *fmt, ...) 229 __attribute__((format(scanf, 5, 6))); 230 231 /** 232 * Printf formatted write to a XenStore file. 233 * 234 * \param t The XenStore transaction covering this request. 235 * \param dir The dirname of the path to read. 236 * \param node The basename of the path to read. 237 * \param fmt Printf format string followed by a variable number of 238 * printf arguments. 239 * 240 * \return On success, 0. Otherwise an errno value indicating the 241 * type of write failure. 242 */ 243 int xs_printf(struct xs_transaction t, const char *dir, 244 const char *node, const char *fmt, ...) 245 __attribute__((format(printf, 4, 5))); 246 247 /** 248 * va_list version of xenbus_printf(). 249 * 250 * \param t The XenStore transaction covering this request. 251 * \param dir The dirname of the path to read. 252 * \param node The basename of the path to read. 253 * \param fmt Printf format string. 254 * \param ap Va_list of printf arguments. 255 * 256 * \return On success, 0. Otherwise an errno value indicating the 257 * type of write failure. 258 */ 259 int xs_vprintf(struct xs_transaction t, const char *dir, 260 const char *node, const char *fmt, va_list ap); 261 262 /** 263 * Multi-file read within a single directory and scanf parsing of 264 * the results. 265 * 266 * \param t The XenStore transaction covering this request. 267 * \param dir The dirname of the paths to read. 268 * \param ... A variable number of argument triples specifying 269 * the file name, scanf-style format string, and 270 * output variable (pointer to storage of the results). 271 * The last triple in the call must be terminated 272 * will a final NULL argument. A NULL format string 273 * will cause the entire contents of the given file 274 * to be assigned as a NUL terminated, M_XENSTORE heap 275 * backed, string to the output parameter of that tuple. 276 * 277 * \return On success, 0. Otherwise an errno value indicating the 278 * type of read failure. 279 * 280 * Example: 281 * char protocol_abi[64]; 282 * uint32_t ring_ref; 283 * char *dev_type; 284 * int error; 285 * 286 * error = xenbus_gather(XBT_NIL, xenbus_get_node(dev), 287 * "ring-ref", "%" PRIu32, &ring_ref, 288 * "protocol", "%63s", protocol_abi, 289 * "device-type", NULL, &dev_type, 290 * NULL); 291 * 292 * ... 293 * 294 * free(dev_type, M_XENSTORE); 295 */ 296 int xs_gather(struct xs_transaction t, const char *dir, ...); 297 298 /** 299 * Register a XenStore watch. 300 * 301 * XenStore watches allow a client to be notified via a callback (embedded 302 * within the watch object) of changes to an object in the XenStore. 303 * 304 * \param watch A xenbus_watch struct with it's node and callback fields 305 * properly initialized. 306 * 307 * \return On success, 0. Otherwise an errno value indicating the 308 * type of write failure. EEXIST errors from the XenStore 309 * are supressed, allowing multiple, physically different, 310 * xenbus_watch objects, to watch the same path in the XenStore. 311 */ 312 int xs_register_watch(struct xs_watch *watch); 313 314 /** 315 * Unregister a XenStore watch. 316 * 317 * \param watch An xs_watch object previously used in a successful call 318 * to xs_register_watch(). 319 * 320 * The xs_watch object's node field is not altered by this call. 321 * It is the caller's responsibility to properly dispose of both the 322 * watch object and the data pointed to by watch->node. 323 */ 324 void xs_unregister_watch(struct xs_watch *watch); 325 326 /** 327 * Allocate and return an sbuf containing the XenStore path string 328 * <dir>/<name>. If name is the NUL string, the returned sbuf contains 329 * the path string <dir>. 330 * 331 * \param dir The NUL terminated directory prefix for new path. 332 * \param name The NUL terminated basename for the new path. 333 * 334 * \return A buffer containing the joined path. 335 */ 336 struct sbuf *xs_join(const char *, const char *); 337 338 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */ 339