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         /* 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 */