sys/xen/xenbus/xenbusvar.h

   1 /******************************************************************************
   2  * Copyright (C) 2005 Rusty Russell, IBM Corporation
   3  * Copyright (C) 2005 XenSource Ltd.
   4  *
   5  * This file may be distributed separately from the Linux kernel, or
   6  * incorporated into other software packages, subject to the following license:
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this source file (the "Software"), to deal in the Software without
  10  * restriction, including without limitation the rights to use, copy, modify,
  11  * merge, publish, distribute, sublicense, and/or sell copies of the Software,
  12  * and to permit persons to whom the Software is furnished to do so, subject to
  13  * the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  23  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  24  * IN THE SOFTWARE.
  25  *
  26  * $FreeBSD$
  27  */
  28
  29 /**
  30  * \file xenbusvar.h
  31  *
  32  * \brief Datastructures and function declarations for usedby device
  33  *        drivers operating on the XenBus.
  34  */
  35
  36 #ifndef _XEN_XENBUS_XENBUSVAR_H
  37 #define _XEN_XENBUS_XENBUSVAR_H
  38
  39 #include <sys/queue.h>
  40 #include <sys/bus.h>
  41 #include <sys/eventhandler.h>
  42 #include <sys/malloc.h>
  43 #include <sys/sbuf.h>
  44
  45 #include <machine/stdarg.h>
  46 #include <machine/xen/xen-os.h>
  47
  48 #include <xen/interface/grant_table.h>
  49 #include <xen/interface/io/xenbus.h>
  50 #include <xen/interface/io/xs_wire.h>
  51
  52 #include <xen/xenstore/xenstorevar.h>
  53
  54 #include "xenbus_if.h"
  55
  56 /* XenBus allocations including XenStore data returned to clients. */
  57 MALLOC_DECLARE(M_XENBUS);
  58
  59 enum {
  60         /**
  61          * Path of this device node.
  62          */
  63         XENBUS_IVAR_NODE,
  64
  65         /**
  66          * The device type (e.g. vif, vbd).
  67          */
  68         XENBUS_IVAR_TYPE,
  69
  70         /**
  71          * The state of this device (not the otherend's state).
  72          */
  73         XENBUS_IVAR_STATE,
  74
  75         /**
  76          * Domain ID of the other end device.
  77          */
  78         XENBUS_IVAR_OTHEREND_ID,
  79
  80         /**
  81          * Path of the other end device.
  82          */
  83         XENBUS_IVAR_OTHEREND_PATH
  84 };
  85
  86 /**
  87  * Simplified accessors for xenbus devices
  88  */
  89 #define XENBUS_ACCESSOR(var, ivar, type) \
  90         __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
  91
  92 XENBUS_ACCESSOR(node,           NODE,                   const char *)
  93 XENBUS_ACCESSOR(type,           TYPE,                   const char *)
  94 XENBUS_ACCESSOR(state,          STATE,                  enum xenbus_state)
  95 XENBUS_ACCESSOR(otherend_id,    OTHEREND_ID,            int)
  96 XENBUS_ACCESSOR(otherend_path,  OTHEREND_PATH,          const char *)
  97
  98 /**
  99  * Return the state of a XenBus device.
 100  *
 101  * \param path  The root XenStore path for the device.
 102  *
 103  * \return  The current state of the device or XenbusStateClosed if no
 104  *          state can be read.
 105  */
 106 XenbusState xenbus_read_driver_state(const char *path);
 107
 108 /**
 109  * Initialize and register a watch on the given path (client suplied storage).
 110  *
 111  * \param dev       The XenBus device requesting the watch service.
 112  * \param path      The XenStore path of the object to be watched.  The
 113  *                  storage for this string must be stable for the lifetime
 114  *                  of the watch.
 115  * \param watch     The watch object to use for this request.  This object
 116  *                  must be stable for the lifetime of the watch.
 117  * \param callback  The function to call when XenStore objects at or below
 118  *                  path are modified.
 119  *
 120  * \return  On success, 0. Otherwise an errno value indicating the
 121  *          type of failure.
 122  *
 123  * \note  On error, the device 'dev' will be switched to the XenbusStateClosing
 124  *        state and the returned error is saved in the per-device error node
 125  *        for dev in the XenStore.
 126  */
 127 int xenbus_watch_path(device_t dev, char *path,
 128                       struct xs_watch *watch,
 129                       xs_watch_cb_t *callback);
 130
 131 /**
 132  * Initialize and register a watch at path/path2 in the XenStore.
 133  *
 134  * \param dev       The XenBus device requesting the watch service.
 135  * \param path      The base XenStore path of the object to be watched.
 136  * \param path2     The tail XenStore path of the object to be watched.
 137  * \param watch     The watch object to use for this request.  This object
 138  *                  must be stable for the lifetime of the watch.
 139  * \param callback  The function to call when XenStore objects at or below
 140  *                  path are modified.
 141  *
 142  * \return  On success, 0. Otherwise an errno value indicating the
 143  *          type of failure.
 144  *
 145  * \note  On error, \a dev will be switched to the XenbusStateClosing
 146  *        state and the returned error is saved in the per-device error node
 147  *        for \a dev in the XenStore.
 148  *
 149  * Similar to xenbus_watch_path, however the storage for the path to the
 150  * watched object is allocated from the heap and filled with "path '/' path2".
 151  * Should a call to this function succeed, it is the callers responsibility
 152  * to free watch->node using the M_XENBUS malloc type.
 153  */
 154 int xenbus_watch_path2(device_t dev, const char *path,
 155                        const char *path2, struct xs_watch *watch,
 156                        xs_watch_cb_t *callback);
 157
 158 /**
 159  * Grant access to the given ring_mfn to the peer of the given device.
 160  *
 161  * \param dev        The device granting access to the ring page.
 162  * \param ring_mfn   The guest machine page number of the page to grant
 163  *                   peer access rights.
 164  * \param refp[out]  The grant reference for the page.
 165  *
 166  * \return  On success, 0. Otherwise an errno value indicating the
 167  *          type of failure.
 168  *
 169  * A successful call to xenbus_grant_ring should be paired with a call
 170  * to gnttab_end_foreign_access() when foregn access to this page is no
 171  * longer requried.
 172  *
 173  * \note  On error, \a dev will be switched to the XenbusStateClosing
 174  *        state and the returned error is saved in the per-device error node
 175  *        for \a dev in the XenStore.
 176  */
 177 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp);
 178
 179 /**
 180  * Allocate an event channel for the given XenBus device.
 181  *
 182  * \param dev        The device for which to allocate the event channel.
 183  * \param port[out]  The port identifier for the allocated event channel.
 184  *
 185  * \return  On success, 0. Otherwise an errno value indicating the
 186  *          type of failure.
 187  *
 188  * A successfully allocated event channel should be free'd using
 189  * xenbus_free_evtchn().
 190  *
 191  * \note  On error, \a dev will be switched to the XenbusStateClosing
 192  *        state and the returned error is saved in the per-device error node
 193  *        for \a dev in the XenStore.
 194  */
 195 int xenbus_alloc_evtchn(device_t dev, evtchn_port_t *port);
 196
 197 /**
 198  * Free an existing event channel.
 199  *
 200  * \param dev   The device which allocated this event channel.
 201  * \param port  The port identifier for the event channel to free.
 202  *
 203  * \return  On success, 0. Otherwise an errno value indicating the
 204  *          type of failure.
 205  *
 206  * \note  On error, \a dev will be switched to the XenbusStateClosing
 207  *        state and the returned error is saved in the per-device error node
 208  *        for \a dev in the XenStore.
 209  */
 210 int xenbus_free_evtchn(device_t dev, evtchn_port_t port);
 211
 212 /**
 213  * Record the given errno, along with the given, printf-style, formatted
 214  * message in dev's device specific error node in the XenStore.
 215  *
 216  * \param dev  The device which encountered the error.
 217  * \param err  The errno value corresponding to the error.
 218  * \param fmt  Printf format string followed by a variable number of
 219  *             printf arguments.
 220  */
 221 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...)
 222         __attribute__((format(printf, 3, 4)));
 223
 224 /**
 225  * va_list version of xenbus_dev_error().
 226  *
 227  * \param dev  The device which encountered the error.
 228  * \param err  The errno value corresponding to the error.
 229  * \param fmt  Printf format string.
 230  * \param ap   Va_list of printf arguments.
 231  */
 232 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap)
 233         __attribute__((format(printf, 3, 0)));
 234
 235 /**
 236  * Equivalent to xenbus_dev_error(), followed by
 237  * xenbus_set_state(dev, XenbusStateClosing).
 238  *
 239  * \param dev  The device which encountered the error.
 240  * \param err  The errno value corresponding to the error.
 241  * \param fmt  Printf format string followed by a variable number of
 242  *             printf arguments.
 243  */
 244 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...)
 245         __attribute__((format(printf, 3, 4)));
 246
 247 /**
 248  * va_list version of xenbus_dev_fatal().
 249  *
 250  * \param dev  The device which encountered the error.
 251  * \param err  The errno value corresponding to the error.
 252  * \param fmt  Printf format string.
 253  * \param ap   Va_list of printf arguments.
 254  */
 255 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list)
 256         __attribute__((format(printf, 3, 0)));
 257
 258 /**
 259  * Convert a member of the xenbus_state enum into an ASCII string.
 260  *
 261  * /param state  The XenBus state to lookup.
 262  *
 263  * /return  A string representing state or, for unrecognized states,
 264  *          the string "Unknown".
 265  */
 266 const char *xenbus_strstate(enum xenbus_state state);
 267
 268 /**
 269  * Return the value of a XenBus device's "online" node within the XenStore.
 270  *
 271  * \param dev  The XenBus device to query.
 272  *
 273  * \return  The value of the "online" node for the device.  If the node
 274  *          does not exist, 0 (offline) is returned.
 275  */
 276 int xenbus_dev_is_online(device_t dev);
 277
 278 #endif /* _XEN_XENBUS_XENBUSVAR_H */