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