xref: /freebsd/sys/xen/xenstore/xenstorevar.h (revision 32100375a661c1e16588ddfa7b90ca8d26cb9786)
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 xs_watch;
56 
57 typedef	void (xs_watch_cb_t)(struct xs_watch *, const char **vec,
58     unsigned int len);
59 
60 /* Register callback to watch subtree (node) in the XenStore. */
61 struct xs_watch
62 {
63 	LIST_ENTRY(xs_watch) list;
64 
65 	/* Path being watched. */
66 	char *node;
67 
68 	/* Callback (executed in a process context with no locks held). */
69 	xs_watch_cb_t *callback;
70 
71 	/* Callback client data untouched by the XenStore watch mechanism. */
72 	uintptr_t callback_data;
73 };
74 LIST_HEAD(xs_watch_list, xs_watch);
75 
76 typedef int (*xs_event_handler_t)(void *);
77 
78 struct xs_transaction
79 {
80 	uint32_t id;
81 };
82 
83 #define XST_NIL ((struct xs_transaction) { 0 })
84 
85 /**
86  * Check if Xenstore is initialized.
87  *
88  * \return  True if initialized, false otherwise.
89  */
90 bool xs_initialized(void);
91 
92 /**
93  * Return xenstore event channel port.
94  *
95  * \return event channel port.
96  */
97 evtchn_port_t xs_evtchn(void);
98 
99 /**
100  * Return xenstore page physical memory address.
101  *
102  * \return xenstore page physical address.
103  */
104 vm_paddr_t xs_address(void);
105 
106 /**
107  * Fetch the contents of a directory in the XenStore.
108  *
109  * \param t       The XenStore transaction covering this request.
110  * \param dir     The dirname of the path to read.
111  * \param node    The basename of the path to read.
112  * \param num     The returned number of directory entries.
113  * \param result  An array of directory entry strings.
114  *
115  * \return  On success, 0. Otherwise an errno value indicating the
116  *          type of failure.
117  *
118  * \note The results buffer is malloced and should be free'd by the
119  *       caller with 'free(*result, M_XENSTORE)'.
120  */
121 int xs_directory(struct xs_transaction t, const char *dir,
122     const char *node, unsigned int *num, const char ***result);
123 
124 /**
125  * Determine if a path exists in the XenStore.
126  *
127  * \param t       The XenStore transaction covering this request.
128  * \param dir     The dirname of the path to read.
129  * \param node    The basename of the path to read.
130  *
131  * \retval 1  The path exists.
132  * \retval 0  The path does not exist or an error occurred attempting
133  *            to make that determination.
134  */
135 int xs_exists(struct xs_transaction t, const char *dir, const char *node);
136 
137 /**
138  * Get the contents of a single "file".  Returns the contents in
139  * *result which should be freed with free(*result, M_XENSTORE) after
140  * use.  The length of the value in bytes is returned in *len.
141  *
142  * \param t       The XenStore transaction covering this request.
143  * \param dir     The dirname of the file to read.
144  * \param node    The basename of the file to read.
145  * \param len     The amount of data read.
146  * \param result  The returned contents from this file.
147  *
148  * \return  On success, 0. Otherwise an errno value indicating the
149  *          type of failure.
150  *
151  * \note The results buffer is malloced and should be free'd by the
152  *       caller with 'free(*result, M_XENSTORE)'.
153  */
154 int xs_read(struct xs_transaction t, const char *dir,
155     const char *node, unsigned int *len, void **result);
156 
157 /**
158  * Write to a single file.
159  *
160  * \param t       The XenStore transaction covering this request.
161  * \param dir     The dirname of the file to write.
162  * \param node    The basename of the file to write.
163  * \param string  The NUL terminated string of data to write.
164  *
165  * \return  On success, 0. Otherwise an errno value indicating the
166  *          type of failure.
167  */
168 int xs_write(struct xs_transaction t, const char *dir,
169     const char *node, const char *string);
170 
171 /**
172  * Create a new directory.
173  *
174  * \param t       The XenStore transaction covering this request.
175  * \param dir     The dirname of the directory to create.
176  * \param node    The basename of the directory to create.
177  *
178  * \return  On success, 0. Otherwise an errno value indicating the
179  *          type of failure.
180  */
181 int xs_mkdir(struct xs_transaction t, const char *dir,
182     const char *node);
183 
184 /**
185  * Remove a file or directory (directories must be empty).
186  *
187  * \param t       The XenStore transaction covering this request.
188  * \param dir     The dirname of the directory to remove.
189  * \param node    The basename of the directory to remove.
190  *
191  * \return  On success, 0. Otherwise an errno value indicating the
192  *          type of failure.
193  */
194 int xs_rm(struct xs_transaction t, const char *dir, const char *node);
195 
196 /**
197  * Destroy a tree of files rooted at dir/node.
198  *
199  * \param t       The XenStore transaction covering this request.
200  * \param dir     The dirname of the directory to remove.
201  * \param node    The basename of the directory to remove.
202  *
203  * \return  On success, 0. Otherwise an errno value indicating the
204  *          type of failure.
205  */
206 int xs_rm_tree(struct xs_transaction t, const char *dir,
207     const char *node);
208 
209 /**
210  * Start a transaction.
211  *
212  * Changes by others will not be seen during the lifetime of this
213  * transaction, and changes will not be visible to others until it
214  * is committed (xs_transaction_end).
215  *
216  * \param t  The returned transaction.
217  *
218  * \return  On success, 0. Otherwise an errno value indicating the
219  *          type of failure.
220  */
221 int xs_transaction_start(struct xs_transaction *t);
222 
223 /**
224  * End a transaction.
225  *
226  * \param t      The transaction to end/commit.
227  * \param abort  If non-zero, the transaction is discarded
228  * 		 instead of committed.
229  *
230  * \return  On success, 0. Otherwise an errno value indicating the
231  *          type of failure.
232  */
233 int xs_transaction_end(struct xs_transaction t, int abort);
234 
235 /*
236  * Single file read and scanf parsing of the result.
237  *
238  * \param t           The XenStore transaction covering this request.
239  * \param dir         The dirname of the path to read.
240  * \param node        The basename of the path to read.
241  * \param scancountp  The number of input values assigned (i.e. the result
242  *      	      of scanf).
243  * \param fmt         Scanf format string followed by a variable number of
244  *                    scanf input arguments.
245  *
246  * \return  On success, 0. Otherwise an errno value indicating the
247  *          type of failure.
248  */
249 int xs_scanf(struct xs_transaction t,
250     const char *dir, const char *node, int *scancountp, const char *fmt, ...)
251     __attribute__((format(scanf, 5, 6)));
252 
253 /**
254  * Printf formatted write to a XenStore file.
255  *
256  * \param t     The XenStore transaction covering this request.
257  * \param dir   The dirname of the path to read.
258  * \param node  The basename of the path to read.
259  * \param fmt   Printf format string followed by a variable number of
260  *              printf arguments.
261  *
262  * \return  On success, 0. Otherwise an errno value indicating the
263  *          type of write failure.
264  */
265 int xs_printf(struct xs_transaction t, const char *dir,
266     const char *node, const char *fmt, ...)
267     __attribute__((format(printf, 4, 5)));
268 
269 /**
270  * va_list version of xenbus_printf().
271  *
272  * \param t     The XenStore transaction covering this request.
273  * \param dir   The dirname of the path to read.
274  * \param node  The basename of the path to read.
275  * \param fmt   Printf format string.
276  * \param ap    Va_list of printf arguments.
277  *
278  * \return  On success, 0. Otherwise an errno value indicating the
279  *          type of write failure.
280  */
281 int xs_vprintf(struct xs_transaction t, const char *dir,
282     const char *node, const char *fmt, va_list ap);
283 
284 /**
285  * Multi-file read within a single directory and scanf parsing of
286  * the results.
287  *
288  * \param t    The XenStore transaction covering this request.
289  * \param dir  The dirname of the paths to read.
290  * \param ...  A variable number of argument triples specifying
291  *             the file name, scanf-style format string, and
292  *             output variable (pointer to storage of the results).
293  *             The last triple in the call must be terminated
294  *             will a final NULL argument.  A NULL format string
295  *             will cause the entire contents of the given file
296  *             to be assigned as a NUL terminated, M_XENSTORE heap
297  *             backed, string to the output parameter of that tuple.
298  *
299  * \return  On success, 0. Otherwise an errno value indicating the
300  *          type of read failure.
301  *
302  * Example:
303  *         char protocol_abi[64];
304  *         uint32_t ring_ref;
305  *         char *dev_type;
306  *         int error;
307  *
308  *         error = xenbus_gather(XBT_NIL, xenbus_get_node(dev),
309  *             "ring-ref", "%" PRIu32, &ring_ref,
310  *             "protocol", "%63s", protocol_abi,
311  *             "device-type", NULL, &dev_type,
312  *             NULL);
313  *
314  *         ...
315  *
316  *         free(dev_type, M_XENSTORE);
317  */
318 int xs_gather(struct xs_transaction t, const char *dir, ...);
319 
320 /**
321  * Register a XenStore watch.
322  *
323  * XenStore watches allow a client to be notified via a callback (embedded
324  * within the watch object) of changes to an object in the XenStore.
325  *
326  * \param watch  An xs_watch struct with it's node and callback fields
327  *               properly initialized.
328  *
329  * \return  On success, 0. Otherwise an errno value indicating the
330  *          type of write failure.  EEXIST errors from the XenStore
331  *          are supressed, allowing multiple, physically different,
332  *          xenbus_watch objects, to watch the same path in the XenStore.
333  */
334 int xs_register_watch(struct xs_watch *watch);
335 
336 /**
337  * Unregister a XenStore watch.
338  *
339  * \param watch  An xs_watch object previously used in a successful call
340  *		 to xs_register_watch().
341  *
342  * The xs_watch object's node field is not altered by this call.
343  * It is the caller's responsibility to properly dispose of both the
344  * watch object and the data pointed to by watch->node.
345  */
346 void xs_unregister_watch(struct xs_watch *watch);
347 
348 /**
349  * Allocate and return an sbuf containing the XenStore path string
350  * <dir>/<name>.  If name is the NUL string, the returned sbuf contains
351  * the path string <dir>.
352  *
353  * \param dir	The NUL terminated directory prefix for new path.
354  * \param name  The NUL terminated basename for the new path.
355  *
356  * \return  A buffer containing the joined path.
357  */
358 struct sbuf *xs_join(const char *, const char *);
359 
360 /**
361  * Lock the xenstore request mutex.
362  */
363 void xs_lock(void);
364 
365 /**
366  * Unlock the xenstore request mutex.
367  */
368 void xs_unlock(void);
369 
370 #endif /* _XEN_XENSTORE_XENSTOREVAR_H */
371 
372