1 /******************************************************************************
2 * xenstorevar.h
3 *
4 * Method declarations and structures for accessing the XenStore.h
5 *
6 * Copyright (C) 2005 Rusty Russell, IBM Corporation
7 * Copyright (C) 2005 XenSource Ltd.
8 * Copyright (C) 2009,2010 Spectra Logic Corporation
9 *
10 * This file may be distributed separately from the Linux kernel, or
11 * incorporated into other software packages, subject to the following license:
12 *
13 * Permission is hereby granted, free of charge, to any person obtaining a copy
14 * of this source file (the "Software"), to deal in the Software without
15 * restriction, including without limitation the rights to use, copy, modify,
16 * merge, publish, distribute, sublicense, and/or sell copies of the Software,
17 * and to permit persons to whom the Software is furnished to do so, subject to
18 * the following conditions:
19 *
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
29 * IN THE SOFTWARE.
30 *
31 * $FreeBSD$
32 */
33
34 #ifndef _XEN_XENSTORE_XENSTOREVAR_H
35 #define _XEN_XENSTORE_XENSTOREVAR_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 <xen/interface/grant_table.h>
47 #include <xen/interface/io/xenbus.h>
48 #include <xen/interface/io/xs_wire.h>
49
50 #include "xenbus_if.h"
51
52 /* XenStore allocations including XenStore data returned to clients. */
53 MALLOC_DECLARE(M_XENSTORE);
54
55 struct xenstore_domain_interface;
56 struct xs_watch;
57 extern struct xenstore_domain_interface *xen_store;
58
59 typedef void (xs_watch_cb_t)(struct xs_watch *, const char **vec,
60 unsigned int len);
61
62 /* Register callback to watch subtree (node) in the XenStore. */
63 struct xs_watch
64 {
65 LIST_ENTRY(xs_watch) list;
66
67 /* Path being watched. */
68 char *node;
69
70 /* Callback (executed in a process context with no locks held). */
71 xs_watch_cb_t *callback;
72
73 /* Callback client data untouched by the XenStore watch mechanism. */
74 uintptr_t callback_data;
75
76 /* Maximum number of pending watch events to be delivered. */
77 unsigned int max_pending;
78
79 /*
80 * Private counter used by xenstore to keep track of the pending
81 * watches. Protected by xs.watch_events_lock.
82 */
83 unsigned int pending;
84 };
85 LIST_HEAD(xs_watch_list, xs_watch);
86
87 typedef int (*xs_event_handler_t)(void *);
88
89 struct xs_transaction
90 {
91 uint32_t id;
92 };
93
94 #define XST_NIL ((struct xs_transaction) { 0 })
95
96 /**
97 * Fetch the contents of a directory in the XenStore.
98 *
99 * \param t The XenStore transaction covering this request.
100 * \param dir The dirname of the path to read.
101 * \param node The basename of the path to read.
102 * \param num The returned number of directory entries.
103 * \param result An array of directory entry strings.
104 *
105 * \return On success, 0. Otherwise an errno value indicating the
106 * type of failure.
107 *
108 * \note The results buffer is malloced and should be free'd by the
109 * caller with 'free(*result, M_XENSTORE)'.
110 */
111 int xs_directory(struct xs_transaction t, const char *dir,
112 const char *node, unsigned int *num, const char ***result);
113
114 /**
115 * Determine if a path exists in the XenStore.
116 *
117 * \param t The XenStore transaction covering this request.
118 * \param dir The dirname of the path to read.
119 * \param node The basename of the path to read.
120 *
121 * \retval 1 The path exists.
122 * \retval 0 The path does not exist or an error occurred attempting
123 * to make that determination.
124 */
125 int xs_exists(struct xs_transaction t, const char *dir, const char *node);
126
127 /**
128 * Get the contents of a single "file". Returns the contents in
129 * *result which should be freed with free(*result, M_XENSTORE) after
130 * use. The length of the value in bytes is returned in *len.
131 *
132 * \param t The XenStore transaction covering this request.
133 * \param dir The dirname of the file to read.
134 * \param node The basename of the file to read.
135 * \param len The amount of data read.
136 * \param result The returned contents from this file.
137 *
138 * \return On success, 0. Otherwise an errno value indicating the
139 * type of failure.
140 *
141 * \note The results buffer is malloced and should be free'd by the
142 * caller with 'free(*result, M_XENSTORE)'.
143 */
144 int xs_read(struct xs_transaction t, const char *dir,
145 const char *node, unsigned int *len, void **result);
146
147 /**
148 * Write to a single file.
149 *
150 * \param t The XenStore transaction covering this request.
151 * \param dir The dirname of the file to write.
152 * \param node The basename of the file to write.
153 * \param string The NUL terminated string of data to write.
154 *
155 * \return On success, 0. Otherwise an errno value indicating the
156 * type of failure.
157 */
158 int xs_write(struct xs_transaction t, const char *dir,
159 const char *node, const char *string);
160
161 /**
162 * Create a new directory.
163 *
164 * \param t The XenStore transaction covering this request.
165 * \param dir The dirname of the directory to create.
166 * \param node The basename of the directory to create.
167 *
168 * \return On success, 0. Otherwise an errno value indicating the
169 * type of failure.
170 */
171 int xs_mkdir(struct xs_transaction t, const char *dir,
172 const char *node);
173
174 /**
175 * Remove a file or directory (directories must be empty).
176 *
177 * \param t The XenStore transaction covering this request.
178 * \param dir The dirname of the directory to remove.
179 * \param node The basename of the directory to remove.
180 *
181 * \return On success, 0. Otherwise an errno value indicating the
182 * type of failure.
183 */
184 int xs_rm(struct xs_transaction t, const char *dir, const char *node);
185
186 /**
187 * Destroy a tree of files rooted at dir/node.
188 *
189 * \param t The XenStore transaction covering this request.
190 * \param dir The dirname of the directory to remove.
191 * \param node The basename of the directory to remove.
192 *
193 * \return On success, 0. Otherwise an errno value indicating the
194 * type of failure.
195 */
196 int xs_rm_tree(struct xs_transaction t, const char *dir,
197 const char *node);
198
199 /**
200 * Start a transaction.
201 *
202 * Changes by others will not be seen during the lifetime of this
203 * transaction, and changes will not be visible to others until it
204 * is committed (xs_transaction_end).
205 *
206 * \param t The returned transaction.
207 *
208 * \return On success, 0. Otherwise an errno value indicating the
209 * type of failure.
210 */
211 int xs_transaction_start(struct xs_transaction *t);
212
213 /**
214 * End a transaction.
215 *
216 * \param t The transaction to end/commit.
217 * \param abort If non-zero, the transaction is discarded
218 * instead of committed.
219 *
220 * \return On success, 0. Otherwise an errno value indicating the
221 * type of failure.
222 */
223 int xs_transaction_end(struct xs_transaction t, int abort);
224
225 /*
226 * Single file read and scanf parsing of the result.
227 *
228 * \param t The XenStore transaction covering this request.
229 * \param dir The dirname of the path to read.
230 * \param node The basename of the path to read.
231 * \param scancountp The number of input values assigned (i.e. the result
232 * of scanf).
233 * \param fmt Scanf format string followed by a variable number of
234 * scanf input arguments.
235 *
236 * \return On success, 0. Otherwise an errno value indicating the
237 * type of failure.
238 */
239 int xs_scanf(struct xs_transaction t,
240 const char *dir, const char *node, int *scancountp, const char *fmt, ...)
241 __attribute__((format(scanf, 5, 6)));
242
243 /**
244 * Printf formatted write to a XenStore file.
245 *
246 * \param t The XenStore transaction covering this request.
247 * \param dir The dirname of the path to read.
248 * \param node The basename of the path to read.
249 * \param fmt Printf format string followed by a variable number of
250 * printf arguments.
251 *
252 * \return On success, 0. Otherwise an errno value indicating the
253 * type of write failure.
254 */
255 int xs_printf(struct xs_transaction t, const char *dir,
256 const char *node, const char *fmt, ...)
257 __attribute__((format(printf, 4, 5)));
258
259 /**
260 * va_list version of xenbus_printf().
261 *
262 * \param t The XenStore transaction covering this request.
263 * \param dir The dirname of the path to read.
264 * \param node The basename of the path to read.
265 * \param fmt Printf format string.
266 * \param ap Va_list of printf arguments.
267 *
268 * \return On success, 0. Otherwise an errno value indicating the
269 * type of write failure.
270 */
271 int xs_vprintf(struct xs_transaction t, const char *dir,
272 const char *node, const char *fmt, va_list ap);
273
274 /**
275 * Multi-file read within a single directory and scanf parsing of
276 * the results.
277 *
278 * \param t The XenStore transaction covering this request.
279 * \param dir The dirname of the paths to read.
280 * \param ... A variable number of argument triples specifying
281 * the file name, scanf-style format string, and
282 * output variable (pointer to storage of the results).
283 * The last triple in the call must be terminated
284 * will a final NULL argument. A NULL format string
285 * will cause the entire contents of the given file
286 * to be assigned as a NUL terminated, M_XENSTORE heap
287 * backed, string to the output parameter of that tuple.
288 *
289 * \return On success, 0. Otherwise an errno value indicating the
290 * type of read failure.
291 *
292 * Example:
293 * char protocol_abi[64];
294 * uint32_t ring_ref;
295 * char *dev_type;
296 * int error;
297 *
298 * error = xenbus_gather(XBT_NIL, xenbus_get_node(dev),
299 * "ring-ref", "%" PRIu32, &ring_ref,
300 * "protocol", "%63s", protocol_abi,
301 * "device-type", NULL, &dev_type,
302 * NULL);
303 *
304 * ...
305 *
306 * free(dev_type, M_XENSTORE);
307 */
308 int xs_gather(struct xs_transaction t, const char *dir, ...);
309
310 /**
311 * Register a XenStore watch.
312 *
313 * XenStore watches allow a client to be notified via a callback (embedded
314 * within the watch object) of changes to an object in the XenStore.
315 *
316 * \param watch An xs_watch struct with it's node and callback fields
317 * properly initialized.
318 *
319 * \return On success, 0. Otherwise an errno value indicating the
320 * type of write failure. EEXIST errors from the XenStore
321 * are supressed, allowing multiple, physically different,
322 * xenbus_watch objects, to watch the same path in the XenStore.
323 */
324 int xs_register_watch(struct xs_watch *watch);
325
326 /**
327 * Unregister a XenStore watch.
328 *
329 * \param watch An xs_watch object previously used in a successful call
330 * to xs_register_watch().
331 *
332 * The xs_watch object's node field is not altered by this call.
333 * It is the caller's responsibility to properly dispose of both the
334 * watch object and the data pointed to by watch->node.
335 */
336 void xs_unregister_watch(struct xs_watch *watch);
337
338 /**
339 * Allocate and return an sbuf containing the XenStore path string
340 * <dir>/<name>. If name is the NUL string, the returned sbuf contains
341 * the path string <dir>.
342 *
343 * \param dir The NUL terminated directory prefix for new path.
344 * \param name The NUL terminated basename for the new path.
345 *
346 * \return A buffer containing the joined path.
347 */
348 struct sbuf *xs_join(const char *, const char *);
349
350 /**
351 * Lock the xenstore request mutex.
352 */
353 void xs_lock(void);
354
355 /**
356 * Unlock the xenstore request mutex.
357 */
358 void xs_unlock(void);
359
360 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */
361
Cache object: 1adc5d1406737ff7ea8d31b6bf4e06a2
|