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 */
Cache object: 67faff936d83e6b2b97bfa0ea6d18f77
|