sys/xen/xenstore/xenstorevar.h

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