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