The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/xen/xenstore/xenstorevar.h

Version: -  FREEBSD  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-2  -  FREEBSD-11-1  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-4  -  FREEBSD-10-3  -  FREEBSD-10-2  -  FREEBSD-10-1  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-3  -  FREEBSD-9-2  -  FREEBSD-9-1  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-4  -  FREEBSD-8-3  -  FREEBSD-8-2  -  FREEBSD-8-1  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-4  -  FREEBSD-7-3  -  FREEBSD-7-2  -  FREEBSD-7-1  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-4  -  FREEBSD-6-3  -  FREEBSD-6-2  -  FREEBSD-6-1  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-5  -  FREEBSD-5-4  -  FREEBSD-5-3  -  FREEBSD-5-2  -  FREEBSD-5-1  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1 
SearchContext: -  none  -  3  -  10 

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

Cache object: 1adc5d1406737ff7ea8d31b6bf4e06a2


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.