xenbusvar.h revision 214077
1187214Srwatson/****************************************************************************** 2187214Srwatson * Copyright (C) 2005 Rusty Russell, IBM Corporation 3187214Srwatson * Copyright (C) 2005 XenSource Ltd. 4187214Srwatson * 5187214Srwatson * This file may be distributed separately from the Linux kernel, or 6187214Srwatson * incorporated into other software packages, subject to the following license: 7187214Srwatson * 8187214Srwatson * Permission is hereby granted, free of charge, to any person obtaining a copy 9187214Srwatson * of this source file (the "Software"), to deal in the Software without 10187214Srwatson * restriction, including without limitation the rights to use, copy, modify, 11187214Srwatson * merge, publish, distribute, sublicense, and/or sell copies of the Software, 12187214Srwatson * and to permit persons to whom the Software is furnished to do so, subject to 13187214Srwatson * the following conditions: 14187214Srwatson * 15187214Srwatson * The above copyright notice and this permission notice shall be included in 16187214Srwatson * all copies or substantial portions of the Software. 17187214Srwatson * 18187214Srwatson * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19187214Srwatson * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20187214Srwatson * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21187214Srwatson * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22187214Srwatson * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23187214Srwatson * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 24187214Srwatson * IN THE SOFTWARE. 25187214Srwatson * 26187214Srwatson * $FreeBSD: head/sys/xen/xenbus/xenbusvar.h 214077 2010-10-19 20:53:30Z gibbs $ 27187214Srwatson */ 28187214Srwatson 29191273Srwatson/** 30187214Srwatson * \file xenbusvar.h 31187214Srwatson * 32187214Srwatson * \brief Datastructures and function declarations for usedby device 33187214Srwatson * drivers operating on the XenBus. 34187214Srwatson */ 35187214Srwatson 36187214Srwatson#ifndef _XEN_XENBUS_XENBUSVAR_H 37187214Srwatson#define _XEN_XENBUS_XENBUSVAR_H 38187214Srwatson 39187214Srwatson#include <sys/queue.h> 40187214Srwatson#include <sys/bus.h> 41187214Srwatson#include <sys/eventhandler.h> 42187214Srwatson#include <sys/malloc.h> 43187214Srwatson#include <sys/sbuf.h> 44187214Srwatson 45187214Srwatson#include <machine/stdarg.h> 46187214Srwatson#include <machine/xen/xen-os.h> 47187214Srwatson 48187214Srwatson#include <xen/interface/grant_table.h> 49187214Srwatson#include <xen/interface/io/xenbus.h> 50187214Srwatson#include <xen/interface/io/xs_wire.h> 51187214Srwatson 52187214Srwatson#include <xen/xenstore/xenstorevar.h> 53187214Srwatson 54187214Srwatson#include "xenbus_if.h" 55187214Srwatson 56187214Srwatson/* XenBus allocations including XenStore data returned to clients. */ 57187214SrwatsonMALLOC_DECLARE(M_XENBUS); 58187214Srwatson 59187214Srwatsonenum { 60187214Srwatson /** 61187214Srwatson * Path of this device node. 62187214Srwatson */ 63187214Srwatson XENBUS_IVAR_NODE, 64187214Srwatson 65187214Srwatson /** 66187214Srwatson * The device type (e.g. vif, vbd). 67187214Srwatson */ 68187214Srwatson XENBUS_IVAR_TYPE, 69187214Srwatson 70187214Srwatson /** 71187214Srwatson * The state of this device (not the otherend's state). 72187214Srwatson */ 73187214Srwatson XENBUS_IVAR_STATE, 74187214Srwatson 75187214Srwatson /** 76187214Srwatson * Domain ID of the other end device. 77187214Srwatson */ 78187214Srwatson XENBUS_IVAR_OTHEREND_ID, 79187214Srwatson 80187214Srwatson /** 81187214Srwatson * Path of the other end device. 82187214Srwatson */ 83187214Srwatson XENBUS_IVAR_OTHEREND_PATH 84187214Srwatson}; 85187214Srwatson 86187214Srwatson/** 87187214Srwatson * Simplified accessors for xenbus devices 88187214Srwatson */ 89187214Srwatson#define XENBUS_ACCESSOR(var, ivar, type) \ 90187214Srwatson __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type) 91191273Srwatson 92187214SrwatsonXENBUS_ACCESSOR(node, NODE, const char *) 93187214SrwatsonXENBUS_ACCESSOR(type, TYPE, const char *) 94187214SrwatsonXENBUS_ACCESSOR(state, STATE, enum xenbus_state) 95187214SrwatsonXENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int) 96187214SrwatsonXENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *) 97187214Srwatson 98187214Srwatson/** 99187214Srwatson * Return the state of a XenBus device. 100187214Srwatson * 101187214Srwatson * \param path The root XenStore path for the device. 102187214Srwatson * 103187214Srwatson * \return The current state of the device or XenbusStateClosed if no 104187214Srwatson * state can be read. 105187214Srwatson */ 106187214SrwatsonXenbusState xenbus_read_driver_state(const char *path); 107187214Srwatson 108187214Srwatson/** 109187214Srwatson * Initialize and register a watch on the given path (client suplied storage). 110187214Srwatson * 111187214Srwatson * \param dev The XenBus device requesting the watch service. 112187214Srwatson * \param path The XenStore path of the object to be watched. The 113187214Srwatson * storage for this string must be stable for the lifetime 114187214Srwatson * of the watch. 115187214Srwatson * \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 */ 127int 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 */ 154int 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 */ 177int 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 */ 195int 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 */ 210int 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 */ 221void 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 */ 232void 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 */ 244void 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 */ 255void 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 */ 266const 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 */ 276int xenbus_dev_is_online(device_t dev); 277 278#endif /* _XEN_XENBUS_XENBUSVAR_H */ 279