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: stable/11/sys/xen/xenbus/xenbusvar.h 369046 2021-01-18 18:57:03Z emaste $ 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> 46214077Sgibbs 47255040Sgibbs#include <xen/xen-os.h> 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 54214077Sgibbs/* XenBus allocations including XenStore data returned to clients. */ 55214077SgibbsMALLOC_DECLARE(M_XENBUS); 56214077Sgibbs 57185605Skmacyenum { 58214077Sgibbs /** 59185605Skmacy * Path of this device node. 60185605Skmacy */ 61185605Skmacy XENBUS_IVAR_NODE, 62185605Skmacy 63214077Sgibbs /** 64185605Skmacy * The device type (e.g. vif, vbd). 65185605Skmacy */ 66185605Skmacy XENBUS_IVAR_TYPE, 67185605Skmacy 68214077Sgibbs /** 69185605Skmacy * The state of this device (not the otherend's state). 70185605Skmacy */ 71185605Skmacy XENBUS_IVAR_STATE, 72185605Skmacy 73214077Sgibbs /** 74185605Skmacy * Domain ID of the other end device. 75185605Skmacy */ 76185605Skmacy XENBUS_IVAR_OTHEREND_ID, 77185605Skmacy 78214077Sgibbs /** 79185605Skmacy * Path of the other end device. 80185605Skmacy */ 81185605Skmacy XENBUS_IVAR_OTHEREND_PATH 82185605Skmacy}; 83185605Skmacy 84214077Sgibbs/** 85294090Sroyger * Simplified accessors for xenbus devices: 86294090Sroyger * 87294090Sroyger * xenbus_get_node 88294090Sroyger * xenbus_get_type 89294090Sroyger * xenbus_get_state 90294090Sroyger * xenbus_get_otherend_id 91294090Sroyger * xenbus_get_otherend_path 92185605Skmacy */ 93185605Skmacy#define XENBUS_ACCESSOR(var, ivar, type) \ 94185605Skmacy __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type) 95185605Skmacy 96185605SkmacyXENBUS_ACCESSOR(node, NODE, const char *) 97185605SkmacyXENBUS_ACCESSOR(type, TYPE, const char *) 98185605SkmacyXENBUS_ACCESSOR(state, STATE, enum xenbus_state) 99185605SkmacyXENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int) 100185605SkmacyXENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *) 101185605Skmacy 102214077Sgibbs/** 103214077Sgibbs * Return the state of a XenBus device. 104214077Sgibbs * 105214077Sgibbs * \param path The root XenStore path for the device. 106214077Sgibbs * 107214077Sgibbs * \return The current state of the device or XenbusStateClosed if no 108214077Sgibbs * state can be read. 109186557Skmacy */ 110214077SgibbsXenbusState xenbus_read_driver_state(const char *path); 111185605Skmacy 112185605Skmacy/** 113231743Sgibbs * Return the state of the "other end" (peer) of a XenBus device. 114231743Sgibbs * 115231743Sgibbs * \param dev The XenBus device whose peer to query. 116231743Sgibbs * 117231743Sgibbs * \return The current state of the peer device or XenbusStateClosed if no 118231743Sgibbs * state can be read. 119231743Sgibbs */ 120231743Sgibbsstatic inline XenbusState 121231743Sgibbsxenbus_get_otherend_state(device_t dev) 122231743Sgibbs{ 123231743Sgibbs return (xenbus_read_driver_state(xenbus_get_otherend_path(dev))); 124231743Sgibbs} 125231743Sgibbs 126231743Sgibbs/** 127214077Sgibbs * Grant access to the given ring_mfn to the peer of the given device. 128214077Sgibbs * 129214077Sgibbs * \param dev The device granting access to the ring page. 130214077Sgibbs * \param ring_mfn The guest machine page number of the page to grant 131214077Sgibbs * peer access rights. 132214077Sgibbs * \param refp[out] The grant reference for the page. 133214077Sgibbs * 134214077Sgibbs * \return On success, 0. Otherwise an errno value indicating the 135214077Sgibbs * type of failure. 136214077Sgibbs * 137214077Sgibbs * A successful call to xenbus_grant_ring should be paired with a call 138214077Sgibbs * to gnttab_end_foreign_access() when foregn access to this page is no 139214077Sgibbs * longer requried. 140214077Sgibbs * 141214077Sgibbs * \note On error, \a dev will be switched to the XenbusStateClosing 142214077Sgibbs * state and the returned error is saved in the per-device error node 143214077Sgibbs * for \a dev in the XenStore. 144214077Sgibbs */ 145214077Sgibbsint xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp); 146185605Skmacy 147185605Skmacy/** 148214077Sgibbs * Record the given errno, along with the given, printf-style, formatted 149214077Sgibbs * message in dev's device specific error node in the XenStore. 150214077Sgibbs * 151214077Sgibbs * \param dev The device which encountered the error. 152214077Sgibbs * \param err The errno value corresponding to the error. 153214077Sgibbs * \param fmt Printf format string followed by a variable number of 154214077Sgibbs * printf arguments. 155185605Skmacy */ 156214077Sgibbsvoid xenbus_dev_error(device_t dev, int err, const char *fmt, ...) 157214077Sgibbs __attribute__((format(printf, 3, 4))); 158185605Skmacy 159185605Skmacy/** 160214077Sgibbs * va_list version of xenbus_dev_error(). 161214077Sgibbs * 162214077Sgibbs * \param dev The device which encountered the error. 163214077Sgibbs * \param err The errno value corresponding to the error. 164214077Sgibbs * \param fmt Printf format string. 165214077Sgibbs * \param ap Va_list of printf arguments. 166185605Skmacy */ 167214077Sgibbsvoid xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap) 168214077Sgibbs __attribute__((format(printf, 3, 0))); 169185605Skmacy 170185605Skmacy/** 171214077Sgibbs * Equivalent to xenbus_dev_error(), followed by 172214077Sgibbs * xenbus_set_state(dev, XenbusStateClosing). 173214077Sgibbs * 174214077Sgibbs * \param dev The device which encountered the error. 175214077Sgibbs * \param err The errno value corresponding to the error. 176214077Sgibbs * \param fmt Printf format string followed by a variable number of 177214077Sgibbs * printf arguments. 178185605Skmacy */ 179214077Sgibbsvoid xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...) 180214077Sgibbs __attribute__((format(printf, 3, 4))); 181185605Skmacy 182185605Skmacy/** 183214077Sgibbs * va_list version of xenbus_dev_fatal(). 184214077Sgibbs * 185214077Sgibbs * \param dev The device which encountered the error. 186214077Sgibbs * \param err The errno value corresponding to the error. 187214077Sgibbs * \param fmt Printf format string. 188214077Sgibbs * \param ap Va_list of printf arguments. 189185605Skmacy */ 190214077Sgibbsvoid xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list) 191214077Sgibbs __attribute__((format(printf, 3, 0))); 192185605Skmacy 193214077Sgibbs/** 194214077Sgibbs * Convert a member of the xenbus_state enum into an ASCII string. 195214077Sgibbs * 196214077Sgibbs * /param state The XenBus state to lookup. 197214077Sgibbs * 198214077Sgibbs * /return A string representing state or, for unrecognized states, 199214077Sgibbs * the string "Unknown". 200185605Skmacy */ 201214077Sgibbsconst char *xenbus_strstate(enum xenbus_state state); 202185605Skmacy 203214077Sgibbs/** 204214077Sgibbs * Return the value of a XenBus device's "online" node within the XenStore. 205214077Sgibbs * 206214077Sgibbs * \param dev The XenBus device to query. 207214077Sgibbs * 208214077Sgibbs * \return The value of the "online" node for the device. If the node 209214077Sgibbs * does not exist, 0 (offline) is returned. 210185605Skmacy */ 211185605Skmacyint xenbus_dev_is_online(device_t dev); 212185605Skmacy 213222975Sgibbs/** 214222975Sgibbs * Default callback invoked when a change to the local XenStore sub-tree 215222975Sgibbs * for a device is modified. 216222975Sgibbs * 217222975Sgibbs * \param dev The XenBus device whose tree was modified. 218222975Sgibbs * \param path The tree relative sub-path to the modified node. The empty 219222975Sgibbs * string indicates the root of the tree was destroyed. 220222975Sgibbs */ 221222975Sgibbsvoid xenbus_localend_changed(device_t dev, const char *path); 222222975Sgibbs 223222975Sgibbs#include "xenbus_if.h" 224222975Sgibbs 225185605Skmacy#endif /* _XEN_XENBUS_XENBUSVAR_H */ 226