sys/xen/xenbus/xenbusb.h

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