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