ia64/xen-unstable

view linux-2.6-xen-sparse/include/xen/xenbus.h @ 9296:f85bb99187bf

Update interface documentation to include sched_op_new hypercall
and clean up the style a bit. Also clean up the sched_op_new
description in the sched.h public header.

Signed-off-by: Keir Fraser <keir@xensource.com>
author kaf24@firebug.cl.cam.ac.uk
date Wed Mar 15 19:19:22 2006 +0100 (2006-03-15)
parents e9daf5307296
children a07e25890329
line source
1 /******************************************************************************
2 * xenbus.h
3 *
4 * Talks to Xen Store to figure out what devices we have.
5 *
6 * Copyright (C) 2005 Rusty Russell, IBM Corporation
7 * Copyright (C) 2005 XenSource Ltd.
8 *
9 * This file may be distributed separately from the Linux kernel, or
10 * incorporated into other software packages, subject to the following license:
11 *
12 * Permission is hereby granted, free of charge, to any person obtaining a copy
13 * of this source file (the "Software"), to deal in the Software without
14 * restriction, including without limitation the rights to use, copy, modify,
15 * merge, publish, distribute, sublicense, and/or sell copies of the Software,
16 * and to permit persons to whom the Software is furnished to do so, subject to
17 * the following conditions:
18 *
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
21 *
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
28 * IN THE SOFTWARE.
29 */
31 #ifndef _XEN_XENBUS_H
32 #define _XEN_XENBUS_H
34 #include <linux/device.h>
35 #include <linux/notifier.h>
36 #include <asm/semaphore.h>
37 #include <xen/interface/xen.h>
38 #include <xen/interface/grant_table.h>
39 #include <xen/interface/io/xenbus.h>
40 #include <xen/interface/io/xs_wire.h>
42 #define XBT_NULL 0
44 /* Register callback to watch this node. */
45 struct xenbus_watch
46 {
47 struct list_head list;
49 /* Path being watched. */
50 const char *node;
52 /* Callback (executed in a process context with no locks held). */
53 void (*callback)(struct xenbus_watch *,
54 const char **vec, unsigned int len);
55 };
58 /* A xenbus device. */
59 struct xenbus_device {
60 const char *devicetype;
61 const char *nodename;
62 const char *otherend;
63 int otherend_id;
64 struct xenbus_watch otherend_watch;
65 struct device dev;
66 XenbusState state;
67 void *data;
68 };
70 static inline struct xenbus_device *to_xenbus_device(struct device *dev)
71 {
72 return container_of(dev, struct xenbus_device, dev);
73 }
75 struct xenbus_device_id
76 {
77 /* .../device/<device_type>/<identifier> */
78 char devicetype[32]; /* General class of device. */
79 };
81 /* A xenbus driver. */
82 struct xenbus_driver {
83 char *name;
84 struct module *owner;
85 const struct xenbus_device_id *ids;
86 int (*probe)(struct xenbus_device *dev,
87 const struct xenbus_device_id *id);
88 void (*otherend_changed)(struct xenbus_device *dev,
89 XenbusState backend_state);
90 int (*remove)(struct xenbus_device *dev);
91 int (*suspend)(struct xenbus_device *dev);
92 int (*resume)(struct xenbus_device *dev);
93 int (*uevent)(struct xenbus_device *, char **, int, char *, int);
94 struct device_driver driver;
95 int (*read_otherend_details)(struct xenbus_device *dev);
96 };
98 static inline struct xenbus_driver *to_xenbus_driver(struct device_driver *drv)
99 {
100 return container_of(drv, struct xenbus_driver, driver);
101 }
103 int xenbus_register_frontend(struct xenbus_driver *drv);
104 int xenbus_register_backend(struct xenbus_driver *drv);
105 void xenbus_unregister_driver(struct xenbus_driver *drv);
107 typedef u32 xenbus_transaction_t;
109 char **xenbus_directory(xenbus_transaction_t t,
110 const char *dir, const char *node, unsigned int *num);
111 void *xenbus_read(xenbus_transaction_t t,
112 const char *dir, const char *node, unsigned int *len);
113 int xenbus_write(xenbus_transaction_t t,
114 const char *dir, const char *node, const char *string);
115 int xenbus_mkdir(xenbus_transaction_t t,
116 const char *dir, const char *node);
117 int xenbus_exists(xenbus_transaction_t t,
118 const char *dir, const char *node);
119 int xenbus_rm(xenbus_transaction_t t, const char *dir, const char *node);
120 int xenbus_transaction_start(xenbus_transaction_t *t);
121 int xenbus_transaction_end(xenbus_transaction_t t, int abort);
123 /* Single read and scanf: returns -errno or num scanned if > 0. */
124 int xenbus_scanf(xenbus_transaction_t t,
125 const char *dir, const char *node, const char *fmt, ...)
126 __attribute__((format(scanf, 4, 5)));
128 /* Single printf and write: returns -errno or 0. */
129 int xenbus_printf(xenbus_transaction_t t,
130 const char *dir, const char *node, const char *fmt, ...)
131 __attribute__((format(printf, 4, 5)));
133 /* Generic read function: NULL-terminated triples of name,
134 * sprintf-style type string, and pointer. Returns 0 or errno.*/
135 int xenbus_gather(xenbus_transaction_t t, const char *dir, ...);
137 /* notifer routines for when the xenstore comes up */
138 int register_xenstore_notifier(struct notifier_block *nb);
139 void unregister_xenstore_notifier(struct notifier_block *nb);
141 int register_xenbus_watch(struct xenbus_watch *watch);
142 void unregister_xenbus_watch(struct xenbus_watch *watch);
143 void xs_suspend(void);
144 void xs_resume(void);
146 /* Used by xenbus_dev to borrow kernel's store connection. */
147 void *xenbus_dev_request_and_reply(struct xsd_sockmsg *msg);
149 /* Called from xen core code. */
150 void xenbus_suspend(void);
151 void xenbus_resume(void);
153 #define XENBUS_IS_ERR_READ(str) ({ \
154 if (!IS_ERR(str) && strlen(str) == 0) { \
155 kfree(str); \
156 str = ERR_PTR(-ERANGE); \
157 } \
158 IS_ERR(str); \
159 })
161 #define XENBUS_EXIST_ERR(err) ((err) == -ENOENT || (err) == -ERANGE)
164 /**
165 * Register a watch on the given path, using the given xenbus_watch structure
166 * for storage, and the given callback function as the callback. Return 0 on
167 * success, or -errno on error. On success, the given path will be saved as
168 * watch->node, and remains the caller's to free. On error, watch->node will
169 * be NULL, the device will switch to XenbusStateClosing, and the error will
170 * be saved in the store.
171 */
172 int xenbus_watch_path(struct xenbus_device *dev, const char *path,
173 struct xenbus_watch *watch,
174 void (*callback)(struct xenbus_watch *,
175 const char **, unsigned int));
178 /**
179 * Register a watch on the given path/path2, using the given xenbus_watch
180 * structure for storage, and the given callback function as the callback.
181 * Return 0 on success, or -errno on error. On success, the watched path
182 * (path/path2) will be saved as watch->node, and becomes the caller's to
183 * kfree(). On error, watch->node will be NULL, so the caller has nothing to
184 * free, the device will switch to XenbusStateClosing, and the error will be
185 * saved in the store.
186 */
187 int xenbus_watch_path2(struct xenbus_device *dev, const char *path,
188 const char *path2, struct xenbus_watch *watch,
189 void (*callback)(struct xenbus_watch *,
190 const char **, unsigned int));
193 /**
194 * Advertise in the store a change of the given driver to the given new_state.
195 * Perform the change inside the given transaction xbt. xbt may be NULL, in
196 * which case this is performed inside its own transaction. Return 0 on
197 * success, or -errno on error. On error, the device will switch to
198 * XenbusStateClosing, and the error will be saved in the store.
199 */
200 int xenbus_switch_state(struct xenbus_device *dev,
201 xenbus_transaction_t xbt,
202 XenbusState new_state);
205 /**
206 * Grant access to the given ring_mfn to the peer of the given device. Return
207 * 0 on success, or -errno on error. On error, the device will switch to
208 * XenbusStateClosing, and the error will be saved in the store.
209 */
210 int xenbus_grant_ring(struct xenbus_device *dev, unsigned long ring_mfn);
213 /**
214 * Map a page of memory into this domain from another domain's grant table.
215 * xenbus_map_ring_valloc allocates a page of virtual address space, maps the
216 * page to that address, and sets *vaddr to that address.
217 * xenbus_map_ring does not allocate the virtual address space (you must do
218 * this yourself!). It only maps in the page to the specified address.
219 * Returns 0 on success, and GNTST_* (see xen/include/interface/grant_table.h)
220 * or -ENOMEM on error. If an error is returned, device will switch to
221 * XenbusStateClosing and the error message will be saved in XenStore.
222 */
223 int xenbus_map_ring_valloc(struct xenbus_device *dev,
224 int gnt_ref, void **vaddr);
225 int xenbus_map_ring(struct xenbus_device *dev, int gnt_ref,
226 grant_handle_t *handle, void *vaddr);
229 /**
230 * Unmap a page of memory in this domain that was imported from another domain.
231 * Use xenbus_unmap_ring_vfree if you mapped in your memory with
232 * xenbus_map_ring_valloc (it will free the virtual address space).
233 * Returns 0 on success and returns GNTST_* on error
234 * (see xen/include/interface/grant_table.h).
235 */
236 int xenbus_unmap_ring_vfree(struct xenbus_device *dev, void *vaddr);
237 int xenbus_unmap_ring(struct xenbus_device *dev,
238 grant_handle_t handle, void *vaddr);
241 /**
242 * Allocate an event channel for the given xenbus_device, assigning the newly
243 * created local port to *port. Return 0 on success, or -errno on error. On
244 * error, the device will switch to XenbusStateClosing, and the error will be
245 * saved in the store.
246 */
247 int xenbus_alloc_evtchn(struct xenbus_device *dev, int *port);
250 /**
251 * Bind to an existing interdomain event channel in another domain. Returns 0
252 * on success and stores the local port in *port. On error, returns -errno,
253 * switches the device to XenbusStateClosing, and saves the error in XenStore.
254 */
255 int xenbus_bind_evtchn(struct xenbus_device *dev, int remote_port, int *port);
258 /**
259 * Free an existing event channel. Returns 0 on success or -errno on error.
260 */
261 int xenbus_free_evtchn(struct xenbus_device *dev, int port);
264 /**
265 * Return the state of the driver rooted at the given store path, or
266 * XenbusStateClosed if no state can be read.
267 */
268 XenbusState xenbus_read_driver_state(const char *path);
271 /***
272 * Report the given negative errno into the store, along with the given
273 * formatted message.
274 */
275 void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt,
276 ...);
279 /***
280 * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by
281 * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly
282 * closedown of this driver and its peer.
283 */
284 void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt,
285 ...);
288 #endif /* _XEN_XENBUS_H */
290 /*
291 * Local variables:
292 * c-file-style: "linux"
293 * indent-tabs-mode: t
294 * c-indent-level: 8
295 * c-basic-offset: 8
296 * tab-width: 8
297 * End:
298 */