sys/xen/xenbus/xenbusb.h

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