include/xen/xenbus.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 program is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU General Public License version 2
  11  * as published by the Free Software Foundation; or, when distributed
  12  * separately from the Linux kernel or incorporated into other
  13  * software packages, subject to the following license:
  14  *
  15  * Permission is hereby granted, free of charge, to any person obtaining a copy
  16  * of this source file (the "Software"), to deal in the Software without
  17  * restriction, including without limitation the rights to use, copy, modify,
  18  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  19  * and to permit persons to whom the Software is furnished to do so, subject to
  20  * the following conditions:
  21  *
  22  * The above copyright notice and this permission notice shall be included in
  23  * all copies or substantial portions of the Software.
  24  *
  25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  26  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  27  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  28  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  29  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  30  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  31  * IN THE SOFTWARE.
  32  */
  33
  34 #ifndef _XEN_XENBUS_H
  35 #define _XEN_XENBUS_H
  36
  37 #include <linux/device.h>
  38 #include <linux/notifier.h>
  39 #include <linux/mutex.h>
  40 #include <xen/interface/xen.h>
  41 #include <xen/interface/grant_table.h>
  42 #include <xen/interface/io/xenbus.h>
  43 #include <xen/interface/io/xs_wire.h>
  44
  45 /* Register callback to watch this node. */
  46 struct xenbus_watch
  47 {
  48         struct list_head list;
  49
  50         /* Path being watched. */
  51         const char *node;
  52
  53         /* Callback (executed in a process context with no locks held). */
  54         void (*callback)(struct xenbus_watch *,
  55                          const char **vec, unsigned int len);
  56
  57         /* See XBWF_ definitions below. */
  58         unsigned long flags;
  59 };
  60
  61 /*
  62  * Execute callback in its own kthread. Useful if the callback is long
  63  * running or heavily serialised, to avoid taking out the main xenwatch thread
  64  * for a long period of time (or even unwittingly causing a deadlock).
  65  */
  66 #define XBWF_new_thread 1
  67
  68 /* A xenbus device. */
  69 struct xenbus_device {
  70         const char *devicetype;
  71         const char *nodename;
  72         const char *otherend;
  73         int otherend_id;
  74         struct xenbus_watch otherend_watch;
  75         struct device dev;
  76         enum xenbus_state state;
  77 };
  78
  79 static inline struct xenbus_device *to_xenbus_device(struct device *dev)
  80 {
  81         return container_of(dev, struct xenbus_device, dev);
  82 }
  83
  84 struct xenbus_device_id
  85 {
  86         /* .../device/<device_type>/<identifier> */
  87         char devicetype[32];    /* General class of device. */
  88 };
  89
  90 /* A xenbus driver. */
  91 struct xenbus_driver {
  92         char *name;
  93         struct module *owner;
  94         const struct xenbus_device_id *ids;
  95         int (*probe)(struct xenbus_device *dev,
  96                      const struct xenbus_device_id *id);
  97         void (*otherend_changed)(struct xenbus_device *dev,
  98                                  enum xenbus_state backend_state);
  99         int (*remove)(struct xenbus_device *dev);
 100         int (*suspend)(struct xenbus_device *dev);
 101         int (*resume)(struct xenbus_device *dev);
 102         int (*uevent)(struct xenbus_device *, char **, int, char *, int);
 103         struct device_driver driver;
 104         int (*read_otherend_details)(struct xenbus_device *dev);
 105 };
 106
 107 static inline struct xenbus_driver *to_xenbus_driver(struct device_driver *drv)
 108 {
 109         return container_of(drv, struct xenbus_driver, driver);
 110 }
 111
 112 int xenbus_register_frontend(struct xenbus_driver *drv);
 113 int xenbus_register_backend(struct xenbus_driver *drv);
 114 void xenbus_unregister_driver(struct xenbus_driver *drv);
 115
 116 struct xenbus_transaction
 117 {
 118         u32 id;
 119 };
 120
 121 /* Nil transaction ID. */
 122 #define XBT_NIL ((struct xenbus_transaction) { 0 })
 123
 124 char **xenbus_directory(struct xenbus_transaction t,
 125                         const char *dir, const char *node, unsigned int *num);
 126 void *xenbus_read(struct xenbus_transaction t,
 127                   const char *dir, const char *node, unsigned int *len);
 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 int xenbus_transaction_start(struct xenbus_transaction *t);
 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 int register_xenstore_notifier(struct notifier_block *nb);
 154 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 void *xenbus_dev_request_and_reply(struct xsd_sockmsg *msg);
 163
 164 /* Called from xen core code. */
 165 void xenbus_suspend(void);
 166 void xenbus_resume(void);
 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, const 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  * Return 0 on success, or -errno on error.  On error, the device will switch
 211  * to XenbusStateClosing, and the error will be saved in the store.
 212  */
 213 int xenbus_switch_state(struct xenbus_device *dev, enum xenbus_state new_state);
 214
 215
 216 /**
 217  * Grant access to the given ring_mfn to the peer of the given device.  Return
 218  * 0 on success, or -errno on error.  On error, the device will switch to
 219  * XenbusStateClosing, and the error will be saved in the store.
 220  */
 221 int xenbus_grant_ring(struct xenbus_device *dev, unsigned long ring_mfn);
 222
 223
 224 /**
 225  * Map a page of memory into this domain from another domain's grant table.
 226  * xenbus_map_ring_valloc allocates a page of virtual address space, maps the
 227  * page to that address, and sets *vaddr to that address.
 228  * xenbus_map_ring does not allocate the virtual address space (you must do
 229  * this yourself!). It only maps in the page to the specified address.
 230  * Returns 0 on success, and GNTST_* (see xen/include/interface/grant_table.h)
 231  * or -ENOMEM on error. If an error is returned, device will switch to
 232  * XenbusStateClosing and the error message will be saved in XenStore.
 233  */
 234 struct vm_struct *xenbus_map_ring_valloc(struct xenbus_device *dev,
 235                                          int gnt_ref);
 236 int xenbus_map_ring(struct xenbus_device *dev, int gnt_ref,
 237                            grant_handle_t *handle, void *vaddr);
 238
 239
 240 /**
 241  * Unmap a page of memory in this domain that was imported from another domain.
 242  * Use xenbus_unmap_ring_vfree if you mapped in your memory with
 243  * xenbus_map_ring_valloc (it will free the virtual address space).
 244  * Returns 0 on success and returns GNTST_* on error
 245  * (see xen/include/interface/grant_table.h).
 246  */
 247 int xenbus_unmap_ring_vfree(struct xenbus_device *dev, struct vm_struct *);
 248 int xenbus_unmap_ring(struct xenbus_device *dev,
 249                       grant_handle_t handle, void *vaddr);
 250
 251
 252 /**
 253  * Allocate an event channel for the given xenbus_device, assigning the newly
 254  * created local port to *port.  Return 0 on success, or -errno on error.  On
 255  * error, the device will switch to XenbusStateClosing, and the error will be
 256  * saved in the store.
 257  */
 258 int xenbus_alloc_evtchn(struct xenbus_device *dev, int *port);
 259
 260
 261 /**
 262  * Bind to an existing interdomain event channel in another domain. Returns 0
 263  * on success and stores the local port in *port. On error, returns -errno,
 264  * switches the device to XenbusStateClosing, and saves the error in XenStore.
 265  */
 266 int xenbus_bind_evtchn(struct xenbus_device *dev, int remote_port, int *port);
 267
 268
 269 /**
 270  * Free an existing event channel. Returns 0 on success or -errno on error.
 271  */
 272 int xenbus_free_evtchn(struct xenbus_device *dev, int port);
 273
 274
 275 /**
 276  * Return the state of the driver rooted at the given store path, or
 277  * XenbusStateClosed if no state can be read.
 278  */
 279 enum xenbus_state xenbus_read_driver_state(const char *path);
 280
 281
 282 /***
 283  * Report the given negative errno into the store, along with the given
 284  * formatted message.
 285  */
 286 void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt,
 287                       ...);
 288
 289
 290 /***
 291  * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by
 292  * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly
 293  * closedown of this driver and its peer.
 294  */
 295 void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt,
 296                       ...);
 297
 298
 299 #endif /* _XEN_XENBUS_H */