xenstorevar.h revision 222975
1185605Skmacy/****************************************************************************** 2214077Sgibbs * xenstorevar.h 3185605Skmacy * 4214077Sgibbs * Method declarations and structures for accessing the XenStore.h 5185605Skmacy * 6185605Skmacy * Copyright (C) 2005 Rusty Russell, IBM Corporation 7185605Skmacy * Copyright (C) 2005 XenSource Ltd. 8214077Sgibbs * Copyright (C) 2009,2010 Spectra Logic Corporation 9185605Skmacy * 10185605Skmacy * This file may be distributed separately from the Linux kernel, or 11185605Skmacy * incorporated into other software packages, subject to the following license: 12185605Skmacy * 13185605Skmacy * Permission is hereby granted, free of charge, to any person obtaining a copy 14185605Skmacy * of this source file (the "Software"), to deal in the Software without 15185605Skmacy * restriction, including without limitation the rights to use, copy, modify, 16185605Skmacy * merge, publish, distribute, sublicense, and/or sell copies of the Software, 17185605Skmacy * and to permit persons to whom the Software is furnished to do so, subject to 18185605Skmacy * the following conditions: 19185605Skmacy * 20185605Skmacy * The above copyright notice and this permission notice shall be included in 21185605Skmacy * all copies or substantial portions of the Software. 22185605Skmacy * 23185605Skmacy * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 24185605Skmacy * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 25185605Skmacy * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 26185605Skmacy * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 27185605Skmacy * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 28185605Skmacy * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 29185605Skmacy * IN THE SOFTWARE. 30185605Skmacy * 31185605Skmacy * $FreeBSD: head/sys/xen/xenstore/xenstorevar.h 222975 2011-06-11 04:59:01Z gibbs $ 32185605Skmacy */ 33185605Skmacy 34214077Sgibbs#ifndef _XEN_XENSTORE_XENSTOREVAR_H 35214077Sgibbs#define _XEN_XENSTORE_XENSTOREVAR_H 36185605Skmacy 37185605Skmacy#include <sys/queue.h> 38185605Skmacy#include <sys/bus.h> 39185605Skmacy#include <sys/eventhandler.h> 40214077Sgibbs#include <sys/malloc.h> 41214077Sgibbs#include <sys/sbuf.h> 42214077Sgibbs 43214077Sgibbs#include <machine/stdarg.h> 44185605Skmacy#include <machine/xen/xen-os.h> 45214077Sgibbs 46214077Sgibbs#include <xen/interface/grant_table.h> 47185605Skmacy#include <xen/interface/io/xenbus.h> 48185605Skmacy#include <xen/interface/io/xs_wire.h> 49185605Skmacy 50185605Skmacy#include "xenbus_if.h" 51185605Skmacy 52214077Sgibbs/* XenStore allocations including XenStore data returned to clients. */ 53214077SgibbsMALLOC_DECLARE(M_XENSTORE); 54185605Skmacy 55214077Sgibbsstruct xenstore_domain_interface; 56214077Sgibbsstruct xs_watch; 57214077Sgibbsextern struct xenstore_domain_interface *xen_store; 58185605Skmacy 59222975Sgibbstypedef void (xs_watch_cb_t)(struct xs_watch *, const char **vec, 60222975Sgibbs unsigned int len); 61185605Skmacy 62214077Sgibbs/* Register callback to watch subtree (node) in the XenStore. */ 63214077Sgibbsstruct xs_watch 64185605Skmacy{ 65214077Sgibbs LIST_ENTRY(xs_watch) list; 66185605Skmacy 67185605Skmacy /* Path being watched. */ 68185605Skmacy char *node; 69185605Skmacy 70185605Skmacy /* Callback (executed in a process context with no locks held). */ 71214077Sgibbs xs_watch_cb_t *callback; 72222975Sgibbs 73222975Sgibbs /* Callback client data untouched by the XenStore watch mechanism. */ 74222975Sgibbs uintptr_t callback_data; 75185605Skmacy}; 76214077SgibbsLIST_HEAD(xs_watch_list, xs_watch); 77185605Skmacy 78214077Sgibbstypedef int (*xs_event_handler_t)(void *); 79185605Skmacy 80214077Sgibbsstruct xs_transaction 81185605Skmacy{ 82214077Sgibbs uint32_t id; 83185605Skmacy}; 84185605Skmacy 85214077Sgibbs#define XST_NIL ((struct xs_transaction) { 0 }) 86185605Skmacy 87214077Sgibbs/** 88214077Sgibbs * Fetch the contents of a directory in the XenStore. 89214077Sgibbs * 90214077Sgibbs * \param t The XenStore transaction covering this request. 91214077Sgibbs * \param dir The dirname of the path to read. 92214077Sgibbs * \param node The basename of the path to read. 93214077Sgibbs * \param num The returned number of directory entries. 94214077Sgibbs * \param result An array of directory entry strings. 95214077Sgibbs * 96214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 97214077Sgibbs * type of failure. 98214077Sgibbs * 99214077Sgibbs * \note The results buffer is malloced and should be free'd by the 100214077Sgibbs * caller with 'free(*result, M_XENSTORE)'. 101214077Sgibbs */ 102214077Sgibbsint xs_directory(struct xs_transaction t, const char *dir, 103214077Sgibbs const char *node, unsigned int *num, const char ***result); 104185605Skmacy 105214077Sgibbs/** 106214077Sgibbs * Determine if a path exists in the XenStore. 107214077Sgibbs * 108214077Sgibbs * \param t The XenStore transaction covering this request. 109214077Sgibbs * \param dir The dirname of the path to read. 110214077Sgibbs * \param node The basename of the path to read. 111214077Sgibbs * 112214077Sgibbs * \retval 1 The path exists. 113214077Sgibbs * \retval 0 The path does not exist or an error occurred attempting 114214077Sgibbs * to make that determination. 115186557Skmacy */ 116214077Sgibbsint xs_exists(struct xs_transaction t, const char *dir, const char *node); 117185605Skmacy 118214077Sgibbs/** 119214077Sgibbs * Get the contents of a single "file". Returns the contents in 120214077Sgibbs * *result which should be freed with free(*result, M_XENSTORE) after 121214077Sgibbs * use. The length of the value in bytes is returned in *len. 122214077Sgibbs * 123214077Sgibbs * \param t The XenStore transaction covering this request. 124214077Sgibbs * \param dir The dirname of the file to read. 125214077Sgibbs * \param node The basename of the file to read. 126214077Sgibbs * \param len The amount of data read. 127214077Sgibbs * \param result The returned contents from this file. 128214077Sgibbs * 129214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 130214077Sgibbs * type of failure. 131214077Sgibbs * 132214077Sgibbs * \note The results buffer is malloced and should be free'd by the 133214077Sgibbs * caller with 'free(*result, M_XENSTORE)'. 134214077Sgibbs */ 135214077Sgibbsint xs_read(struct xs_transaction t, const char *dir, 136214077Sgibbs const char *node, unsigned int *len, void **result); 137185605Skmacy 138214077Sgibbs/** 139214077Sgibbs * Write to a single file. 140214077Sgibbs * 141214077Sgibbs * \param t The XenStore transaction covering this request. 142214077Sgibbs * \param dir The dirname of the file to write. 143214077Sgibbs * \param node The basename of the file to write. 144214077Sgibbs * \param string The NUL terminated string of data to write. 145214077Sgibbs * 146214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 147214077Sgibbs * type of failure. 148186557Skmacy */ 149214077Sgibbsint xs_write(struct xs_transaction t, const char *dir, 150214077Sgibbs const char *node, const char *string); 151185605Skmacy 152214077Sgibbs/** 153214077Sgibbs * Create a new directory. 154214077Sgibbs * 155214077Sgibbs * \param t The XenStore transaction covering this request. 156214077Sgibbs * \param dir The dirname of the directory to create. 157214077Sgibbs * \param node The basename of the directory to create. 158214077Sgibbs * 159214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 160214077Sgibbs * type of failure. 161214077Sgibbs */ 162214077Sgibbsint xs_mkdir(struct xs_transaction t, const char *dir, 163214077Sgibbs const char *node); 164185605Skmacy 165185605Skmacy/** 166214077Sgibbs * Remove a file or directory (directories must be empty). 167214077Sgibbs * 168214077Sgibbs * \param t The XenStore transaction covering this request. 169214077Sgibbs * \param dir The dirname of the directory to remove. 170214077Sgibbs * \param node The basename of the directory to remove. 171214077Sgibbs * 172214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 173214077Sgibbs * type of failure. 174185605Skmacy */ 175214077Sgibbsint xs_rm(struct xs_transaction t, const char *dir, const char *node); 176185605Skmacy 177185605Skmacy/** 178214077Sgibbs * Destroy a tree of files rooted at dir/node. 179214077Sgibbs * 180214077Sgibbs * \param t The XenStore transaction covering this request. 181214077Sgibbs * \param dir The dirname of the directory to remove. 182214077Sgibbs * \param node The basename of the directory to remove. 183214077Sgibbs * 184214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 185214077Sgibbs * type of failure. 186185605Skmacy */ 187214077Sgibbsint xs_rm_tree(struct xs_transaction t, const char *dir, 188214077Sgibbs const char *node); 189185605Skmacy 190185605Skmacy/** 191214077Sgibbs * Start a transaction. 192214077Sgibbs * 193214077Sgibbs * Changes by others will not be seen during the lifetime of this 194214077Sgibbs * transaction, and changes will not be visible to others until it 195214077Sgibbs * is committed (xs_transaction_end). 196214077Sgibbs * 197214077Sgibbs * \param t The returned transaction. 198214077Sgibbs * 199214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 200214077Sgibbs * type of failure. 201185605Skmacy */ 202214077Sgibbsint xs_transaction_start(struct xs_transaction *t); 203185605Skmacy 204185605Skmacy/** 205214077Sgibbs * End a transaction. 206214077Sgibbs * 207214077Sgibbs * \param t The transaction to end/commit. 208214077Sgibbs * \param abort If non-zero, the transaction is discarded 209214077Sgibbs * instead of committed. 210214077Sgibbs * 211214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 212214077Sgibbs * type of failure. 213185605Skmacy */ 214214077Sgibbsint xs_transaction_end(struct xs_transaction t, int abort); 215185605Skmacy 216214077Sgibbs/* 217214077Sgibbs * Single file read and scanf parsing of the result. 218214077Sgibbs * 219214077Sgibbs * \param t The XenStore transaction covering this request. 220214077Sgibbs * \param dir The dirname of the path to read. 221214077Sgibbs * \param node The basename of the path to read. 222214077Sgibbs * \param scancountp The number of input values assigned (i.e. the result 223214077Sgibbs * of scanf). 224214077Sgibbs * \param fmt Scanf format string followed by a variable number of 225214077Sgibbs * scanf input arguments. 226214077Sgibbs * 227214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 228214077Sgibbs * type of failure. 229214077Sgibbs */ 230214077Sgibbsint xs_scanf(struct xs_transaction t, 231214077Sgibbs const char *dir, const char *node, int *scancountp, const char *fmt, ...) 232214077Sgibbs __attribute__((format(scanf, 5, 6))); 233185605Skmacy 234185605Skmacy/** 235214077Sgibbs * Printf formatted write to a XenStore file. 236214077Sgibbs * 237214077Sgibbs * \param t The XenStore transaction covering this request. 238214077Sgibbs * \param dir The dirname of the path to read. 239214077Sgibbs * \param node The basename of the path to read. 240214077Sgibbs * \param fmt Printf format string followed by a variable number of 241214077Sgibbs * printf arguments. 242214077Sgibbs * 243214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 244214077Sgibbs * type of write failure. 245185605Skmacy */ 246214077Sgibbsint xs_printf(struct xs_transaction t, const char *dir, 247214077Sgibbs const char *node, const char *fmt, ...) 248214077Sgibbs __attribute__((format(printf, 4, 5))); 249185605Skmacy 250185605Skmacy/** 251214077Sgibbs * va_list version of xenbus_printf(). 252214077Sgibbs * 253214077Sgibbs * \param t The XenStore transaction covering this request. 254214077Sgibbs * \param dir The dirname of the path to read. 255214077Sgibbs * \param node The basename of the path to read. 256214077Sgibbs * \param fmt Printf format string. 257214077Sgibbs * \param ap Va_list of printf arguments. 258214077Sgibbs * 259214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 260214077Sgibbs * type of write failure. 261185605Skmacy */ 262214077Sgibbsint xs_vprintf(struct xs_transaction t, const char *dir, 263214077Sgibbs const char *node, const char *fmt, va_list ap); 264185605Skmacy 265185605Skmacy/** 266214077Sgibbs * Multi-file read within a single directory and scanf parsing of 267214077Sgibbs * the results. 268214077Sgibbs * 269214077Sgibbs * \param t The XenStore transaction covering this request. 270214077Sgibbs * \param dir The dirname of the paths to read. 271214077Sgibbs * \param ... A variable number of argument triples specifying 272214077Sgibbs * the file name, scanf-style format string, and 273214077Sgibbs * output variable (pointer to storage of the results). 274214077Sgibbs * The last triple in the call must be terminated 275214077Sgibbs * will a final NULL argument. A NULL format string 276214077Sgibbs * will cause the entire contents of the given file 277214077Sgibbs * to be assigned as a NUL terminated, M_XENSTORE heap 278214077Sgibbs * backed, string to the output parameter of that tuple. 279214077Sgibbs * 280214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 281214077Sgibbs * type of read failure. 282214077Sgibbs * 283214077Sgibbs * Example: 284214077Sgibbs * char protocol_abi[64]; 285214077Sgibbs * uint32_t ring_ref; 286214077Sgibbs * char *dev_type; 287214077Sgibbs * int error; 288214077Sgibbs * 289214077Sgibbs * error = xenbus_gather(XBT_NIL, xenbus_get_node(dev), 290214077Sgibbs * "ring-ref", "%" PRIu32, &ring_ref, 291214077Sgibbs * "protocol", "%63s", protocol_abi, 292214077Sgibbs * "device-type", NULL, &dev_type, 293214077Sgibbs * NULL); 294214077Sgibbs * 295214077Sgibbs * ... 296214077Sgibbs * 297214077Sgibbs * free(dev_type, M_XENSTORE); 298185605Skmacy */ 299214077Sgibbsint xs_gather(struct xs_transaction t, const char *dir, ...); 300185605Skmacy 301214077Sgibbs/** 302214077Sgibbs * Register a XenStore watch. 303214077Sgibbs * 304214077Sgibbs * XenStore watches allow a client to be notified via a callback (embedded 305214077Sgibbs * within the watch object) of changes to an object in the XenStore. 306214077Sgibbs * 307222975Sgibbs * \param watch An xs_watch struct with it's node and callback fields 308214077Sgibbs * properly initialized. 309214077Sgibbs * 310214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 311214077Sgibbs * type of write failure. EEXIST errors from the XenStore 312214077Sgibbs * are supressed, allowing multiple, physically different, 313214077Sgibbs * xenbus_watch objects, to watch the same path in the XenStore. 314185605Skmacy */ 315214077Sgibbsint xs_register_watch(struct xs_watch *watch); 316214077Sgibbs 317214077Sgibbs/** 318214077Sgibbs * Unregister a XenStore watch. 319214077Sgibbs * 320214077Sgibbs * \param watch An xs_watch object previously used in a successful call 321214077Sgibbs * to xs_register_watch(). 322214077Sgibbs * 323214077Sgibbs * The xs_watch object's node field is not altered by this call. 324214077Sgibbs * It is the caller's responsibility to properly dispose of both the 325214077Sgibbs * watch object and the data pointed to by watch->node. 326214077Sgibbs */ 327214077Sgibbsvoid xs_unregister_watch(struct xs_watch *watch); 328185605Skmacy 329214077Sgibbs/** 330214077Sgibbs * Allocate and return an sbuf containing the XenStore path string 331214077Sgibbs * <dir>/<name>. If name is the NUL string, the returned sbuf contains 332214077Sgibbs * the path string <dir>. 333214077Sgibbs * 334214077Sgibbs * \param dir The NUL terminated directory prefix for new path. 335214077Sgibbs * \param name The NUL terminated basename for the new path. 336214077Sgibbs * 337214077Sgibbs * \return A buffer containing the joined path. 338185605Skmacy */ 339214077Sgibbsstruct sbuf *xs_join(const char *, const char *); 340185605Skmacy 341214077Sgibbs#endif /* _XEN_XENSTORE_XENSTOREVAR_H */ 342