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