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: releng/12.0/sys/xen/xenstore/xenstorevar.h 336470 2018-07-19 07:54:45Z royger $
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
Cache object: 194b783136893bbb38cc95949c4f4816
|