1 /******************************************************************************
4 * Method declarations and structures for accessing the XenStore.h
6 * Copyright (C) 2005 Rusty Russell, IBM Corporation
7 * Copyright (C) 2005 XenSource Ltd.
8 * Copyright (C) 2009,2010 Spectra Logic Corporation
10 * This file may be distributed separately from the Linux kernel, or
11 * incorporated into other software packages, subject to the following license:
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:
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
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
34 #ifndef _XEN_XENSTORE_XENSTOREVAR_H
35 #define _XEN_XENSTORE_XENSTOREVAR_H
37 #include <sys/queue.h>
39 #include <sys/eventhandler.h>
40 #include <sys/malloc.h>
43 #include <machine/stdarg.h>
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>
50 #include "xenbus_if.h"
52 /* XenStore allocations including XenStore data returned to clients. */
53 MALLOC_DECLARE(M_XENSTORE);
55 struct xenstore_domain_interface;
57 extern struct xenstore_domain_interface *xen_store;
59 typedef void (xs_watch_cb_t)(struct xs_watch *, const char **vec,
62 /* Register callback to watch subtree (node) in the XenStore. */
65 LIST_ENTRY(xs_watch) list;
67 /* Path being watched. */
70 /* Callback (executed in a process context with no locks held). */
71 xs_watch_cb_t *callback;
73 /* Callback client data untouched by the XenStore watch mechanism. */
74 uintptr_t callback_data;
76 LIST_HEAD(xs_watch_list, xs_watch);
78 typedef int (*xs_event_handler_t)(void *);
85 #define XST_NIL ((struct xs_transaction) { 0 })
88 * Fetch the contents of a directory in the XenStore.
90 * \param t The XenStore transaction covering this request.
91 * \param dir The dirname of the path to read.
92 * \param node The basename of the path to read.
93 * \param num The returned number of directory entries.
94 * \param result An array of directory entry strings.
96 * \return On success, 0. Otherwise an errno value indicating the
99 * \note The results buffer is malloced and should be free'd by the
100 * caller with 'free(*result, M_XENSTORE)'.
102 int xs_directory(struct xs_transaction t, const char *dir,
103 const char *node, unsigned int *num, const char ***result);
106 * Determine if a path exists in the XenStore.
108 * \param t The XenStore transaction covering this request.
109 * \param dir The dirname of the path to read.
110 * \param node The basename of the path to read.
112 * \retval 1 The path exists.
113 * \retval 0 The path does not exist or an error occurred attempting
114 * to make that determination.
116 int xs_exists(struct xs_transaction t, const char *dir, const char *node);
119 * Get the contents of a single "file". Returns the contents in
120 * *result which should be freed with free(*result, M_XENSTORE) after
121 * use. The length of the value in bytes is returned in *len.
123 * \param t The XenStore transaction covering this request.
124 * \param dir The dirname of the file to read.
125 * \param node The basename of the file to read.
126 * \param len The amount of data read.
127 * \param result The returned contents from this file.
129 * \return On success, 0. Otherwise an errno value indicating the
132 * \note The results buffer is malloced and should be free'd by the
133 * caller with 'free(*result, M_XENSTORE)'.
135 int xs_read(struct xs_transaction t, const char *dir,
136 const char *node, unsigned int *len, void **result);
139 * Write to a single file.
141 * \param t The XenStore transaction covering this request.
142 * \param dir The dirname of the file to write.
143 * \param node The basename of the file to write.
144 * \param string The NUL terminated string of data to write.
146 * \return On success, 0. Otherwise an errno value indicating the
149 int xs_write(struct xs_transaction t, const char *dir,
150 const char *node, const char *string);
153 * Create a new directory.
155 * \param t The XenStore transaction covering this request.
156 * \param dir The dirname of the directory to create.
157 * \param node The basename of the directory to create.
159 * \return On success, 0. Otherwise an errno value indicating the
162 int xs_mkdir(struct xs_transaction t, const char *dir,
166 * Remove a file or directory (directories must be empty).
168 * \param t The XenStore transaction covering this request.
169 * \param dir The dirname of the directory to remove.
170 * \param node The basename of the directory to remove.
172 * \return On success, 0. Otherwise an errno value indicating the
175 int xs_rm(struct xs_transaction t, const char *dir, const char *node);
178 * Destroy a tree of files rooted at dir/node.
180 * \param t The XenStore transaction covering this request.
181 * \param dir The dirname of the directory to remove.
182 * \param node The basename of the directory to remove.
184 * \return On success, 0. Otherwise an errno value indicating the
187 int xs_rm_tree(struct xs_transaction t, const char *dir,
191 * Start a transaction.
193 * Changes by others will not be seen during the lifetime of this
194 * transaction, and changes will not be visible to others until it
195 * is committed (xs_transaction_end).
197 * \param t The returned transaction.
199 * \return On success, 0. Otherwise an errno value indicating the
202 int xs_transaction_start(struct xs_transaction *t);
207 * \param t The transaction to end/commit.
208 * \param abort If non-zero, the transaction is discarded
209 * instead of committed.
211 * \return On success, 0. Otherwise an errno value indicating the
214 int xs_transaction_end(struct xs_transaction t, int abort);
217 * Single file read and scanf parsing of the result.
219 * \param t The XenStore transaction covering this request.
220 * \param dir The dirname of the path to read.
221 * \param node The basename of the path to read.
222 * \param scancountp The number of input values assigned (i.e. the result
224 * \param fmt Scanf format string followed by a variable number of
225 * scanf input arguments.
227 * \return On success, 0. Otherwise an errno value indicating the
230 int xs_scanf(struct xs_transaction t,
231 const char *dir, const char *node, int *scancountp, const char *fmt, ...)
232 __attribute__((format(scanf, 5, 6)));
235 * Printf formatted write to a XenStore file.
237 * \param t The XenStore transaction covering this request.
238 * \param dir The dirname of the path to read.
239 * \param node The basename of the path to read.
240 * \param fmt Printf format string followed by a variable number of
243 * \return On success, 0. Otherwise an errno value indicating the
244 * type of write failure.
246 int xs_printf(struct xs_transaction t, const char *dir,
247 const char *node, const char *fmt, ...)
248 __attribute__((format(printf, 4, 5)));
251 * va_list version of xenbus_printf().
253 * \param t The XenStore transaction covering this request.
254 * \param dir The dirname of the path to read.
255 * \param node The basename of the path to read.
256 * \param fmt Printf format string.
257 * \param ap Va_list of printf arguments.
259 * \return On success, 0. Otherwise an errno value indicating the
260 * type of write failure.
262 int xs_vprintf(struct xs_transaction t, const char *dir,
263 const char *node, const char *fmt, va_list ap);
266 * Multi-file read within a single directory and scanf parsing of
269 * \param t The XenStore transaction covering this request.
270 * \param dir The dirname of the paths to read.
271 * \param ... A variable number of argument triples specifying
272 * the file name, scanf-style format string, and
273 * output variable (pointer to storage of the results).
274 * The last triple in the call must be terminated
275 * will a final NULL argument. A NULL format string
276 * will cause the entire contents of the given file
277 * to be assigned as a NUL terminated, M_XENSTORE heap
278 * backed, string to the output parameter of that tuple.
280 * \return On success, 0. Otherwise an errno value indicating the
281 * type of read failure.
284 * char protocol_abi[64];
289 * error = xenbus_gather(XBT_NIL, xenbus_get_node(dev),
290 * "ring-ref", "%" PRIu32, &ring_ref,
291 * "protocol", "%63s", protocol_abi,
292 * "device-type", NULL, &dev_type,
297 * free(dev_type, M_XENSTORE);
299 int xs_gather(struct xs_transaction t, const char *dir, ...);
302 * Register a XenStore watch.
304 * XenStore watches allow a client to be notified via a callback (embedded
305 * within the watch object) of changes to an object in the XenStore.
307 * \param watch An xs_watch struct with it's node and callback fields
308 * properly initialized.
310 * \return On success, 0. Otherwise an errno value indicating the
311 * type of write failure. EEXIST errors from the XenStore
312 * are supressed, allowing multiple, physically different,
313 * xenbus_watch objects, to watch the same path in the XenStore.
315 int xs_register_watch(struct xs_watch *watch);
318 * Unregister a XenStore watch.
320 * \param watch An xs_watch object previously used in a successful call
321 * to xs_register_watch().
323 * The xs_watch object's node field is not altered by this call.
324 * It is the caller's responsibility to properly dispose of both the
325 * watch object and the data pointed to by watch->node.
327 void xs_unregister_watch(struct xs_watch *watch);
330 * Allocate and return an sbuf containing the XenStore path string
331 * <dir>/<name>. If name is the NUL string, the returned sbuf contains
332 * the path string <dir>.
334 * \param dir The NUL terminated directory prefix for new path.
335 * \param name The NUL terminated basename for the new path.
337 * \return A buffer containing the joined path.
339 struct sbuf *xs_join(const char *, const char *);
341 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */