1 /******************************************************************************
2 * Copyright (C) 2005 Rusty Russell, IBM Corporation
3 * Copyright (C) 2005 XenSource Ltd.
5 * This file may be distributed separately from the Linux kernel, or
6 * incorporated into other software packages, subject to the following license:
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:
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
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
32 * \brief Datastructures and function declarations for usedby device
33 * drivers operating on the XenBus.
36 #ifndef _XEN_XENBUS_XENBUSVAR_H
37 #define _XEN_XENBUS_XENBUSVAR_H
39 #include <sys/queue.h>
41 #include <sys/eventhandler.h>
42 #include <sys/malloc.h>
45 #include <machine/stdarg.h>
47 #include <xen/xen-os.h>
48 #include <xen/interface/grant_table.h>
49 #include <xen/interface/io/xenbus.h>
50 #include <xen/interface/io/xs_wire.h>
52 #include <xen/xenstore/xenstorevar.h>
54 /* XenBus allocations including XenStore data returned to clients. */
55 MALLOC_DECLARE(M_XENBUS);
59 * Path of this device node.
64 * The device type (e.g. vif, vbd).
69 * The state of this device (not the otherend's state).
74 * Domain ID of the other end device.
76 XENBUS_IVAR_OTHEREND_ID,
79 * Path of the other end device.
81 XENBUS_IVAR_OTHEREND_PATH
85 * Simplified accessors for xenbus devices:
90 * xenbus_get_otherend_id
91 * xenbus_get_otherend_path
93 #define XENBUS_ACCESSOR(var, ivar, type) \
94 __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
96 XENBUS_ACCESSOR(node, NODE, const char *)
97 XENBUS_ACCESSOR(type, TYPE, const char *)
98 XENBUS_ACCESSOR(state, STATE, enum xenbus_state)
99 XENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int)
100 XENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *)
103 * Return the state of a XenBus device.
105 * \param path The root XenStore path for the device.
107 * \return The current state of the device or XenbusStateClosed if no
110 XenbusState xenbus_read_driver_state(const char *path);
113 * Return the state of the "other end" (peer) of a XenBus device.
115 * \param dev The XenBus device whose peer to query.
117 * \return The current state of the peer device or XenbusStateClosed if no
120 static inline XenbusState
121 xenbus_get_otherend_state(device_t dev)
123 return (xenbus_read_driver_state(xenbus_get_otherend_path(dev)));
127 * Initialize and register a watch on the given path (client suplied storage).
129 * \param dev The XenBus device requesting the watch service.
130 * \param path The XenStore path of the object to be watched. The
131 * storage for this string must be stable for the lifetime
133 * \param watch The watch object to use for this request. This object
134 * must be stable for the lifetime of the watch.
135 * \param callback The function to call when XenStore objects at or below
137 * \param cb_data Client data that can be retrieved from the watch object
138 * during the callback.
140 * \return On success, 0. Otherwise an errno value indicating the
143 * \note On error, the device 'dev' will be switched to the XenbusStateClosing
144 * state and the returned error is saved in the per-device error node
145 * for dev in the XenStore.
147 int xenbus_watch_path(device_t dev, char *path,
148 struct xs_watch *watch,
149 xs_watch_cb_t *callback,
153 * Initialize and register a watch at path/path2 in the XenStore.
155 * \param dev The XenBus device requesting the watch service.
156 * \param path The base XenStore path of the object to be watched.
157 * \param path2 The tail XenStore path of the object to be watched.
158 * \param watch The watch object to use for this request. This object
159 * must be stable for the lifetime of the watch.
160 * \param callback The function to call when XenStore objects at or below
162 * \param cb_data Client data that can be retrieved from the watch object
163 * during the callback.
165 * \return On success, 0. Otherwise an errno value indicating the
168 * \note On error, \a dev will be switched to the XenbusStateClosing
169 * state and the returned error is saved in the per-device error node
170 * for \a dev in the XenStore.
172 * Similar to xenbus_watch_path, however the storage for the path to the
173 * watched object is allocated from the heap and filled with "path '/' path2".
174 * Should a call to this function succeed, it is the callers responsibility
175 * to free watch->node using the M_XENBUS malloc type.
177 int xenbus_watch_path2(device_t dev, const char *path,
178 const char *path2, struct xs_watch *watch,
179 xs_watch_cb_t *callback,
183 * Grant access to the given ring_mfn to the peer of the given device.
185 * \param dev The device granting access to the ring page.
186 * \param ring_mfn The guest machine page number of the page to grant
187 * peer access rights.
188 * \param refp[out] The grant reference for the page.
190 * \return On success, 0. Otherwise an errno value indicating the
193 * A successful call to xenbus_grant_ring should be paired with a call
194 * to gnttab_end_foreign_access() when foregn access to this page is no
197 * \note On error, \a dev will be switched to the XenbusStateClosing
198 * state and the returned error is saved in the per-device error node
199 * for \a dev in the XenStore.
201 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp);
204 * Record the given errno, along with the given, printf-style, formatted
205 * message in dev's device specific error node in the XenStore.
207 * \param dev The device which encountered the error.
208 * \param err The errno value corresponding to the error.
209 * \param fmt Printf format string followed by a variable number of
212 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...)
213 __attribute__((format(printf, 3, 4)));
216 * va_list version of xenbus_dev_error().
218 * \param dev The device which encountered the error.
219 * \param err The errno value corresponding to the error.
220 * \param fmt Printf format string.
221 * \param ap Va_list of printf arguments.
223 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap)
224 __attribute__((format(printf, 3, 0)));
227 * Equivalent to xenbus_dev_error(), followed by
228 * xenbus_set_state(dev, XenbusStateClosing).
230 * \param dev The device which encountered the error.
231 * \param err The errno value corresponding to the error.
232 * \param fmt Printf format string followed by a variable number of
235 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...)
236 __attribute__((format(printf, 3, 4)));
239 * va_list version of xenbus_dev_fatal().
241 * \param dev The device which encountered the error.
242 * \param err The errno value corresponding to the error.
243 * \param fmt Printf format string.
244 * \param ap Va_list of printf arguments.
246 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list)
247 __attribute__((format(printf, 3, 0)));
250 * Convert a member of the xenbus_state enum into an ASCII string.
252 * /param state The XenBus state to lookup.
254 * /return A string representing state or, for unrecognized states,
255 * the string "Unknown".
257 const char *xenbus_strstate(enum xenbus_state state);
260 * Return the value of a XenBus device's "online" node within the XenStore.
262 * \param dev The XenBus device to query.
264 * \return The value of the "online" node for the device. If the node
265 * does not exist, 0 (offline) is returned.
267 int xenbus_dev_is_online(device_t dev);
270 * Default callback invoked when a change to the local XenStore sub-tree
271 * for a device is modified.
273 * \param dev The XenBus device whose tree was modified.
274 * \param path The tree relative sub-path to the modified node. The empty
275 * string indicates the root of the tree was destroyed.
277 void xenbus_localend_changed(device_t dev, const char *path);
279 #include "xenbus_if.h"
281 #endif /* _XEN_XENBUS_XENBUSVAR_H */