1 /******************************************************************************
2 * Copyright (C) 2005 Rusty Russell, IBM Corporation
3 * Copyright (C) 2005 XenSource Ltd.
4 *
5 * This file may be distributed separately from the Linux kernel, or
6 * incorporated into other software packages, subject to the following license:
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this source file (the "Software"), to deal in the Software without
10 * restriction, including without limitation the rights to use, copy, modify,
11 * merge, publish, distribute, sublicense, and/or sell copies of the Software,
12 * and to permit persons to whom the Software is furnished to do so, subject to
13 * the following conditions:
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
24 * IN THE SOFTWARE.
25 *
26 * $FreeBSD: releng/8.2/sys/xen/xenbus/xenbusvar.h 215788 2010-11-24 01:03:03Z gibbs $
27 */
28
29 /**
30 * \file xenbusvar.h
31 *
32 * \brief Datastructures and function declarations for usedby device
33 * drivers operating on the XenBus.
34 */
35
36 #ifndef _XEN_XENBUS_XENBUSVAR_H
37 #define _XEN_XENBUS_XENBUSVAR_H
38
39 #include <sys/queue.h>
40 #include <sys/bus.h>
41 #include <sys/eventhandler.h>
42 #include <sys/malloc.h>
43 #include <sys/sbuf.h>
44
45 #include <machine/stdarg.h>
46 #include <machine/xen/xen-os.h>
47
48 #include <xen/interface/grant_table.h>
49 #include <xen/interface/io/xenbus.h>
50 #include <xen/interface/io/xs_wire.h>
51
52 #include <xen/xenstore/xenstorevar.h>
53
54 #include "xenbus_if.h"
55
56 /* XenBus allocations including XenStore data returned to clients. */
57 MALLOC_DECLARE(M_XENBUS);
58
59 enum {
60 /**
61 * Path of this device node.
62 */
63 XENBUS_IVAR_NODE,
64
65 /**
66 * The device type (e.g. vif, vbd).
67 */
68 XENBUS_IVAR_TYPE,
69
70 /**
71 * The state of this device (not the otherend's state).
72 */
73 XENBUS_IVAR_STATE,
74
75 /**
76 * Domain ID of the other end device.
77 */
78 XENBUS_IVAR_OTHEREND_ID,
79
80 /**
81 * Path of the other end device.
82 */
83 XENBUS_IVAR_OTHEREND_PATH
84 };
85
86 /**
87 * Simplified accessors for xenbus devices
88 */
89 #define XENBUS_ACCESSOR(var, ivar, type) \
90 __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
91
92 XENBUS_ACCESSOR(node, NODE, const char *)
93 XENBUS_ACCESSOR(type, TYPE, const char *)
94 XENBUS_ACCESSOR(state, STATE, enum xenbus_state)
95 XENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int)
96 XENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *)
97
98 /**
99 * Return the state of a XenBus device.
100 *
101 * \param path The root XenStore path for the device.
102 *
103 * \return The current state of the device or XenbusStateClosed if no
104 * state can be read.
105 */
106 XenbusState xenbus_read_driver_state(const char *path);
107
108 /**
109 * Initialize and register a watch on the given path (client suplied storage).
110 *
111 * \param dev The XenBus device requesting the watch service.
112 * \param path The XenStore path of the object to be watched. The
113 * storage for this string must be stable for the lifetime
114 * of the watch.
115 * \param watch The watch object to use for this request. This object
116 * must be stable for the lifetime of the watch.
117 * \param callback The function to call when XenStore objects at or below
118 * path are modified.
119 *
120 * \return On success, 0. Otherwise an errno value indicating the
121 * type of failure.
122 *
123 * \note On error, the device 'dev' will be switched to the XenbusStateClosing
124 * state and the returned error is saved in the per-device error node
125 * for dev in the XenStore.
126 */
127 int xenbus_watch_path(device_t dev, char *path,
128 struct xs_watch *watch,
129 xs_watch_cb_t *callback);
130
131 /**
132 * Initialize and register a watch at path/path2 in the XenStore.
133 *
134 * \param dev The XenBus device requesting the watch service.
135 * \param path The base XenStore path of the object to be watched.
136 * \param path2 The tail XenStore path of the object to be watched.
137 * \param watch The watch object to use for this request. This object
138 * must be stable for the lifetime of the watch.
139 * \param callback The function to call when XenStore objects at or below
140 * path are modified.
141 *
142 * \return On success, 0. Otherwise an errno value indicating the
143 * type of failure.
144 *
145 * \note On error, \a dev will be switched to the XenbusStateClosing
146 * state and the returned error is saved in the per-device error node
147 * for \a dev in the XenStore.
148 *
149 * Similar to xenbus_watch_path, however the storage for the path to the
150 * watched object is allocated from the heap and filled with "path '/' path2".
151 * Should a call to this function succeed, it is the callers responsibility
152 * to free watch->node using the M_XENBUS malloc type.
153 */
154 int xenbus_watch_path2(device_t dev, const char *path,
155 const char *path2, struct xs_watch *watch,
156 xs_watch_cb_t *callback);
157
158 /**
159 * Grant access to the given ring_mfn to the peer of the given device.
160 *
161 * \param dev The device granting access to the ring page.
162 * \param ring_mfn The guest machine page number of the page to grant
163 * peer access rights.
164 * \param refp[out] The grant reference for the page.
165 *
166 * \return On success, 0. Otherwise an errno value indicating the
167 * type of failure.
168 *
169 * A successful call to xenbus_grant_ring should be paired with a call
170 * to gnttab_end_foreign_access() when foregn access to this page is no
171 * longer requried.
172 *
173 * \note On error, \a dev will be switched to the XenbusStateClosing
174 * state and the returned error is saved in the per-device error node
175 * for \a dev in the XenStore.
176 */
177 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp);
178
179 /**
180 * Allocate an event channel for the given XenBus device.
181 *
182 * \param dev The device for which to allocate the event channel.
183 * \param port[out] The port identifier for the allocated event channel.
184 *
185 * \return On success, 0. Otherwise an errno value indicating the
186 * type of failure.
187 *
188 * A successfully allocated event channel should be free'd using
189 * xenbus_free_evtchn().
190 *
191 * \note On error, \a dev will be switched to the XenbusStateClosing
192 * state and the returned error is saved in the per-device error node
193 * for \a dev in the XenStore.
194 */
195 int xenbus_alloc_evtchn(device_t dev, evtchn_port_t *port);
196
197 /**
198 * Free an existing event channel.
199 *
200 * \param dev The device which allocated this event channel.
201 * \param port The port identifier for the event channel to free.
202 *
203 * \return On success, 0. Otherwise an errno value indicating the
204 * type of failure.
205 *
206 * \note On error, \a dev will be switched to the XenbusStateClosing
207 * state and the returned error is saved in the per-device error node
208 * for \a dev in the XenStore.
209 */
210 int xenbus_free_evtchn(device_t dev, evtchn_port_t port);
211
212 /**
213 * Record the given errno, along with the given, printf-style, formatted
214 * message in dev's device specific error node in the XenStore.
215 *
216 * \param dev The device which encountered the error.
217 * \param err The errno value corresponding to the error.
218 * \param fmt Printf format string followed by a variable number of
219 * printf arguments.
220 */
221 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...)
222 __attribute__((format(printf, 3, 4)));
223
224 /**
225 * va_list version of xenbus_dev_error().
226 *
227 * \param dev The device which encountered the error.
228 * \param err The errno value corresponding to the error.
229 * \param fmt Printf format string.
230 * \param ap Va_list of printf arguments.
231 */
232 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap)
233 __attribute__((format(printf, 3, 0)));
234
235 /**
236 * Equivalent to xenbus_dev_error(), followed by
237 * xenbus_set_state(dev, XenbusStateClosing).
238 *
239 * \param dev The device which encountered the error.
240 * \param err The errno value corresponding to the error.
241 * \param fmt Printf format string followed by a variable number of
242 * printf arguments.
243 */
244 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...)
245 __attribute__((format(printf, 3, 4)));
246
247 /**
248 * va_list version of xenbus_dev_fatal().
249 *
250 * \param dev The device which encountered the error.
251 * \param err The errno value corresponding to the error.
252 * \param fmt Printf format string.
253 * \param ap Va_list of printf arguments.
254 */
255 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list)
256 __attribute__((format(printf, 3, 0)));
257
258 /**
259 * Convert a member of the xenbus_state enum into an ASCII string.
260 *
261 * /param state The XenBus state to lookup.
262 *
263 * /return A string representing state or, for unrecognized states,
264 * the string "Unknown".
265 */
266 const char *xenbus_strstate(enum xenbus_state state);
267
268 /**
269 * Return the value of a XenBus device's "online" node within the XenStore.
270 *
271 * \param dev The XenBus device to query.
272 *
273 * \return The value of the "online" node for the device. If the node
274 * does not exist, 0 (offline) is returned.
275 */
276 int xenbus_dev_is_online(device_t dev);
277
278 #endif /* _XEN_XENBUS_XENBUSVAR_H */
Cache object: f1f75404503388ed546b42151da19124
|