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