sys/xen/xenbus/xenbusvar.h

   1 /******************************************************************************
   2  * xenbus.h
   3  *
   4  * Talks to Xen Store to figure out what devices we have.
   5  *
   6  * Copyright (C) 2005 Rusty Russell, IBM Corporation
   7  * Copyright (C) 2005 XenSource Ltd.
   8  *
   9  * This file may be distributed separately from the Linux kernel, or
  10  * incorporated into other software packages, subject to the following license:
  11  *
  12  * Permission is hereby granted, free of charge, to any person obtaining a copy
  13  * of this source file (the "Software"), to deal in the Software without
  14  * restriction, including without limitation the rights to use, copy, modify,
  15  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  16  * and to permit persons to whom the Software is furnished to do so, subject to
  17  * the following conditions:
  18  *
  19  * The above copyright notice and this permission notice shall be included in
  20  * all copies or substantial portions of the Software.
  21  *
  22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  23  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  25  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  26  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  27  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  28  * IN THE SOFTWARE.
  29  *
  30  * $FreeBSD$
  31  */
  32
  33 #ifndef _XEN_XENBUS_XENBUSVAR_H
  34 #define _XEN_XENBUS_XENBUSVAR_H
  35
  36 #include <sys/queue.h>
  37 #include <sys/bus.h>
  38 #include <sys/eventhandler.h>
  39 #include <machine/xen/xen-os.h>
  40 #include <xen/interface/io/xenbus.h>
  41 #include <xen/interface/io/xs_wire.h>
  42
  43 #include "xenbus_if.h"
  44
  45 enum {
  46         /*
  47          * Path of this device node.
  48          */
  49         XENBUS_IVAR_NODE,
  50
  51         /*
  52          * The device type (e.g. vif, vbd).
  53          */
  54         XENBUS_IVAR_TYPE,
  55
  56         /*
  57          * The state of this device (not the otherend's state).
  58          */
  59         XENBUS_IVAR_STATE,
  60
  61         /*
  62          * Domain ID of the other end device.
  63          */
  64         XENBUS_IVAR_OTHEREND_ID,
  65
  66         /*
  67          * Path of the other end device.
  68          */
  69         XENBUS_IVAR_OTHEREND_PATH
  70 };
  71
  72 /*
  73  * Simplified accessors for xenbus devices
  74  */
  75 #define XENBUS_ACCESSOR(var, ivar, type) \
  76         __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
  77
  78 XENBUS_ACCESSOR(node,           NODE,                   const char *)
  79 XENBUS_ACCESSOR(type,           TYPE,                   const char *)
  80 XENBUS_ACCESSOR(state,          STATE,                  enum xenbus_state)
  81 XENBUS_ACCESSOR(otherend_id,    OTHEREND_ID,            int)
  82 XENBUS_ACCESSOR(otherend_path,  OTHEREND_PATH,          const char *)
  83
  84 /* Register callback to watch this node. */
  85 struct xenbus_watch
  86 {
  87         LIST_ENTRY(xenbus_watch) list;
  88
  89         /* Path being watched. */
  90         char *node;
  91
  92         /* Callback (executed in a process context with no locks held). */
  93         void (*callback)(struct xenbus_watch *,
  94                          const char **vec, unsigned int len);
  95 };
  96
  97 typedef int (*xenstore_event_handler_t)(void *);
  98
  99 struct xenbus_transaction
 100 {
 101                 uint32_t id;
 102 };
 103
 104 #define XBT_NIL ((struct xenbus_transaction) { 0 })
 105
 106 int xenbus_directory(struct xenbus_transaction t, const char *dir,
 107     const char *node, unsigned int *num, char ***result);
 108 int xenbus_read(struct xenbus_transaction t, const char *dir,
 109     const char *node, unsigned int *len, void **result);
 110 int xenbus_write(struct xenbus_transaction t, const char *dir,
 111     const char *node, const char *string);
 112 int xenbus_mkdir(struct xenbus_transaction t, const char *dir,
 113     const char *node);
 114 int xenbus_exists(struct xenbus_transaction t, const char *dir,
 115     const char *node);
 116 int xenbus_rm(struct xenbus_transaction t, const char *dir, const char *node);
 117 int xenbus_transaction_start(struct xenbus_transaction *t);
 118 int xenbus_transaction_end(struct xenbus_transaction t, int abort);
 119
 120 /*
 121  * Single read and scanf: returns errno or zero. If scancountp is
 122  * non-null, then number of items scanned is returned in *scanncountp.
 123  */
 124 int xenbus_scanf(struct xenbus_transaction t,
 125     const char *dir, const char *node, int *scancountp, const char *fmt, ...)
 126         __attribute__((format(scanf, 5, 6)));
 127
 128 /* Single printf and write: returns errno or 0. */
 129 int xenbus_printf(struct xenbus_transaction t,
 130                   const char *dir, const char *node, const char *fmt, ...)
 131         __attribute__((format(printf, 4, 5)));
 132
 133 /*
 134  * Generic read function: NULL-terminated triples of name,
 135  * sprintf-style type string, and pointer. Returns 0 or errno.
 136  */
 137 int xenbus_gather(struct xenbus_transaction t, const char *dir, ...);
 138
 139 /* notifer routines for when the xenstore comes up */
 140 int register_xenstore_notifier(xenstore_event_handler_t func, void *arg, int priority);
 141 #if 0
 142 void unregister_xenstore_notifier();
 143 #endif
 144 int register_xenbus_watch(struct xenbus_watch *watch);
 145 void unregister_xenbus_watch(struct xenbus_watch *watch);
 146 void xs_suspend(void);
 147 void xs_resume(void);
 148
 149 /* Used by xenbus_dev to borrow kernel's store connection. */
 150 int xenbus_dev_request_and_reply(struct xsd_sockmsg *msg, void **result);
 151
 152 #if 0
 153
 154 #define XENBUS_IS_ERR_READ(str) ({                      \
 155         if (!IS_ERR(str) && strlen(str) == 0) {         \
 156                 free(str, M_DEVBUF);                            \
 157                 str = ERR_PTR(-ERANGE);                 \
 158         }                                               \
 159         IS_ERR(str);                                    \
 160 })
 161
 162 #endif
 163
 164 #define XENBUS_EXIST_ERR(err) ((err) == ENOENT || (err) == ERANGE)
 165
 166
 167 /**
 168  * Register a watch on the given path, using the given xenbus_watch structure
 169  * for storage, and the given callback function as the callback.  Return 0 on
 170  * success, or errno on error.  On success, the given path will be saved as
 171  * watch->node, and remains the caller's to free.  On error, watch->node will
 172  * be NULL, the device will switch to XenbusStateClosing, and the error will
 173  * be saved in the store.
 174  */
 175 int xenbus_watch_path(device_t dev, char *path,
 176                       struct xenbus_watch *watch,
 177                       void (*callback)(struct xenbus_watch *,
 178                                        const char **, unsigned int));
 179
 180
 181 /**
 182  * Register a watch on the given path/path2, using the given xenbus_watch
 183  * structure for storage, and the given callback function as the callback.
 184  * Return 0 on success, or errno on error.  On success, the watched path
 185  * (path/path2) will be saved as watch->node, and becomes the caller's to
 186  * kfree().  On error, watch->node will be NULL, so the caller has nothing to
 187  * free, the device will switch to XenbusStateClosing, and the error will be
 188  * saved in the store.
 189  */
 190 int xenbus_watch_path2(device_t dev, const char *path,
 191                        const char *path2, struct xenbus_watch *watch,
 192                        void (*callback)(struct xenbus_watch *,
 193                                         const char **, unsigned int));
 194
 195
 196 /**
 197  * Advertise in the store a change of the given driver to the given new_state.
 198  * which case this is performed inside its own transaction.  Return 0 on
 199  * success, or errno on error.  On error, the device will switch to
 200  * XenbusStateClosing, and the error will be saved in the store.
 201  */
 202 int xenbus_switch_state(device_t dev,
 203                         XenbusState new_state);
 204
 205
 206 /**
 207  * Grant access to the given ring_mfn to the peer of the given device.
 208  * Return 0 on success, or errno on error.  On error, the device will
 209  * switch to XenbusStateClosing, and the error will be saved in the
 210  * store. The grant ring reference is returned in *refp.
 211  */
 212 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, int *refp);
 213
 214
 215 /**
 216  * Allocate an event channel for the given xenbus_device, assigning the newly
 217  * created local port to *port.  Return 0 on success, or errno on error.  On
 218  * error, the device will switch to XenbusStateClosing, and the error will be
 219  * saved in the store.
 220  */
 221 int xenbus_alloc_evtchn(device_t dev, int *port);
 222
 223
 224 /**
 225  * Free an existing event channel. Returns 0 on success or errno on error.
 226  */
 227 int xenbus_free_evtchn(device_t dev, int port);
 228
 229
 230 /**
 231  * Return the state of the driver rooted at the given store path, or
 232  * XenbusStateClosed if no state can be read.
 233  */
 234 XenbusState xenbus_read_driver_state(const char *path);
 235
 236
 237 /***
 238  * Report the given negative errno into the store, along with the given
 239  * formatted message.
 240  */
 241 void xenbus_dev_error(device_t dev, int err, const char *fmt,
 242                       ...);
 243
 244
 245 /***
 246  * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by
 247  * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly
 248  * closedown of this driver and its peer.
 249  */
 250 void xenbus_dev_fatal(device_t dev, int err, const char *fmt,
 251                       ...);
 252
 253 int xenbus_dev_init(void);
 254
 255 const char *xenbus_strstate(enum xenbus_state state);
 256 int xenbus_dev_is_online(device_t dev);
 257 int xenbus_frontend_closed(device_t dev);
 258
 259 #endif /* _XEN_XENBUS_XENBUSVAR_H */