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
  47 #include <xen/xen-os.h>
  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 /* XenBus allocations including XenStore data returned to clients. */
  55 MALLOC_DECLARE(M_XENBUS);
  56
  57 enum {
  58         /**
  59          * Path of this device node.
  60          */
  61         XENBUS_IVAR_NODE,
  62
  63         /**
  64          * The device type (e.g. vif, vbd).
  65          */
  66         XENBUS_IVAR_TYPE,
  67
  68         /**
  69          * The state of this device (not the otherend's state).
  70          */
  71         XENBUS_IVAR_STATE,
  72
  73         /**
  74          * Domain ID of the other end device.
  75          */
  76         XENBUS_IVAR_OTHEREND_ID,
  77
  78         /**
  79          * Path of the other end device.
  80          */
  81         XENBUS_IVAR_OTHEREND_PATH
  82 };
  83
  84 /**
  85  * Simplified accessors for xenbus devices:
  86  *
  87  * xenbus_get_node
  88  * xenbus_get_type
  89  * xenbus_get_state
  90  * xenbus_get_otherend_id
  91  * xenbus_get_otherend_path
  92  */
  93 #define XENBUS_ACCESSOR(var, ivar, type) \
  94         __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
  95
  96 XENBUS_ACCESSOR(node,           NODE,                   const char *)
  97 XENBUS_ACCESSOR(type,           TYPE,                   const char *)
  98 XENBUS_ACCESSOR(state,          STATE,                  enum xenbus_state)
  99 XENBUS_ACCESSOR(otherend_id,    OTHEREND_ID,            int)
 100 XENBUS_ACCESSOR(otherend_path,  OTHEREND_PATH,          const char *)
 101
 102 /**
 103  * Return the state of a XenBus device.
 104  *
 105  * \param path  The root XenStore path for the device.
 106  *
 107  * \return  The current state of the device or XenbusStateClosed if no
 108  *          state can be read.
 109  */
 110 XenbusState xenbus_read_driver_state(const char *path);
 111
 112 /**
 113  * Return the state of the "other end" (peer) of a XenBus device.
 114  *
 115  * \param dev   The XenBus device whose peer to query.
 116  *
 117  * \return  The current state of the peer device or XenbusStateClosed if no
 118  *          state can be read.
 119  */
 120 static inline XenbusState
 121 xenbus_get_otherend_state(device_t dev)
 122 {
 123         return (xenbus_read_driver_state(xenbus_get_otherend_path(dev)));
 124 }
 125
 126 /**
 127  * Grant access to the given ring_mfn to the peer of the given device.
 128  *
 129  * \param dev        The device granting access to the ring page.
 130  * \param ring_mfn   The guest machine page number of the page to grant
 131  *                   peer access rights.
 132  * \param refp[out]  The grant reference for the page.
 133  *
 134  * \return  On success, 0. Otherwise an errno value indicating the
 135  *          type of failure.
 136  *
 137  * A successful call to xenbus_grant_ring should be paired with a call
 138  * to gnttab_end_foreign_access() when foregn access to this page is no
 139  * longer requried.
 140  *
 141  * \note  On error, \a dev will be switched to the XenbusStateClosing
 142  *        state and the returned error is saved in the per-device error node
 143  *        for \a dev in the XenStore.
 144  */
 145 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp);
 146
 147 /**
 148  * Record the given errno, along with the given, printf-style, formatted
 149  * message in dev's device specific error node in the XenStore.
 150  *
 151  * \param dev  The device which encountered the error.
 152  * \param err  The errno value corresponding to the error.
 153  * \param fmt  Printf format string followed by a variable number of
 154  *             printf arguments.
 155  */
 156 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...)
 157         __attribute__((format(printf, 3, 4)));
 158
 159 /**
 160  * va_list version of xenbus_dev_error().
 161  *
 162  * \param dev  The device which encountered the error.
 163  * \param err  The errno value corresponding to the error.
 164  * \param fmt  Printf format string.
 165  * \param ap   Va_list of printf arguments.
 166  */
 167 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap)
 168         __attribute__((format(printf, 3, 0)));
 169
 170 /**
 171  * Equivalent to xenbus_dev_error(), followed by
 172  * xenbus_set_state(dev, XenbusStateClosing).
 173  *
 174  * \param dev  The device which encountered the error.
 175  * \param err  The errno value corresponding to the error.
 176  * \param fmt  Printf format string followed by a variable number of
 177  *             printf arguments.
 178  */
 179 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...)
 180         __attribute__((format(printf, 3, 4)));
 181
 182 /**
 183  * va_list version of xenbus_dev_fatal().
 184  *
 185  * \param dev  The device which encountered the error.
 186  * \param err  The errno value corresponding to the error.
 187  * \param fmt  Printf format string.
 188  * \param ap   Va_list of printf arguments.
 189  */
 190 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list)
 191         __attribute__((format(printf, 3, 0)));
 192
 193 /**
 194  * Convert a member of the xenbus_state enum into an ASCII string.
 195  *
 196  * /param state  The XenBus state to lookup.
 197  *
 198  * /return  A string representing state or, for unrecognized states,
 199  *          the string "Unknown".
 200  */
 201 const char *xenbus_strstate(enum xenbus_state state);
 202
 203 /**
 204  * Return the value of a XenBus device's "online" node within the XenStore.
 205  *
 206  * \param dev  The XenBus device to query.
 207  *
 208  * \return  The value of the "online" node for the device.  If the node
 209  *          does not exist, 0 (offline) is returned.
 210  */
 211 int xenbus_dev_is_online(device_t dev);
 212
 213 /**
 214  * Default callback invoked when a change to the local XenStore sub-tree
 215  * for a device is modified.
 216  *
 217  * \param dev   The XenBus device whose tree was modified.
 218  * \param path  The tree relative sub-path to the modified node.  The empty
 219  *              string indicates the root of the tree was destroyed.
 220  */
 221 void xenbus_localend_changed(device_t dev, const char *path);
 222
 223 #include "xenbus_if.h"
 224
 225 #endif /* _XEN_XENBUS_XENBUSVAR_H */