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