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
27 /**
28 * \file xenbusvar.h
29 *
30 * \brief Datastructures and function declarations for usedby device
31 * drivers operating on the XenBus.
32 */
33
34 #ifndef _XEN_XENBUS_XENBUSVAR_H
35 #define _XEN_XENBUS_XENBUSVAR_H
36
37 #include <sys/queue.h>
38 #include <sys/bus.h>
39 #include <sys/eventhandler.h>
40 #include <sys/malloc.h>
41 #include <sys/sbuf.h>
42
43 #include <machine/stdarg.h>
44
45 #include <xen/xen-os.h>
46 #include <contrib/xen/grant_table.h>
47 #include <contrib/xen/io/xenbus.h>
48 #include <contrib/xen/io/xs_wire.h>
49
50 #include <xen/xenstore/xenstorevar.h>
51
52 /* XenBus allocations including XenStore data returned to clients. */
53 MALLOC_DECLARE(M_XENBUS);
54
55 enum {
56 /**
57 * Path of this device node.
58 */
59 XENBUS_IVAR_NODE,
60
61 /**
62 * The device type (e.g. vif, vbd).
63 */
64 XENBUS_IVAR_TYPE,
65
66 /**
67 * The state of this device (not the otherend's state).
68 */
69 XENBUS_IVAR_STATE,
70
71 /**
72 * Domain ID of the other end device.
73 */
74 XENBUS_IVAR_OTHEREND_ID,
75
76 /**
77 * Path of the other end device.
78 */
79 XENBUS_IVAR_OTHEREND_PATH
80 };
81
82 /**
83 * Simplified accessors for xenbus devices:
84 *
85 * xenbus_get_node
86 * xenbus_get_type
87 * xenbus_get_state
88 * xenbus_get_otherend_id
89 * xenbus_get_otherend_path
90 */
91 #define XENBUS_ACCESSOR(var, ivar, type) \
92 __BUS_ACCESSOR(xenbus, var, XENBUS, ivar, type)
93
94 XENBUS_ACCESSOR(node, NODE, const char *)
95 XENBUS_ACCESSOR(type, TYPE, const char *)
96 XENBUS_ACCESSOR(state, STATE, enum xenbus_state)
97 XENBUS_ACCESSOR(otherend_id, OTHEREND_ID, int)
98 XENBUS_ACCESSOR(otherend_path, OTHEREND_PATH, const char *)
99
100 /**
101 * Return the state of a XenBus device.
102 *
103 * \param path The root XenStore path for the device.
104 *
105 * \return The current state of the device or XenbusStateClosed if no
106 * state can be read.
107 */
108 XenbusState xenbus_read_driver_state(const char *path);
109
110 /**
111 * Return the state of the "other end" (peer) of a XenBus device.
112 *
113 * \param dev The XenBus device whose peer to query.
114 *
115 * \return The current state of the peer device or XenbusStateClosed if no
116 * state can be read.
117 */
118 static inline XenbusState
xenbus_get_otherend_state(device_t dev)119 xenbus_get_otherend_state(device_t dev)
120 {
121 return (xenbus_read_driver_state(xenbus_get_otherend_path(dev)));
122 }
123
124 /**
125 * Grant access to the given ring_mfn to the peer of the given device.
126 *
127 * \param dev The device granting access to the ring page.
128 * \param ring_mfn The guest machine page number of the page to grant
129 * peer access rights.
130 * \param refp[out] The grant reference for the page.
131 *
132 * \return On success, 0. Otherwise an errno value indicating the
133 * type of failure.
134 *
135 * A successful call to xenbus_grant_ring should be paired with a call
136 * to gnttab_end_foreign_access() when foregn access to this page is no
137 * longer requried.
138 *
139 * \note On error, \a dev will be switched to the XenbusStateClosing
140 * state and the returned error is saved in the per-device error node
141 * for \a dev in the XenStore.
142 */
143 int xenbus_grant_ring(device_t dev, unsigned long ring_mfn, grant_ref_t *refp);
144
145 /**
146 * Record the given errno, along with the given, printf-style, formatted
147 * message in dev's device specific error node in the XenStore.
148 *
149 * \param dev The device which encountered the error.
150 * \param err The errno value corresponding to the error.
151 * \param fmt Printf format string followed by a variable number of
152 * printf arguments.
153 */
154 void xenbus_dev_error(device_t dev, int err, const char *fmt, ...)
155 __attribute__((format(printf, 3, 4)));
156
157 /**
158 * va_list version of xenbus_dev_error().
159 *
160 * \param dev The device which encountered the error.
161 * \param err The errno value corresponding to the error.
162 * \param fmt Printf format string.
163 * \param ap Va_list of printf arguments.
164 */
165 void xenbus_dev_verror(device_t dev, int err, const char *fmt, va_list ap)
166 __attribute__((format(printf, 3, 0)));
167
168 /**
169 * Equivalent to xenbus_dev_error(), followed by
170 * xenbus_set_state(dev, XenbusStateClosing).
171 *
172 * \param dev The device which encountered the error.
173 * \param err The errno value corresponding to the error.
174 * \param fmt Printf format string followed by a variable number of
175 * printf arguments.
176 */
177 void xenbus_dev_fatal(device_t dev, int err, const char *fmt, ...)
178 __attribute__((format(printf, 3, 4)));
179
180 /**
181 * va_list version of xenbus_dev_fatal().
182 *
183 * \param dev The device which encountered the error.
184 * \param err The errno value corresponding to the error.
185 * \param fmt Printf format string.
186 * \param ap Va_list of printf arguments.
187 */
188 void xenbus_dev_vfatal(device_t dev, int err, const char *fmt, va_list)
189 __attribute__((format(printf, 3, 0)));
190
191 /**
192 * Convert a member of the xenbus_state enum into an ASCII string.
193 *
194 * /param state The XenBus state to lookup.
195 *
196 * /return A string representing state or, for unrecognized states,
197 * the string "Unknown".
198 */
199 const char *xenbus_strstate(enum xenbus_state state);
200
201 /**
202 * Return the value of a XenBus device's "online" node within the XenStore.
203 *
204 * \param dev The XenBus device to query.
205 *
206 * \return The value of the "online" node for the device. If the node
207 * does not exist, 0 (offline) is returned.
208 */
209 int xenbus_dev_is_online(device_t dev);
210
211 /**
212 * Default callback invoked when a change to the local XenStore sub-tree
213 * for a device is modified.
214 *
215 * \param dev The XenBus device whose tree was modified.
216 * \param path The tree relative sub-path to the modified node. The empty
217 * string indicates the root of the tree was destroyed.
218 */
219 void xenbus_localend_changed(device_t dev, const char *path);
220
221 #include "xenbus_if.h"
222
223 #endif /* _XEN_XENBUS_XENBUSVAR_H */
224