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. */ 51MALLOC_DECLARE(M_XENSTORE); 52 53struct xs_watch; 54 55typedef 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. */ 59struct 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}; 81LIST_HEAD(xs_watch_list, xs_watch); 82 83typedef int (*xs_event_handler_t)(void *); 84 85struct 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 */ 97bool xs_initialized(void); 98 99/** 100 * Return xenstore event channel port. 101 * 102 * \return event channel port. 103 */ 104evtchn_port_t xs_evtchn(void); 105 106/** 107 * Return xenstore page physical memory address. 108 * 109 * \return xenstore page physical address. 110 */ 111vm_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 */ 128int 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 */ 142int 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 */ 161int 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 */ 175int 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 */ 188int 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 */ 201int 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 */ 213int 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 */ 228int 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 */ 240int 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 */ 256int 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 */ 272int 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 */ 288int 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 */ 325int 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 */ 341int 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 */ 353void 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 */ 365struct sbuf *xs_join(const char *, const char *); 366 367/** 368 * Lock the xenstore request mutex. 369 */ 370void xs_lock(void); 371 372/** 373 * Unlock the xenstore request mutex. 374 */ 375void xs_unlock(void); 376 377#endif /* _XEN_XENSTORE_XENSTOREVAR_H */ 378