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