sys/xen/xenbus/xenbusb.h

   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 */