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