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