xenbus.h

  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/export.h>
 41#include <linux/fs.h>
 42#include <linux/completion.h>
 43#include <linux/init.h>
 44#include <linux/slab.h>
 45#include <linux/semaphore.h>
 46#include <xen/interface/xen.h>
 47#include <xen/interface/grant_table.h>
 48#include <xen/interface/io/xenbus.h>
 49#include <xen/interface/io/xs_wire.h>
 50#include <xen/interface/event_channel.h>
 51
 52#define XENBUS_MAX_RING_GRANT_ORDER 4
 53#define XENBUS_MAX_RING_GRANTS      (1U << XENBUS_MAX_RING_GRANT_ORDER)
 54
 55/* Register callback to watch this node. */
 56struct xenbus_watch
 57{
 58	struct list_head list;
 59
 60	/* Path being watched. */
 61	const char *node;
 62
 63	unsigned int nr_pending;
 64
 65	/*
 66	 * Called just before enqueing new event while a spinlock is held.
 67	 * The event will be discarded if this callback returns false.
 68	 */
 69	bool (*will_handle)(struct xenbus_watch *,
 70			      const char *path, const char *token);
 71
 72	/* Callback (executed in a process context with no locks held). */
 73	void (*callback)(struct xenbus_watch *,
 74			 const char *path, const char *token);
 75};
 76
 77
 78/* A xenbus device. */
 79struct xenbus_device {
 80	const char *devicetype;
 81	const char *nodename;
 82	const char *otherend;
 83	int otherend_id;
 84	struct xenbus_watch otherend_watch;
 85	struct device dev;
 86	enum xenbus_state state;
 87	struct completion down;
 88	struct work_struct work;
 89	struct semaphore reclaim_sem;
 90
 91	/* Event channel based statistics and settings. */
 92	atomic_t event_channels;
 93	atomic_t events;
 94	atomic_t spurious_events;
 95	atomic_t jiffies_eoi_delayed;
 96	unsigned int spurious_threshold;
 97};
 98
 99#define to_xenbus_device(__dev)	container_of_const(__dev, struct xenbus_device, dev)
100
101struct xenbus_device_id
102{
103	/* .../device/<device_type>/<identifier> */
104	char devicetype[32]; 	/* General class of device. */
105};
106
107/* A xenbus driver. */
108struct xenbus_driver {
109	const char *name;       /* defaults to ids[0].devicetype */
110	const struct xenbus_device_id *ids;
111	bool allow_rebind; /* avoid setting xenstore closed during remove */
112	bool not_essential;     /* is not mandatory for boot progress */
113	int (*probe)(struct xenbus_device *dev,
114		     const struct xenbus_device_id *id);
115	void (*otherend_changed)(struct xenbus_device *dev,
116				 enum xenbus_state backend_state);
117	void (*remove)(struct xenbus_device *dev);
118	int (*suspend)(struct xenbus_device *dev);
119	int (*resume)(struct xenbus_device *dev);
120	int (*uevent)(const struct xenbus_device *, struct kobj_uevent_env *);
121	struct device_driver driver;
122	int (*read_otherend_details)(struct xenbus_device *dev);
123	int (*is_ready)(struct xenbus_device *dev);
124	void (*reclaim_memory)(struct xenbus_device *dev);
125};
126
127#define to_xenbus_driver(__drv)	container_of_const(__drv, struct xenbus_driver, driver)
128
129int __must_check __xenbus_register_frontend(struct xenbus_driver *drv,
130					    struct module *owner,
131					    const char *mod_name);
132int __must_check __xenbus_register_backend(struct xenbus_driver *drv,
133					   struct module *owner,
134					   const char *mod_name);
135
136#define xenbus_register_frontend(drv) \
137	__xenbus_register_frontend(drv, THIS_MODULE, KBUILD_MODNAME)
138#define xenbus_register_backend(drv) \
139	__xenbus_register_backend(drv, THIS_MODULE, KBUILD_MODNAME)
140
141void xenbus_unregister_driver(struct xenbus_driver *drv);
142
143struct xenbus_transaction
144{
145	u32 id;
146};
147
148/* Nil transaction ID. */
149#define XBT_NIL ((struct xenbus_transaction) { 0 })
150
151char **xenbus_directory(struct xenbus_transaction t,
152			const char *dir, const char *node, unsigned int *num);
153void *xenbus_read(struct xenbus_transaction t,
154		  const char *dir, const char *node, unsigned int *len);
155int xenbus_write(struct xenbus_transaction t,
156		 const char *dir, const char *node, const char *string);
157int xenbus_exists(struct xenbus_transaction t,
158		  const char *dir, const char *node);
159int xenbus_rm(struct xenbus_transaction t, const char *dir, const char *node);
160int xenbus_transaction_start(struct xenbus_transaction *t);
161int xenbus_transaction_end(struct xenbus_transaction t, bool abort);
162
163/* Single read and scanf: returns -errno or num scanned if > 0. */
164__scanf(4, 5)
165int xenbus_scanf(struct xenbus_transaction t,
166		 const char *dir, const char *node, const char *fmt, ...);
167
168/* Read an (optional) unsigned value. */
169unsigned int xenbus_read_unsigned(const char *dir, const char *node,
170				  unsigned int default_val);
171
172/* Single printf and write: returns -errno or 0. */
173__printf(4, 5)
174int xenbus_printf(struct xenbus_transaction t,
175		  const char *dir, const char *node, const char *fmt, ...);
176
177/* Generic read function: NULL-terminated triples of name,
178 * sprintf-style type string, and pointer. Returns 0 or errno.*/
179int xenbus_gather(struct xenbus_transaction t, const char *dir, ...);
180
181/* notifier routines for when the xenstore comes up */
182extern int xenstored_ready;
183int register_xenstore_notifier(struct notifier_block *nb);
184void unregister_xenstore_notifier(struct notifier_block *nb);
185
186int register_xenbus_watch(struct xenbus_watch *watch);
187void unregister_xenbus_watch(struct xenbus_watch *watch);
188void xs_suspend(void);
189void xs_resume(void);
190void xs_suspend_cancel(void);
191
192struct work_struct;
193
194#define XENBUS_IS_ERR_READ(str) ({			\
195	if (!IS_ERR(str) && strlen(str) == 0) {		\
196		kfree(str);				\
197		str = ERR_PTR(-ERANGE);			\
198	}						\
199	IS_ERR(str);					\
200})
201
202#define XENBUS_EXIST_ERR(err) ((err) == -ENOENT || (err) == -ERANGE)
203
204int xenbus_watch_path(struct xenbus_device *dev, const char *path,
205		      struct xenbus_watch *watch,
206		      bool (*will_handle)(struct xenbus_watch *,
207					  const char *, const char *),
208		      void (*callback)(struct xenbus_watch *,
209				       const char *, const char *));
210__printf(5, 6)
211int xenbus_watch_pathfmt(struct xenbus_device *dev, struct xenbus_watch *watch,
212			 bool (*will_handle)(struct xenbus_watch *,
213					     const char *, const char *),
214			 void (*callback)(struct xenbus_watch *,
215					  const char *, const char *),
216			 const char *pathfmt, ...);
217
218int xenbus_switch_state(struct xenbus_device *dev, enum xenbus_state new_state);
219int xenbus_setup_ring(struct xenbus_device *dev, gfp_t gfp, void **vaddr,
220		      unsigned int nr_pages, grant_ref_t *grefs);
221void xenbus_teardown_ring(void **vaddr, unsigned int nr_pages,
222			  grant_ref_t *grefs);
223int xenbus_map_ring_valloc(struct xenbus_device *dev, grant_ref_t *gnt_refs,
224			   unsigned int nr_grefs, void **vaddr);
225
226int xenbus_unmap_ring_vfree(struct xenbus_device *dev, void *vaddr);
227
228int xenbus_alloc_evtchn(struct xenbus_device *dev, evtchn_port_t *port);
229int xenbus_free_evtchn(struct xenbus_device *dev, evtchn_port_t port);
230
231enum xenbus_state xenbus_read_driver_state(const char *path);
232
233__printf(3, 4)
234void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt, ...);
235__printf(3, 4)
236void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt, ...);
237
238const char *xenbus_strstate(enum xenbus_state state);
239int xenbus_dev_is_online(struct xenbus_device *dev);
240int xenbus_frontend_closed(struct xenbus_device *dev);
241
242extern const struct file_operations xen_xenbus_fops;
243extern struct xenstore_domain_interface *xen_store_interface;
244extern int xen_store_evtchn;
245
246#endif /* _XEN_XENBUS_H */