1 /*- 2 * Core definitions and data structures shareable across OS platforms. 3 * 4 * Copyright (c) 2010 Spectra Logic Corporation 5 * Copyright (C) 2008 Doug Rabson 6 * All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 1. Redistributions of source code must retain the above copyright 12 * notice, this list of conditions, and the following disclaimer, 13 * without modification. 14 * 2. Redistributions in binary form must reproduce at minimum a disclaimer 15 * substantially similar to the "NO WARRANTY" disclaimer below 16 * ("Disclaimer") and any redistribution must be conditioned upon 17 * including a substantially similar Disclaimer requirement for further 18 * binary redistribution. 19 * 20 * NO WARRANTY 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 29 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 30 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGES. 32 * 33 * $FreeBSD$ 34 */ 35 #ifndef _XEN_XENBUS_XENBUSB_H 36 #define _XEN_XENBUS_XENBUSB_H 37 38 /** 39 * \file xenbusb.h 40 * 41 * Datastructures and function declarations for use in implementing 42 * bus attachements (e.g. frontend and backend device busses) for XenBus. 43 */ 44 45 /** 46 * Enumeration of state flag values for the xbs_flags field of 47 * the xenbusb_softc structure. 48 */ 49 typedef enum { 50 /** */ 51 XBS_ATTACH_CH_ACTIVE = 0x01 52 } xenbusb_softc_flag; 53 54 /** 55 * \brief Container for all state needed to manage a Xenbus Bus 56 * attachment. 57 */ 58 struct xenbusb_softc { 59 /** 60 * XenStore watch used to monitor the subtree of the 61 * XenStore where devices for this bus attachment arrive 62 * and depart. 63 */ 64 struct xs_watch xbs_device_watch; 65 66 /** Mutex used to protect fields of the xenbusb_softc. */ 67 struct mtx xbs_lock; 68 69 /** State flags. */ 70 xenbusb_softc_flag xbs_flags; 71 72 /** 73 * A dedicated task for processing child arrival and 74 * departure events. 75 */ 76 struct task xbs_probe_children; 77 78 /** 79 * Config Hook used to block boot processing until 80 * XenBus devices complete their connection processing 81 * with other VMs. 82 */ 83 struct intr_config_hook xbs_attach_ch; 84 85 /** 86 * The number of children for this bus that are still 87 * in the connecting (to other VMs) state. This variable 88 * is used to determine when to release xbs_attach_ch. 89 */ 90 u_int xbs_connecting_children; 91 92 /** The NewBus device_t for this bus attachment. */ 93 device_t xbs_dev; 94 95 /** 96 * The VM relative path to the XenStore subtree this 97 * bus attachment manages. 98 */ 99 const char *xbs_node; 100 101 /** 102 * The number of path components (strings separated by the '/' 103 * character) that make up the device ID on this bus. 104 */ 105 u_int xbs_id_components; 106 }; 107 108 /** 109 * Enumeration of state flag values for the xbs_flags field of 110 * the xenbusb_softc structure. 111 */ 112 typedef enum { 113 114 /** 115 * This device is contributing to the xbs_connecting_children 116 * count of its parent bus. 117 */ 118 XDF_CONNECTING = 0x01 119 } xenbus_dev_flag; 120 121 /** Instance variables for devices on a XenBus bus. */ 122 struct xenbus_device_ivars { 123 /** 124 * XenStore watch used to monitor the subtree of the 125 * XenStore where information about the otherend of 126 * the split Xen device this device instance represents. 127 */ 128 struct xs_watch xd_otherend_watch; 129 130 /** 131 * XenStore watch used to monitor the XenStore sub-tree 132 * associated with this device. This watch will fire 133 * for modifications that we make from our domain as 134 * well as for those made by the control domain. 135 */ 136 struct xs_watch xd_local_watch; 137 138 /** Sleepable lock used to protect instance data. */ 139 struct sx xd_lock; 140 141 /** State flags. */ 142 xenbus_dev_flag xd_flags; 143 144 /** The NewBus device_t for this XenBus device instance. */ 145 device_t xd_dev; 146 147 /** 148 * The VM relative path to the XenStore subtree representing 149 * this VMs half of this device. 150 */ 151 char *xd_node; 152 153 /** The length of xd_node. */ 154 int xd_node_len; 155 156 /** XenBus device type ("vbd", "vif", etc.). */ 157 char *xd_type; 158 159 /** 160 * Cached version of <xd_node>/state node in the XenStore. 161 */ 162 enum xenbus_state xd_state; 163 164 /** The VM identifier of the other end of this split device. */ 165 int xd_otherend_id; 166 167 /** 168 * The path to the subtree of the XenStore where information 169 * about the otherend of this split device instance. 170 */ 171 char *xd_otherend_path; 172 173 /** The length of xd_otherend_path. */ 174 int xd_otherend_path_len; 175 }; 176 177 /** 178 * \brief Identify instances of this device type in the system. 179 * 180 * \param driver The driver performing this identify action. 181 * \param parent The NewBus parent device for any devices this method adds. 182 */ 183 void xenbusb_identify(driver_t *driver __unused, device_t parent); 184 185 /** 186 * \brief Perform common XenBus bus attach processing. 187 * 188 * \param dev The NewBus device representing this XenBus bus. 189 * \param bus_node The XenStore path to the XenStore subtree for 190 * this XenBus bus. 191 * \param id_components The number of '/' separated path components that 192 * make up a unique device ID on this XenBus bus. 193 * 194 * \return On success, 0. Otherwise an errno value indicating the 195 * type of failure. 196 * 197 * Intiailizes the softc for this bus, installs an interrupt driven 198 * configuration hook to block boot processing until XenBus devices fully 199 * configure, performs an initial probe/attach of the bus, and registers 200 * a XenStore watch so we are notified when the bus topology changes. 201 */ 202 int xenbusb_attach(device_t dev, char *bus_node, u_int id_components); 203 204 /** 205 * \brief Perform common XenBus bus resume handling. 206 * 207 * \param dev The NewBus device representing this XenBus bus. 208 * 209 * \return On success, 0. Otherwise an errno value indicating the 210 * type of failure. 211 */ 212 int xenbusb_resume(device_t dev); 213 214 /** 215 * \brief Pretty-prints information about a child of a XenBus bus. 216 * 217 * \param dev The NewBus device representing this XenBus bus. 218 * \param child The NewBus device representing a child of dev%'s XenBus bus. 219 * 220 * \return On success, 0. Otherwise an errno value indicating the 221 * type of failure. 222 */ 223 int xenbusb_print_child(device_t dev, device_t child); 224 225 /** 226 * \brief Common XenBus child instance variable read access method. 227 * 228 * \param dev The NewBus device representing this XenBus bus. 229 * \param child The NewBus device representing a child of dev%'s XenBus bus. 230 * \param index The index of the instance variable to access. 231 * \param result The value of the instance variable accessed. 232 * 233 * \return On success, 0. Otherwise an errno value indicating the 234 * type of failure. 235 */ 236 int xenbusb_read_ivar(device_t dev, device_t child, int index, 237 uintptr_t *result); 238 239 /** 240 * \brief Common XenBus child instance variable write access method. 241 * 242 * \param dev The NewBus device representing this XenBus bus. 243 * \param child The NewBus device representing a child of dev%'s XenBus bus. 244 * \param index The index of the instance variable to access. 245 * \param value The new value to set in the instance variable accessed. 246 * 247 * \return On success, 0. Otherwise an errno value indicating the 248 * type of failure. 249 */ 250 int xenbusb_write_ivar(device_t dev, device_t child, int index, 251 uintptr_t value); 252 253 /** 254 * \brief Common XenBus method implementing responses to peer state changes. 255 * 256 * \param bus The XenBus bus parent of child. 257 * \param child The XenBus child whose peer stat has changed. 258 * \param state The current state of the peer. 259 */ 260 void xenbusb_otherend_changed(device_t bus, device_t child, 261 enum xenbus_state state); 262 263 /** 264 * \brief Common XenBus method implementing responses to local XenStore changes. 265 * 266 * \param bus The XenBus bus parent of child. 267 * \param child The XenBus child whose peer stat has changed. 268 * \param path The tree relative sub-path to the modified node. The empty 269 * string indicates the root of the tree was destroyed. 270 */ 271 void xenbusb_localend_changed(device_t bus, device_t child, const char *path); 272 273 /** 274 * \brief Attempt to add a XenBus device instance to this XenBus bus. 275 * 276 * \param dev The NewBus device representing this XenBus bus. 277 * \param type The device type being added (e.g. "vbd", "vif"). 278 * \param id The device ID for this device. 279 * 280 * \return On success, 0. Otherwise an errno value indicating the 281 * type of failure. Failure indicates that either the 282 * path to this device no longer exists or insufficient 283 * information exists in the XenStore to create a new 284 * device. 285 * 286 * If successful, this routine will add a device_t with instance 287 * variable storage to the NewBus device topology. Probe/Attach 288 * processing is not performed by this routine, but must be scheduled 289 * via the xbs_probe_children task. This separation of responsibilities 290 * is required to avoid hanging up the XenStore event delivery thread 291 * with our probe/attach work in the event a device is added via 292 * a callback from the XenStore. 293 */ 294 int xenbusb_add_device(device_t dev, const char *type, const char *id); 295 296 #include "xenbusb_if.h" 297 298 #endif /* _XEN_XENBUS_XENBUSB_H */ 299