xenbusvar.h revision 214077
1185605Skmacy/****************************************************************************** 2185605Skmacy * Copyright (C) 2005 Rusty Russell, IBM Corporation 3185605Skmacy * Copyright (C) 2005 XenSource Ltd. 4185605Skmacy * 5185605Skmacy * This file may be distributed separately from the Linux kernel, or 6185605Skmacy * incorporated into other software packages, subject to the following license: 7185605Skmacy * 8185605Skmacy * Permission is hereby granted, free of charge, to any person obtaining a copy 9185605Skmacy * of this source file (the "Software"), to deal in the Software without 10185605Skmacy * restriction, including without limitation the rights to use, copy, modify, 11185605Skmacy * merge, publish, distribute, sublicense, and/or sell copies of the Software, 12185605Skmacy * and to permit persons to whom the Software is furnished to do so, subject to 13185605Skmacy * the following conditions: 14185605Skmacy * 15185605Skmacy * The above copyright notice and this permission notice shall be included in 16185605Skmacy * all copies or substantial portions of the Software. 17185605Skmacy * 18185605Skmacy * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19185605Skmacy * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20185605Skmacy * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21185605Skmacy * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22185605Skmacy * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23185605Skmacy * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 24185605Skmacy * IN THE SOFTWARE. 25185605Skmacy * 26185605Skmacy * $FreeBSD: head/sys/xen/xenbus/xenbusvar.h 214077 2010-10-19 20:53:30Z gibbs $ 27185605Skmacy */ 28185605Skmacy 29214077Sgibbs/** 30214077Sgibbs * \file xenbusvar.h 31214077Sgibbs * 32214077Sgibbs * \brief Datastructures and function declarations for usedby device 33214077Sgibbs * drivers operating on the XenBus. 34214077Sgibbs */ 35214077Sgibbs 36185605Skmacy#ifndef _XEN_XENBUS_XENBUSVAR_H 37185605Skmacy#define _XEN_XENBUS_XENBUSVAR_H 38185605Skmacy 39185605Skmacy#include <sys/queue.h> 40185605Skmacy#include <sys/bus.h> 41185605Skmacy#include <sys/eventhandler.h> 42214077Sgibbs#include <sys/malloc.h> 43214077Sgibbs#include <sys/sbuf.h> 44214077Sgibbs 45214077Sgibbs#include <machine/stdarg.h> 46185605Skmacy#include <machine/xen/xen-os.h> 47214077Sgibbs 48214077Sgibbs#include <xen/interface/grant_table.h> 49185605Skmacy#include <xen/interface/io/xenbus.h> 50185605Skmacy#include <xen/interface/io/xs_wire.h> 51185605Skmacy 52214077Sgibbs#include <xen/xenstore/xenstorevar.h> 53214077Sgibbs 54185605Skmacy#include "xenbus_if.h" 55185605Skmacy 56214077Sgibbs/* XenBus allocations including XenStore data returned to clients. */ 57214077SgibbsMALLOC_DECLARE(M_XENBUS); 58214077Sgibbs 59185605Skmacyenum { 60214077Sgibbs /** 61185605Skmacy * Path of this device node. 62185605Skmacy */ 63185605Skmacy XENBUS_IVAR_NODE, 64185605Skmacy 65214077Sgibbs /** 66185605Skmacy * The device type (e.g. vif, vbd). 67185605Skmacy */ 68185605Skmacy XENBUS_IVAR_TYPE, 69185605Skmacy 70214077Sgibbs /** 71185605Skmacy * The state of this device (not the otherend's state). 72185605Skmacy */ 73185605Skmacy XENBUS_IVAR_STATE, 74185605Skmacy 75214077Sgibbs /** 76185605Skmacy * Domain ID of the other end device. 77185605Skmacy */ 78185605Skmacy XENBUS_IVAR_OTHEREND_ID, 79185605Skmacy 80214077Sgibbs /** 81185605Skmacy * Path of the other end device. 82185605Skmacy */ 83185605Skmacy XENBUS_IVAR_OTHEREND_PATH 84185605Skmacy}; 85185605Skmacy 86214077Sgibbs/** 87185605Skmacy * Simplified accessors for xenbus devices 88185605Skmacy */ 89185605Skmacy#define XENBUS_ACCESSOR(var, ivar, type) \ 90185605Skmacy __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type) 91185605Skmacy 92185605SkmacyXENBUS_ACCESSOR(node, NODE, const char *) 93185605SkmacyXENBUS_ACCESSOR(type, TYPE, const char *) 94185605SkmacyXENBUS_ACCESSOR(state, STATE, enum xenbus_state) 95185605SkmacyXENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int) 96185605SkmacyXENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *) 97185605Skmacy 98214077Sgibbs/** 99214077Sgibbs * Return the state of a XenBus device. 100214077Sgibbs * 101214077Sgibbs * \param path The root XenStore path for the device. 102214077Sgibbs * 103214077Sgibbs * \return The current state of the device or XenbusStateClosed if no 104214077Sgibbs * state can be read. 105186557Skmacy */ 106214077SgibbsXenbusState xenbus_read_driver_state(const char *path); 107185605Skmacy 108185605Skmacy/** 109214077Sgibbs * Initialize and register a watch on the given path (client suplied storage). 110214077Sgibbs * 111214077Sgibbs * \param dev The XenBus device requesting the watch service. 112214077Sgibbs * \param path The XenStore path of the object to be watched. The 113214077Sgibbs * storage for this string must be stable for the lifetime 114214077Sgibbs * of the watch. 115214077Sgibbs * \param watch The watch object to use for this request. This object 116214077Sgibbs * must be stable for the lifetime of the watch. 117214077Sgibbs * \param callback The function to call when XenStore objects at or below 118214077Sgibbs * path are modified. 119214077Sgibbs * 120214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 121214077Sgibbs * type of failure. 122214077Sgibbs * 123214077Sgibbs * \note On error, the device 'dev' will be switched to the XenbusStateClosing 124214077Sgibbs * state and the returned error is saved in the per-device error node 125214077Sgibbs * for dev in the XenStore. 126185605Skmacy */ 127185605Skmacyint xenbus_watch_path(device_t dev, char *path, 128214077Sgibbs struct xs_watch *watch, 129214077Sgibbs xs_watch_cb_t *callback); 130185605Skmacy 131185605Skmacy/** 132214077Sgibbs * Initialize and register a watch at path/path2 in the XenStore. 133214077Sgibbs * 134214077Sgibbs * \param dev The XenBus device requesting the watch service. 135214077Sgibbs * \param path The base XenStore path of the object to be watched. 136214077Sgibbs * \param path2 The tail XenStore path of the object to be watched. 137214077Sgibbs * \param watch The watch object to use for this request. This object 138214077Sgibbs * must be stable for the lifetime of the watch. 139214077Sgibbs * \param callback The function to call when XenStore objects at or below 140214077Sgibbs * path are modified. 141214077Sgibbs * 142214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 143214077Sgibbs * type of failure. 144214077Sgibbs * 145214077Sgibbs * \note On error, \a dev will be switched to the XenbusStateClosing 146214077Sgibbs * state and the returned error is saved in the per-device error node 147214077Sgibbs * for \a dev in the XenStore. 148214077Sgibbs * 149214077Sgibbs * Similar to xenbus_watch_path, however the storage for the path to the 150214077Sgibbs * watched object is allocated from the heap and filled with "path '/' path2". 151214077Sgibbs * Should a call to this function succeed, it is the callers responsibility 152214077Sgibbs * to free watch->node using the M_XENBUS malloc type. 153185605Skmacy */ 154185605Skmacyint xenbus_watch_path2(device_t dev, const char *path, 155214077Sgibbs const char *path2, struct xs_watch *watch, 156214077Sgibbs xs_watch_cb_t *callback); 157185605Skmacy 158214077Sgibbs/** 159214077Sgibbs * Grant access to the given ring_mfn to the peer of the given device. 160214077Sgibbs * 161214077Sgibbs * \param dev The device granting access to the ring page. 162214077Sgibbs * \param ring_mfn The guest machine page number of the page to grant 163214077Sgibbs * peer access rights. 164214077Sgibbs * \param refp[out] The grant reference for the page. 165214077Sgibbs * 166214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 167214077Sgibbs * type of failure. 168214077Sgibbs * 169214077Sgibbs * A successful call to xenbus_grant_ring should be paired with a call 170214077Sgibbs * to gnttab_end_foreign_access() when foregn access to this page is no 171214077Sgibbs * longer requried. 172214077Sgibbs * 173214077Sgibbs * \note On error, \a dev will be switched to the XenbusStateClosing 174214077Sgibbs * state and the returned error is saved in the per-device error node 175214077Sgibbs * for \a dev in the XenStore. 176214077Sgibbs */ 177214077Sgibbsint xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp); 178185605Skmacy 179185605Skmacy/** 180214077Sgibbs * Allocate an event channel for the given XenBus device. 181214077Sgibbs * 182214077Sgibbs * \param dev The device for which to allocate the event channel. 183214077Sgibbs * \param port[out] The port identifier for the allocated event channel. 184214077Sgibbs * 185214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 186214077Sgibbs * type of failure. 187214077Sgibbs * 188214077Sgibbs * A successfully allocated event channel should be free'd using 189214077Sgibbs * xenbus_free_evtchn(). 190214077Sgibbs * 191214077Sgibbs * \note On error, \a dev will be switched to the XenbusStateClosing 192214077Sgibbs * state and the returned error is saved in the per-device error node 193214077Sgibbs * for \a dev in the XenStore. 194185605Skmacy */ 195214077Sgibbsint xenbus_alloc_evtchn(device_t dev, evtchn_port_t *port); 196185605Skmacy 197214077Sgibbs/** 198214077Sgibbs * Free an existing event channel. 199214077Sgibbs * 200214077Sgibbs * \param dev The device which allocated this event channel. 201214077Sgibbs * \param port The port identifier for the event channel to free. 202214077Sgibbs * 203214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 204214077Sgibbs * type of failure. 205214077Sgibbs * 206214077Sgibbs * \note On error, \a dev will be switched to the XenbusStateClosing 207214077Sgibbs * state and the returned error is saved in the per-device error node 208214077Sgibbs * for \a dev in the XenStore. 209214077Sgibbs */ 210214077Sgibbsint xenbus_free_evtchn(device_t dev, evtchn_port_t port); 211185605Skmacy 212185605Skmacy/** 213214077Sgibbs * Record the given errno, along with the given, printf-style, formatted 214214077Sgibbs * message in dev's device specific error node in the XenStore. 215214077Sgibbs * 216214077Sgibbs * \param dev The device which encountered the error. 217214077Sgibbs * \param err The errno value corresponding to the error. 218214077Sgibbs * \param fmt Printf format string followed by a variable number of 219214077Sgibbs * printf arguments. 220185605Skmacy */ 221214077Sgibbsvoid xenbus_dev_error(device_t dev, int err, const char *fmt, ...) 222214077Sgibbs __attribute__((format(printf, 3, 4))); 223185605Skmacy 224185605Skmacy/** 225214077Sgibbs * va_list version of xenbus_dev_error(). 226214077Sgibbs * 227214077Sgibbs * \param dev The device which encountered the error. 228214077Sgibbs * \param err The errno value corresponding to the error. 229214077Sgibbs * \param fmt Printf format string. 230214077Sgibbs * \param ap Va_list of printf arguments. 231185605Skmacy */ 232214077Sgibbsvoid xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap) 233214077Sgibbs __attribute__((format(printf, 3, 0))); 234185605Skmacy 235185605Skmacy/** 236214077Sgibbs * Equivalent to xenbus_dev_error(), followed by 237214077Sgibbs * xenbus_set_state(dev, XenbusStateClosing). 238214077Sgibbs * 239214077Sgibbs * \param dev The device which encountered the error. 240214077Sgibbs * \param err The errno value corresponding to the error. 241214077Sgibbs * \param fmt Printf format string followed by a variable number of 242214077Sgibbs * printf arguments. 243185605Skmacy */ 244214077Sgibbsvoid xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...) 245214077Sgibbs __attribute__((format(printf, 3, 4))); 246185605Skmacy 247185605Skmacy/** 248214077Sgibbs * va_list version of xenbus_dev_fatal(). 249214077Sgibbs * 250214077Sgibbs * \param dev The device which encountered the error. 251214077Sgibbs * \param err The errno value corresponding to the error. 252214077Sgibbs * \param fmt Printf format string. 253214077Sgibbs * \param ap Va_list of printf arguments. 254185605Skmacy */ 255214077Sgibbsvoid xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list) 256214077Sgibbs __attribute__((format(printf, 3, 0))); 257185605Skmacy 258214077Sgibbs/** 259214077Sgibbs * Convert a member of the xenbus_state enum into an ASCII string. 260214077Sgibbs * 261214077Sgibbs * /param state The XenBus state to lookup. 262214077Sgibbs * 263214077Sgibbs * /return A string representing state or, for unrecognized states, 264214077Sgibbs * the string "Unknown". 265185605Skmacy */ 266214077Sgibbsconst char *xenbus_strstate(enum xenbus_state state); 267185605Skmacy 268214077Sgibbs/** 269214077Sgibbs * Return the value of a XenBus device's "online" node within the XenStore. 270214077Sgibbs * 271214077Sgibbs * \param dev The XenBus device to query. 272214077Sgibbs * 273214077Sgibbs * \return The value of the "online" node for the device. If the node 274214077Sgibbs * does not exist, 0 (offline) is returned. 275185605Skmacy */ 276185605Skmacyint xenbus_dev_is_online(device_t dev); 277185605Skmacy 278185605Skmacy#endif /* _XEN_XENBUS_XENBUSVAR_H */ 279