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 program is free software; you can redistribute it and/or |
---|
10 | * modify it under the terms of the GNU General Public License version 2 |
---|
11 | * as published by the Free Software Foundation; or, when distributed |
---|
12 | * separately from the Linux kernel or incorporated into other |
---|
13 | * software packages, subject to the following license: |
---|
14 | * |
---|
15 | * Permission is hereby granted, free of charge, to any person obtaining a copy |
---|
16 | * of this source file (the "Software"), to deal in the Software without |
---|
17 | * restriction, including without limitation the rights to use, copy, modify, |
---|
18 | * merge, publish, distribute, sublicense, and/or sell copies of the Software, |
---|
19 | * and to permit persons to whom the Software is furnished to do so, subject to |
---|
20 | * the following conditions: |
---|
21 | * |
---|
22 | * The above copyright notice and this permission notice shall be included in |
---|
23 | * all copies or substantial portions of the Software. |
---|
24 | * |
---|
25 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
---|
26 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
---|
27 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
---|
28 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
---|
29 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
---|
30 | * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
---|
31 | * IN THE SOFTWARE. |
---|
32 | */ |
---|
33 | |
---|
34 | #ifndef _XEN_XENBUS_H |
---|
35 | #define _XEN_XENBUS_H |
---|
36 | |
---|
37 | #include <linux/device.h> |
---|
38 | #include <linux/notifier.h> |
---|
39 | #include <linux/mutex.h> |
---|
40 | #include <linux/completion.h> |
---|
41 | #include <linux/init.h> |
---|
42 | #include <xen/interface/xen.h> |
---|
43 | #include <xen/interface/grant_table.h> |
---|
44 | #include <xen/interface/io/xenbus.h> |
---|
45 | #include <xen/interface/io/xs_wire.h> |
---|
46 | |
---|
47 | /* Register callback to watch this node. */ |
---|
48 | struct xenbus_watch |
---|
49 | { |
---|
50 | struct list_head list; |
---|
51 | |
---|
52 | /* Path being watched. */ |
---|
53 | const char *node; |
---|
54 | |
---|
55 | /* Callback (executed in a process context with no locks held). */ |
---|
56 | void (*callback)(struct xenbus_watch *, |
---|
57 | const char **vec, unsigned int len); |
---|
58 | |
---|
59 | /* See XBWF_ definitions below. */ |
---|
60 | unsigned long flags; |
---|
61 | }; |
---|
62 | |
---|
63 | /* |
---|
64 | * Execute callback in its own kthread. Useful if the callback is long |
---|
65 | * running or heavily serialised, to avoid taking out the main xenwatch thread |
---|
66 | * for a long period of time (or even unwittingly causing a deadlock). |
---|
67 | */ |
---|
68 | #define XBWF_new_thread 1 |
---|
69 | |
---|
70 | /* A xenbus device. */ |
---|
71 | struct xenbus_device { |
---|
72 | const char *devicetype; |
---|
73 | const char *nodename; |
---|
74 | const char *otherend; |
---|
75 | int otherend_id; |
---|
76 | struct xenbus_watch otherend_watch; |
---|
77 | struct device dev; |
---|
78 | enum xenbus_state state; |
---|
79 | struct completion down; |
---|
80 | }; |
---|
81 | |
---|
82 | static inline struct xenbus_device *to_xenbus_device(struct device *dev) |
---|
83 | { |
---|
84 | return container_of(dev, struct xenbus_device, dev); |
---|
85 | } |
---|
86 | |
---|
87 | struct xenbus_device_id |
---|
88 | { |
---|
89 | /* .../device/<device_type>/<identifier> */ |
---|
90 | char devicetype[32]; /* General class of device. */ |
---|
91 | }; |
---|
92 | |
---|
93 | /* A xenbus driver. */ |
---|
94 | struct xenbus_driver { |
---|
95 | char *name; |
---|
96 | struct module *owner; |
---|
97 | const struct xenbus_device_id *ids; |
---|
98 | int (*probe)(struct xenbus_device *dev, |
---|
99 | const struct xenbus_device_id *id); |
---|
100 | void (*otherend_changed)(struct xenbus_device *dev, |
---|
101 | enum xenbus_state backend_state); |
---|
102 | int (*remove)(struct xenbus_device *dev); |
---|
103 | int (*suspend)(struct xenbus_device *dev); |
---|
104 | int (*suspend_cancel)(struct xenbus_device *dev); |
---|
105 | int (*resume)(struct xenbus_device *dev); |
---|
106 | int (*uevent)(struct xenbus_device *, char **, int, char *, int); |
---|
107 | struct device_driver driver; |
---|
108 | int (*read_otherend_details)(struct xenbus_device *dev); |
---|
109 | }; |
---|
110 | |
---|
111 | static inline struct xenbus_driver *to_xenbus_driver(struct device_driver *drv) |
---|
112 | { |
---|
113 | return container_of(drv, struct xenbus_driver, driver); |
---|
114 | } |
---|
115 | |
---|
116 | int xenbus_register_frontend(struct xenbus_driver *drv); |
---|
117 | int xenbus_register_backend(struct xenbus_driver *drv); |
---|
118 | void xenbus_unregister_driver(struct xenbus_driver *drv); |
---|
119 | |
---|
120 | struct xenbus_transaction |
---|
121 | { |
---|
122 | u32 id; |
---|
123 | }; |
---|
124 | |
---|
125 | /* Nil transaction ID. */ |
---|
126 | #define XBT_NIL ((struct xenbus_transaction) { 0 }) |
---|
127 | |
---|
128 | char **xenbus_directory(struct xenbus_transaction t, |
---|
129 | const char *dir, const char *node, unsigned int *num); |
---|
130 | void *xenbus_read(struct xenbus_transaction t, |
---|
131 | const char *dir, const char *node, unsigned int *len); |
---|
132 | int xenbus_write(struct xenbus_transaction t, |
---|
133 | const char *dir, const char *node, const char *string); |
---|
134 | int xenbus_mkdir(struct xenbus_transaction t, |
---|
135 | const char *dir, const char *node); |
---|
136 | int xenbus_exists(struct xenbus_transaction t, |
---|
137 | const char *dir, const char *node); |
---|
138 | int xenbus_rm(struct xenbus_transaction t, const char *dir, const char *node); |
---|
139 | int xenbus_transaction_start(struct xenbus_transaction *t); |
---|
140 | int xenbus_transaction_end(struct xenbus_transaction t, int abort); |
---|
141 | |
---|
142 | /* Single read and scanf: returns -errno or num scanned if > 0. */ |
---|
143 | int xenbus_scanf(struct xenbus_transaction t, |
---|
144 | const char *dir, const char *node, const char *fmt, ...) |
---|
145 | __attribute__((format(scanf, 4, 5))); |
---|
146 | |
---|
147 | /* Single printf and write: returns -errno or 0. */ |
---|
148 | int xenbus_printf(struct xenbus_transaction t, |
---|
149 | const char *dir, const char *node, const char *fmt, ...) |
---|
150 | __attribute__((format(printf, 4, 5))); |
---|
151 | |
---|
152 | /* Generic read function: NULL-terminated triples of name, |
---|
153 | * sprintf-style type string, and pointer. Returns 0 or errno.*/ |
---|
154 | int xenbus_gather(struct xenbus_transaction t, const char *dir, ...); |
---|
155 | |
---|
156 | /* notifer routines for when the xenstore comes up */ |
---|
157 | int register_xenstore_notifier(struct notifier_block *nb); |
---|
158 | void unregister_xenstore_notifier(struct notifier_block *nb); |
---|
159 | |
---|
160 | int register_xenbus_watch(struct xenbus_watch *watch); |
---|
161 | void unregister_xenbus_watch(struct xenbus_watch *watch); |
---|
162 | void xs_suspend(void); |
---|
163 | void xs_resume(void); |
---|
164 | void xs_suspend_cancel(void); |
---|
165 | |
---|
166 | /* Used by xenbus_dev to borrow kernel's store connection. */ |
---|
167 | void *xenbus_dev_request_and_reply(struct xsd_sockmsg *msg); |
---|
168 | |
---|
169 | /* Prepare for domain suspend: then resume or cancel the suspend. */ |
---|
170 | void xenbus_suspend(void); |
---|
171 | void xenbus_resume(void); |
---|
172 | void xenbus_suspend_cancel(void); |
---|
173 | |
---|
174 | #define XENBUS_IS_ERR_READ(str) ({ \ |
---|
175 | if (!IS_ERR(str) && strlen(str) == 0) { \ |
---|
176 | kfree(str); \ |
---|
177 | str = ERR_PTR(-ERANGE); \ |
---|
178 | } \ |
---|
179 | IS_ERR(str); \ |
---|
180 | }) |
---|
181 | |
---|
182 | #define XENBUS_EXIST_ERR(err) ((err) == -ENOENT || (err) == -ERANGE) |
---|
183 | |
---|
184 | |
---|
185 | /** |
---|
186 | * Register a watch on the given path, using the given xenbus_watch structure |
---|
187 | * for storage, and the given callback function as the callback. Return 0 on |
---|
188 | * success, or -errno on error. On success, the given path will be saved as |
---|
189 | * watch->node, and remains the caller's to free. On error, watch->node will |
---|
190 | * be NULL, the device will switch to XenbusStateClosing, and the error will |
---|
191 | * be saved in the store. |
---|
192 | */ |
---|
193 | int xenbus_watch_path(struct xenbus_device *dev, const char *path, |
---|
194 | struct xenbus_watch *watch, |
---|
195 | void (*callback)(struct xenbus_watch *, |
---|
196 | const char **, unsigned int)); |
---|
197 | |
---|
198 | |
---|
199 | /** |
---|
200 | * Register a watch on the given path/path2, using the given xenbus_watch |
---|
201 | * structure for storage, and the given callback function as the callback. |
---|
202 | * Return 0 on success, or -errno on error. On success, the watched path |
---|
203 | * (path/path2) will be saved as watch->node, and becomes the caller's to |
---|
204 | * kfree(). On error, watch->node will be NULL, so the caller has nothing to |
---|
205 | * free, the device will switch to XenbusStateClosing, and the error will be |
---|
206 | * saved in the store. |
---|
207 | */ |
---|
208 | int xenbus_watch_path2(struct xenbus_device *dev, const char *path, |
---|
209 | const char *path2, struct xenbus_watch *watch, |
---|
210 | void (*callback)(struct xenbus_watch *, |
---|
211 | const char **, unsigned int)); |
---|
212 | |
---|
213 | |
---|
214 | /** |
---|
215 | * Advertise in the store a change of the given driver to the given new_state. |
---|
216 | * Return 0 on success, or -errno on error. On error, the device will switch |
---|
217 | * to XenbusStateClosing, and the error will be saved in the store. |
---|
218 | */ |
---|
219 | int xenbus_switch_state(struct xenbus_device *dev, enum xenbus_state new_state); |
---|
220 | |
---|
221 | |
---|
222 | /** |
---|
223 | * Grant access to the given ring_mfn to the peer of the given device. Return |
---|
224 | * 0 on success, or -errno on error. On error, the device will switch to |
---|
225 | * XenbusStateClosing, and the error will be saved in the store. |
---|
226 | */ |
---|
227 | int xenbus_grant_ring(struct xenbus_device *dev, unsigned long ring_mfn); |
---|
228 | |
---|
229 | |
---|
230 | /** |
---|
231 | * Map a page of memory into this domain from another domain's grant table. |
---|
232 | * xenbus_map_ring_valloc allocates a page of virtual address space, maps the |
---|
233 | * page to that address, and sets *vaddr to that address. |
---|
234 | * xenbus_map_ring does not allocate the virtual address space (you must do |
---|
235 | * this yourself!). It only maps in the page to the specified address. |
---|
236 | * Returns 0 on success, and GNTST_* (see xen/include/interface/grant_table.h) |
---|
237 | * or -ENOMEM on error. If an error is returned, device will switch to |
---|
238 | * XenbusStateClosing and the error message will be saved in XenStore. |
---|
239 | */ |
---|
240 | struct vm_struct *xenbus_map_ring_valloc(struct xenbus_device *dev, |
---|
241 | int gnt_ref); |
---|
242 | int xenbus_map_ring(struct xenbus_device *dev, int gnt_ref, |
---|
243 | grant_handle_t *handle, void *vaddr); |
---|
244 | |
---|
245 | |
---|
246 | /** |
---|
247 | * Unmap a page of memory in this domain that was imported from another domain. |
---|
248 | * Use xenbus_unmap_ring_vfree if you mapped in your memory with |
---|
249 | * xenbus_map_ring_valloc (it will free the virtual address space). |
---|
250 | * Returns 0 on success and returns GNTST_* on error |
---|
251 | * (see xen/include/interface/grant_table.h). |
---|
252 | */ |
---|
253 | int xenbus_unmap_ring_vfree(struct xenbus_device *dev, struct vm_struct *); |
---|
254 | int xenbus_unmap_ring(struct xenbus_device *dev, |
---|
255 | grant_handle_t handle, void *vaddr); |
---|
256 | |
---|
257 | |
---|
258 | /** |
---|
259 | * Allocate an event channel for the given xenbus_device, assigning the newly |
---|
260 | * created local port to *port. Return 0 on success, or -errno on error. On |
---|
261 | * error, the device will switch to XenbusStateClosing, and the error will be |
---|
262 | * saved in the store. |
---|
263 | */ |
---|
264 | int xenbus_alloc_evtchn(struct xenbus_device *dev, int *port); |
---|
265 | |
---|
266 | |
---|
267 | /** |
---|
268 | * Free an existing event channel. Returns 0 on success or -errno on error. |
---|
269 | */ |
---|
270 | int xenbus_free_evtchn(struct xenbus_device *dev, int port); |
---|
271 | |
---|
272 | |
---|
273 | /** |
---|
274 | * Return the state of the driver rooted at the given store path, or |
---|
275 | * XenbusStateUnknown if no state can be read. |
---|
276 | */ |
---|
277 | enum xenbus_state xenbus_read_driver_state(const char *path); |
---|
278 | |
---|
279 | |
---|
280 | /*** |
---|
281 | * Report the given negative errno into the store, along with the given |
---|
282 | * formatted message. |
---|
283 | */ |
---|
284 | void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt, |
---|
285 | ...); |
---|
286 | |
---|
287 | |
---|
288 | /*** |
---|
289 | * Equivalent to xenbus_dev_error(dev, err, fmt, args), followed by |
---|
290 | * xenbus_switch_state(dev, NULL, XenbusStateClosing) to schedule an orderly |
---|
291 | * closedown of this driver and its peer. |
---|
292 | */ |
---|
293 | void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt, |
---|
294 | ...); |
---|
295 | |
---|
296 | int xenbus_dev_init(void); |
---|
297 | |
---|
298 | const char *xenbus_strstate(enum xenbus_state state); |
---|
299 | int xenbus_dev_is_online(struct xenbus_device *dev); |
---|
300 | int xenbus_frontend_closed(struct xenbus_device *dev); |
---|
301 | |
---|
302 | #endif /* _XEN_XENBUS_H */ |
---|