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 45 #include <xen/xen-os.h> 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 *, const char **vec, 60 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 /* Callback client data untouched by the XenStore watch mechanism. */ 74 uintptr_t callback_data; 75 }; 76 LIST_HEAD(xs_watch_list, xs_watch); 77 78 typedef int (*xs_event_handler_t)(void *); 79 80 struct xs_transaction 81 { 82 uint32_t id; 83 }; 84 85 #define XST_NIL ((struct xs_transaction) { 0 }) 86 87 /** 88 * Fetch the contents of a directory in the XenStore. 89 * 90 * \param t The XenStore transaction covering this request. 91 * \param dir The dirname of the path to read. 92 * \param node The basename of the path to read. 93 * \param num The returned number of directory entries. 94 * \param result An array of directory entry strings. 95 * 96 * \return On success, 0. Otherwise an errno value indicating the 97 * type of failure. 98 * 99 * \note The results buffer is malloced and should be free'd by the 100 * caller with 'free(*result, M_XENSTORE)'. 101 */ 102 int xs_directory(struct xs_transaction t, const char *dir, 103 const char *node, unsigned int *num, const char ***result); 104 105 /** 106 * Determine if a path exists in the XenStore. 107 * 108 * \param t The XenStore transaction covering this request. 109 * \param dir The dirname of the path to read. 110 * \param node The basename of the path to read. 111 * 112 * \retval 1 The path exists. 113 * \retval 0 The path does not exist or an error occurred attempting 114 * to make that determination. 115 */ 116 int xs_exists(struct xs_transaction t, const char *dir, const char *node); 117 118 /** 119 * Get the contents of a single "file". Returns the contents in 120 * *result which should be freed with free(*result, M_XENSTORE) after 121 * use. The length of the value in bytes is returned in *len. 122 * 123 * \param t The XenStore transaction covering this request. 124 * \param dir The dirname of the file to read. 125 * \param node The basename of the file to read. 126 * \param len The amount of data read. 127 * \param result The returned contents from this file. 128 * 129 * \return On success, 0. Otherwise an errno value indicating the 130 * type of failure. 131 * 132 * \note The results buffer is malloced and should be free'd by the 133 * caller with 'free(*result, M_XENSTORE)'. 134 */ 135 int xs_read(struct xs_transaction t, const char *dir, 136 const char *node, unsigned int *len, void **result); 137 138 /** 139 * Write to a single file. 140 * 141 * \param t The XenStore transaction covering this request. 142 * \param dir The dirname of the file to write. 143 * \param node The basename of the file to write. 144 * \param string The NUL terminated string of data to write. 145 * 146 * \return On success, 0. Otherwise an errno value indicating the 147 * type of failure. 148 */ 149 int xs_write(struct xs_transaction t, const char *dir, 150 const char *node, const char *string); 151 152 /** 153 * Create a new directory. 154 * 155 * \param t The XenStore transaction covering this request. 156 * \param dir The dirname of the directory to create. 157 * \param node The basename of the directory to create. 158 * 159 * \return On success, 0. Otherwise an errno value indicating the 160 * type of failure. 161 */ 162 int xs_mkdir(struct xs_transaction t, const char *dir, 163 const char *node); 164 165 /** 166 * Remove a file or directory (directories must be empty). 167 * 168 * \param t The XenStore transaction covering this request. 169 * \param dir The dirname of the directory to remove. 170 * \param node The basename of the directory to remove. 171 * 172 * \return On success, 0. Otherwise an errno value indicating the 173 * type of failure. 174 */ 175 int xs_rm(struct xs_transaction t, const char *dir, const char *node); 176 177 /** 178 * Destroy a tree of files rooted at dir/node. 179 * 180 * \param t The XenStore transaction covering this request. 181 * \param dir The dirname of the directory to remove. 182 * \param node The basename of the directory to remove. 183 * 184 * \return On success, 0. Otherwise an errno value indicating the 185 * type of failure. 186 */ 187 int xs_rm_tree(struct xs_transaction t, const char *dir, 188 const char *node); 189 190 /** 191 * Start a transaction. 192 * 193 * Changes by others will not be seen during the lifetime of this 194 * transaction, and changes will not be visible to others until it 195 * is committed (xs_transaction_end). 196 * 197 * \param t The returned transaction. 198 * 199 * \return On success, 0. Otherwise an errno value indicating the 200 * type of failure. 201 */ 202 int xs_transaction_start(struct xs_transaction *t); 203 204 /** 205 * End a transaction. 206 * 207 * \param t The transaction to end/commit. 208 * \param abort If non-zero, the transaction is discarded 209 * instead of committed. 210 * 211 * \return On success, 0. Otherwise an errno value indicating the 212 * type of failure. 213 */ 214 int xs_transaction_end(struct xs_transaction t, int abort); 215 216 /* 217 * Single file read and scanf parsing of the result. 218 * 219 * \param t The XenStore transaction covering this request. 220 * \param dir The dirname of the path to read. 221 * \param node The basename of the path to read. 222 * \param scancountp The number of input values assigned (i.e. the result 223 * of scanf). 224 * \param fmt Scanf format string followed by a variable number of 225 * scanf input arguments. 226 * 227 * \return On success, 0. Otherwise an errno value indicating the 228 * type of failure. 229 */ 230 int xs_scanf(struct xs_transaction t, 231 const char *dir, const char *node, int *scancountp, const char *fmt, ...) 232 __attribute__((format(scanf, 5, 6))); 233 234 /** 235 * Printf formatted write to a XenStore file. 236 * 237 * \param t The XenStore transaction covering this request. 238 * \param dir The dirname of the path to read. 239 * \param node The basename of the path to read. 240 * \param fmt Printf format string followed by a variable number of 241 * printf arguments. 242 * 243 * \return On success, 0. Otherwise an errno value indicating the 244 * type of write failure. 245 */ 246 int xs_printf(struct xs_transaction t, const char *dir, 247 const char *node, const char *fmt, ...) 248 __attribute__((format(printf, 4, 5))); 249 250 /** 251 * va_list version of xenbus_printf(). 252 * 253 * \param t The XenStore transaction covering this request. 254 * \param dir The dirname of the path to read. 255 * \param node The basename of the path to read. 256 * \param fmt Printf format string. 257 * \param ap Va_list of printf arguments. 258 * 259 * \return On success, 0. Otherwise an errno value indicating the 260 * type of write failure. 261 */ 262 int xs_vprintf(struct xs_transaction t, const char *dir, 263 const char *node, const char *fmt, va_list ap); 264 265 /** 266 * Multi-file read within a single directory and scanf parsing of 267 * the results. 268 * 269 * \param t The XenStore transaction covering this request. 270 * \param dir The dirname of the paths to read. 271 * \param ... A variable number of argument triples specifying 272 * the file name, scanf-style format string, and 273 * output variable (pointer to storage of the results). 274 * The last triple in the call must be terminated 275 * will a final NULL argument. A NULL format string 276 * will cause the entire contents of the given file 277 * to be assigned as a NUL terminated, M_XENSTORE heap 278 * backed, string to the output parameter of that tuple. 279 * 280 * \return On success, 0. Otherwise an errno value indicating the 281 * type of read failure. 282 * 283 * Example: 284 * char protocol_abi[64]; 285 * uint32_t ring_ref; 286 * char *dev_type; 287 * int error; 288 * 289 * error = xenbus_gather(XBT_NIL, xenbus_get_node(dev), 290 * "ring-ref", "%" PRIu32, &ring_ref, 291 * "protocol", "%63s", protocol_abi, 292 * "device-type", NULL, &dev_type, 293 * NULL); 294 * 295 * ... 296 * 297 * free(dev_type, M_XENSTORE); 298 */ 299 int xs_gather(struct xs_transaction t, const char *dir, ...); 300 301 /** 302 * Register a XenStore watch. 303 * 304 * XenStore watches allow a client to be notified via a callback (embedded 305 * within the watch object) of changes to an object in the XenStore. 306 * 307 * \param watch An xs_watch struct with it's node and callback fields 308 * properly initialized. 309 * 310 * \return On success, 0. Otherwise an errno value indicating the 311 * type of write failure. EEXIST errors from the XenStore 312 * are supressed, allowing multiple, physically different, 313 * xenbus_watch objects, to watch the same path in the XenStore. 314 */ 315 int xs_register_watch(struct xs_watch *watch); 316 317 /** 318 * Unregister a XenStore watch. 319 * 320 * \param watch An xs_watch object previously used in a successful call 321 * to xs_register_watch(). 322 * 323 * The xs_watch object's node field is not altered by this call. 324 * It is the caller's responsibility to properly dispose of both the 325 * watch object and the data pointed to by watch->node. 326 */ 327 void xs_unregister_watch(struct xs_watch *watch); 328 329 /** 330 * Allocate and return an sbuf containing the XenStore path string 331 * <dir>/<name>. If name is the NUL string, the returned sbuf contains 332 * the path string <dir>. 333 * 334 * \param dir The NUL terminated directory prefix for new path. 335 * \param name The NUL terminated basename for the new path. 336 * 337 * \return A buffer containing the joined path. 338 */ 339 struct sbuf *xs_join(const char *, const char *); 340 341 /** 342 * Lock the xenstore request mutex. 343 */ 344 void xs_lock(void); 345 346 /** 347 * Unlock the xenstore request mutex. 348 */ 349 void xs_unlock(void); 350 351 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */ 352 353