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 #include "xenbusb_if.h" 45 46 /** 47 * Enumeration of state flag values for the xbs_flags field of 48 * the xenbusb_softc structure. 49 */ 50 typedef enum { 51 /** */ 52 XBS_ATTACH_CH_ACTIVE = 0x01 53 } xenbusb_softc_flag; 54 55 /** 56 * \brief Container for all state needed to manage a Xenbus Bus 57 * attachment. 58 */ 59 struct xenbusb_softc { 60 /** 61 * XenStore watch used to monitor the subtree of the 62 * XenStore where devices for this bus attachment arrive 63 * and depart. 64 * 65 * \note This field must be the first in the softc structure 66 * so that a simple cast can be used to retrieve the 67 * softc from within a XenStore watch event callback. 68 */ 69 struct xs_watch xbs_device_watch; 70 71 /** Mutex used to protect fields of the xenbusb_softc. */ 72 struct mtx xbs_lock; 73 74 /** State flags. */ 75 xenbusb_softc_flag xbs_flags; 76 77 /** 78 * A dedicated task for processing child arrival and 79 * departure events. 80 */ 81 struct task xbs_probe_children; 82 83 /** 84 * Config Hook used to block boot processing until 85 * XenBus devices complete their connection processing 86 * with other VMs. 87 */ 88 struct intr_config_hook xbs_attach_ch; 89 90 /** 91 * The number of children for this bus that are still 92 * in the connecting (to other VMs) state. This variable 93 * is used to determine when to release xbs_attach_ch. 94 */ 95 u_int xbs_connecting_children; 96 97 /** The NewBus device_t for this bus attachment. */ 98 device_t xbs_dev; 99 100 /** 101 * The VM relative path to the XenStore subtree this 102 * bus attachment manages. 103 */ 104 const char *xbs_node; 105 106 /** 107 * The number of path components (strings separated by the '/' 108 * character) that make up the device ID on this bus. 109 */ 110 u_int xbs_id_components; 111 }; 112 113 /** 114 * Enumeration of state flag values for the xbs_flags field of 115 * the xenbusb_softc structure. 116 */ 117 typedef enum { 118 119 /** 120 * This device is contributing to the xbs_connecting_children 121 * count of its parent bus. 122 */ 123 XDF_CONNECTING = 0x01 124 } xenbus_dev_flag; 125 126 /** Instance variables for devices on a XenBus bus. */ 127 struct xenbus_device_ivars { 128 /** 129 * XenStore watch used to monitor the subtree of the 130 * XenStore where information about the otherend of 131 * the split Xen device this device instance represents. 132 * 133 * \note This field must be the first in the instance 134 * variable structure so that a simple cast can be 135 * used to retrieve ivar data from within a XenStore 136 * watch event callback. 137 */ 138 struct xs_watch xd_otherend_watch; 139 140 /** Sleepable lock used to protect instance data. */ 141 struct sx xd_lock; 142 143 /** State flags. */ 144 xenbus_dev_flag xd_flags; 145 146 /** The NewBus device_t for this XenBus device instance. */ 147 device_t xd_dev; 148 149 /** 150 * The VM relative path to the XenStore subtree representing 151 * this VMs half of this device. 152 */ 153 char *xd_node; 154 155 /** XenBus device type ("vbd", "vif", etc.). */ 156 char *xd_type; 157 158 /** 159 * Cached version of <xd_node>/state node in the XenStore. 160 */ 161 enum xenbus_state xd_state; 162 163 /** The VM identifier of the other end of this split device. */ 164 int xd_otherend_id; 165 166 /** 167 * The path to the subtree of the XenStore where information 168 * about the otherend of this split device instance. 169 */ 170 char *xd_otherend_path; 171 }; 172 173 /** 174 * \brief Identify instances of this device type in the system. 175 * 176 * \param driver The driver performing this identify action. 177 * \param parent The NewBus parent device for any devices this method adds. 178 */ 179 void xenbusb_identify(driver_t *driver __unused, device_t parent); 180 181 /** 182 * \brief Perform common XenBus bus attach processing. 183 * 184 * \param dev The NewBus device representing this XenBus bus. 185 * \param bus_node The XenStore path to the XenStore subtree for 186 * this XenBus bus. 187 * \param id_components The number of '/' separated path components that 188 * make up a unique device ID on this XenBus bus. 189 * 190 * \return On success, 0. Otherwise an errno value indicating the 191 * type of failure. 192 * 193 * Intiailizes the softc for this bus, installs an interrupt driven 194 * configuration hook to block boot processing until XenBus devices fully 195 * configure, performs an initial probe/attach of the bus, and registers 196 * a XenStore watch so we are notified when the bus topology changes. 197 */ 198 int xenbusb_attach(device_t dev, char *bus_node, u_int id_components); 199 200 /** 201 * \brief Perform common XenBus bus resume handling. 202 * 203 * \param dev The NewBus device representing this XenBus bus. 204 * 205 * \return On success, 0. Otherwise an errno value indicating the 206 * type of failure. 207 */ 208 int xenbusb_resume(device_t dev); 209 210 /** 211 * \brief Pretty-prints information about a child of a XenBus bus. 212 * 213 * \param dev The NewBus device representing this XenBus bus. 214 * \param child The NewBus device representing a child of dev%'s XenBus bus. 215 * 216 * \return On success, 0. Otherwise an errno value indicating the 217 * type of failure. 218 */ 219 int xenbusb_print_child(device_t dev, device_t child); 220 221 /** 222 * \brief Common XenBus child instance variable read access method. 223 * 224 * \param dev The NewBus device representing this XenBus bus. 225 * \param child The NewBus device representing a child of dev%'s XenBus bus. 226 * \param index The index of the instance variable to access. 227 * \param result The value of the instance variable accessed. 228 * 229 * \return On success, 0. Otherwise an errno value indicating the 230 * type of failure. 231 */ 232 int xenbusb_read_ivar(device_t dev, device_t child, int index, 233 uintptr_t *result); 234 235 /** 236 * \brief Common XenBus child instance variable write access method. 237 * 238 * \param dev The NewBus device representing this XenBus bus. 239 * \param child The NewBus device representing a child of dev%'s XenBus bus. 240 * \param index The index of the instance variable to access. 241 * \param value The new value to set in the instance variable accessed. 242 * 243 * \return On success, 0. Otherwise an errno value indicating the 244 * type of failure. 245 */ 246 int xenbusb_write_ivar(device_t dev, device_t child, int index, 247 uintptr_t value); 248 249 /** 250 * \brief Attempt to add a XenBus device instance to this XenBus bus. 251 * 252 * \param dev The NewBus device representing this XenBus bus. 253 * \param type The device type being added (e.g. "vbd", "vif"). 254 * \param id The device ID for this device. 255 * 256 * \return On success, 0. Otherwise an errno value indicating the 257 * type of failure. Failure indicates that either the 258 * path to this device no longer exists or insufficient 259 * information exists in the XenStore to create a new 260 * device. 261 * 262 * If successful, this routine will add a device_t with instance 263 * variable storage to the NewBus device topology. Probe/Attach 264 * processing is not performed by this routine, but must be scheduled 265 * via the xbs_probe_children task. This separation of responsibilities 266 * is required to avoid hanging up the XenStore event delivery thread 267 * with our probe/attach work in the event a device is added via 268 * a callback from the XenStore. 269 */ 270 int xenbusb_add_device(device_t dev, const char *type, const char *id); 271 272 #endif /* _XEN_XENBUS_XENBUSB_H */ 273