sys/arch/xen/include/xenbus.h

   1 /* $NetBSD: xenbus.h,v 1.10 2008/10/24 21:09:24 jym Exp $ */
   2 /******************************************************************************
   3  * xenbus.h
   4  *
   5  * Talks to Xen Store to figure out what devices we have.
   6  *
   7  * Copyright (C) 2005 Rusty Russell, IBM Corporation
   8  * Copyright (C) 2005 XenSource Ltd.
   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
  32 #ifndef _ASM_XEN_XENBUS_H
  33 #define _ASM_XEN_XENBUS_H
  34
  35 #include <sys/device.h>
  36 #include <sys/queue.h>
  37 #include <xen/xen3-public/xen.h>
  38 #include <xen/xen3-public/io/xenbus.h>
  39 #include <xen/xen3-public/io/xs_wire.h>
  40 #include <xen/xen3-public/grant_table.h>        /* for grant_ref_t */
  41
  42 /* xenbus to hypervisor attach */
  43 struct xenbus_attach_args {
  44         const char              *xa_device;
  45         int                     xa_handle;
  46 };
  47
  48 /* devices to xenbus attach */
  49 struct xenbusdev_attach_args {
  50         const char              *xa_type;
  51         int                     xa_id;
  52         struct xenbus_device    *xa_xbusd;
  53 };
  54
  55 /* Register callback to watch this node. */
  56 struct xenbus_watch {
  57         SLIST_ENTRY(xenbus_watch) watch_next;
  58
  59         /* Path being watched. */
  60         char *node;
  61
  62         /* Callback (executed in a process context with no locks held). */
  63         void (*xbw_callback)(struct xenbus_watch *,
  64                          const char **vec, unsigned int len);
  65         struct xenbus_device *xbw_dev;
  66 };
  67
  68
  69 /*
  70  * A xenbus device. Note that the malloced memory will be larger than
  71  * sizeof(xenbus_device) to have the storage for xbusd_path, so xbusd_path
  72  * has to be the last entry.
  73  */
  74 typedef enum {
  75         XENBUS_FRONTEND_DEVICE,
  76         XENBUS_BACKEND_DEVICE
  77 } xenbusdev_type_t;
  78
  79 struct xenbus_device {
  80         SLIST_ENTRY(xenbus_device) xbusd_entries;
  81         char *xbusd_otherend; /* the otherend path */
  82         int xbusd_otherend_id; /* the otherend's id */
  83         /* callback for otherend change */
  84         void (*xbusd_otherend_changed)(void *, XenbusState);
  85         xenbusdev_type_t xbusd_type;
  86         union {
  87                 struct {
  88                         device_t f_dev;
  89                 } f;
  90                 struct {
  91                         void *b_cookie; /* private to backend driver */
  92                         int (*b_detach)(void *);
  93                 } b;
  94         } xbusd_u;
  95         int xbusd_has_error;
  96         /* for xenbus internal use */
  97         struct xenbus_watch xbusd_otherend_watch;
  98         const char xbusd_path[1]; /* our path */
  99 };
 100
 101 /*
 102  * frontend devices use the normal autoconf(9) framework to attach.
 103  * backend drivers need something more clever because we want the
 104  * domain's name or uid in the device's name. Each backend driver registers
 105  * to xenbus.
 106  */
 107
 108 struct xenbus_backend_driver {
 109         SLIST_ENTRY(xenbus_backend_driver) xbakd_entries;
 110         int (*xbakd_create) (struct xenbus_device *); /* called for new devs */
 111         const char *xbakd_type; /* device type we register for */
 112 };
 113
 114 void xenbus_backend_register(struct xenbus_backend_driver *);
 115
 116 struct xenbus_transaction;
 117
 118 int xenbus_directory(struct xenbus_transaction *t,
 119                         const char *dir, const char *node, unsigned int *num,
 120                         char ***);
 121 int xenbus_read(struct xenbus_transaction *t,
 122                   const char *dir, const char *node, unsigned int *len,
 123                   char **);
 124 int xenbus_read_ul(struct xenbus_transaction *,
 125                   const char *, const char *, unsigned long *, int);
 126 int xenbus_read_ull(struct xenbus_transaction *,
 127                   const char *, const char *, unsigned long long *, int);
 128 int xenbus_write(struct xenbus_transaction *t,
 129                  const char *dir, const char *node, const char *string);
 130 int xenbus_mkdir(struct xenbus_transaction *t,
 131                  const char *dir, const char *node);
 132 int xenbus_exists(struct xenbus_transaction *t,
 133                   const char *dir, const char *node);
 134 int xenbus_rm(struct xenbus_transaction *t, const char *dir, const char *node);
 135 struct xenbus_transaction *xenbus_transaction_start(void);
 136 int xenbus_transaction_end(struct xenbus_transaction *t, int abort);
 137
 138 /* Single read and scanf: returns -errno or num scanned if > 0. */
 139 int xenbus_scanf(struct xenbus_transaction *t,
 140                  const char *dir, const char *node, const char *fmt, ...)
 141         __attribute__((format(scanf, 4, 5)));
 142
 143 /* Single printf and write: returns -errno or 0. */
 144 int xenbus_printf(struct xenbus_transaction *t,
 145                   const char *dir, const char *node, const char *fmt, ...)
 146         __attribute__((format(printf, 4, 5)));
 147
 148 /* Generic read function: NULL-terminated triples of name,
 149  * sprintf-style type string, and pointer. Returns 0 or errno.*/
 150 int xenbus_gather(struct xenbus_transaction *t, const char *dir, ...);
 151
 152 /* notifer routines for when the xenstore comes up */
 153 // XXX int register_xenstore_notifier(struct notifier_block *nb);
 154 // XXX void unregister_xenstore_notifier(struct notifier_block *nb);
 155
 156 int register_xenbus_watch(struct xenbus_watch *watch);
 157 void unregister_xenbus_watch(struct xenbus_watch *watch);
 158 void xs_suspend(void);
 159 void xs_resume(void);
 160
 161 /* Used by xenbus_dev to borrow kernel's store connection. */
 162 int xenbus_dev_request_and_reply(struct xsd_sockmsg *msg, void **);
 163
 164 void xenbus_probe(void *);
 165
 166 int xenbus_free_device(struct xenbus_device *);
 167
 168 #define XENBUS_IS_ERR_READ(str) ({                      \
 169         if (!IS_ERR(str) && strlen(str) == 0) {         \
 170                 kfree(str);                             \
 171                 str = ERR_PTR(-ERANGE);                 \
 172         }                                               \
 173         IS_ERR(str);                                    \
 174 })
 175
 176 #define XENBUS_EXIST_ERR(err) ((err) == -ENOENT || (err) == -ERANGE)
 177
 178
 179 /**
 180  * Register a watch on the given path, using the given xenbus_watch structure
 181  * for storage, and the given callback function as the callback.  Return 0 on
 182  * success, or -errno on error.  On success, the given path will be saved as
 183  * watch->node, and remains the caller's to free.  On error, watch->node will
 184  * be NULL, the device will switch to XenbusStateClosing, and the error will
 185  * be saved in the store.
 186  */
 187 int xenbus_watch_path(struct xenbus_device *dev, char *path,
 188                       struct xenbus_watch *watch,
 189                       void (*callback)(struct xenbus_watch *,
 190                                        const char **, unsigned int));
 191
 192
 193 /**
 194  * Register a watch on the given path/path2, using the given xenbus_watch
 195  * structure for storage, and the given callback function as the callback.
 196  * Return 0 on success, or -errno on error.  On success, the watched path
 197  * (path/path2) will be saved as watch->node, and becomes the caller's to
 198  * kfree().  On error, watch->node will be NULL, so the caller has nothing to
 199  * free, the device will switch to XenbusStateClosing, and the error will be
 200  * saved in the store.
 201  */
 202 int xenbus_watch_path2(struct xenbus_device *dev, const char *path,
 203                        const char *path2, struct xenbus_watch *watch,
 204                        void (*callback)(struct xenbus_watch *,
 205                                         const char **, unsigned int));
 206
 207
 208 /**
 209  * Advertise in the store a change of the given driver to the given new_state.
 210  * Perform the change inside the given transaction xbt.  xbt may be NULL, in
 211  * which case this is performed inside its own transaction.  Return 0 on
 212  * success, or -errno on error.  On error, the device will switch to
 213  * XenbusStateClosing, and the error will be saved in the store.
 214  */
 215 int xenbus_switch_state(struct xenbus_device *dev,
 216                         struct xenbus_transaction *xbt,
 217                         XenbusState new_state);
 218
 219
 220 /**
 221  * Grant access to the given ring_mfn to the peer of the given device.  Return
 222  * 0 on success, or -errno on error.  On error, the device will switch to
 223  * XenbusStateClosing, and the error will be saved in the store.
 224  */
 225 int xenbus_grant_ring(struct xenbus_device *, paddr_t, grant_ref_t *);
 226
 227
 228 /**
 229  * Allocate an event channel for the given xenbus_device, assigning the newly
 230  * created local port to *port.  Return 0 on success, or -errno on error.  On
 231  * error, the device will switch to XenbusStateClosing, and the error will be
 232  * saved in the store.
 233  */
 234 int xenbus_alloc_evtchn(struct xenbus_device *dev, int *port);
 235
 236
 237 /**
 238  * Return the state of the driver rooted at the given store path, or
 239  * XenbusStateClosed if no state can be read.
 240  */
 241 XenbusState xenbus_read_driver_state(const char *path);
 242
 243
 244 /***
 245  * Report the given negative errno into the store, along with the given
 246  * formatted message.
 247  */
 248 void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt,
 249                       ...);
 250
 251
 252 /***
 253  * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by
 254  * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly
 255  * closedown of this driver and its peer.
 256  */
 257 void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt,
 258                       ...);
 259
 260
 261 #endif /* _ASM_XEN_XENBUS_H */
 262
 263 /*
 264  * Local variables:
 265  *  c-file-style: "linux"
 266  *  indent-tabs-mode: t
 267  *  c-indent-level: 8
 268  *  c-basic-offset: 8
 269  *  tab-width: 8
 270  * End:
 271  */