xref: /freebsd/sys/xen/xenbus/xenbusb.h (revision aa0a1e58f0189b0fde359a8bda032887e72057fa)
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 */
273