xref: /freebsd/sys/kern/subr_bus.c (revision f18d3c411697ff46d85e579a72be54ca0cc67dd0)
1 /*-
2  * Copyright (c) 1997,1998,2003 Doug Rabson
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24  * SUCH DAMAGE.
25  */
26 
27 #include <sys/cdefs.h>
28 __FBSDID("$FreeBSD$");
29 
30 #include "opt_bus.h"
31 #include "opt_random.h"
32 
33 #include <sys/param.h>
34 #include <sys/conf.h>
35 #include <sys/filio.h>
36 #include <sys/lock.h>
37 #include <sys/kernel.h>
38 #include <sys/kobj.h>
39 #include <sys/limits.h>
40 #include <sys/malloc.h>
41 #include <sys/module.h>
42 #include <sys/mutex.h>
43 #include <sys/poll.h>
44 #include <sys/proc.h>
45 #include <sys/condvar.h>
46 #include <sys/queue.h>
47 #include <machine/bus.h>
48 #include <sys/random.h>
49 #include <sys/rman.h>
50 #include <sys/selinfo.h>
51 #include <sys/signalvar.h>
52 #include <sys/sysctl.h>
53 #include <sys/systm.h>
54 #include <sys/uio.h>
55 #include <sys/bus.h>
56 #include <sys/interrupt.h>
57 
58 #include <net/vnet.h>
59 
60 #include <machine/cpu.h>
61 #include <machine/stdarg.h>
62 
63 #include <vm/uma.h>
64 
65 SYSCTL_NODE(_hw, OID_AUTO, bus, CTLFLAG_RW, NULL, NULL);
66 SYSCTL_NODE(, OID_AUTO, dev, CTLFLAG_RW, NULL, NULL);
67 
68 /*
69  * Used to attach drivers to devclasses.
70  */
71 typedef struct driverlink *driverlink_t;
72 struct driverlink {
73 	kobj_class_t	driver;
74 	TAILQ_ENTRY(driverlink) link;	/* list of drivers in devclass */
75 	int		pass;
76 	TAILQ_ENTRY(driverlink) passlink;
77 };
78 
79 /*
80  * Forward declarations
81  */
82 typedef TAILQ_HEAD(devclass_list, devclass) devclass_list_t;
83 typedef TAILQ_HEAD(driver_list, driverlink) driver_list_t;
84 typedef TAILQ_HEAD(device_list, device) device_list_t;
85 
86 struct devclass {
87 	TAILQ_ENTRY(devclass) link;
88 	devclass_t	parent;		/* parent in devclass hierarchy */
89 	driver_list_t	drivers;     /* bus devclasses store drivers for bus */
90 	char		*name;
91 	device_t	*devices;	/* array of devices indexed by unit */
92 	int		maxunit;	/* size of devices array */
93 	int		flags;
94 #define DC_HAS_CHILDREN		1
95 
96 	struct sysctl_ctx_list sysctl_ctx;
97 	struct sysctl_oid *sysctl_tree;
98 };
99 
100 /**
101  * @brief Implementation of device.
102  */
103 struct device {
104 	/*
105 	 * A device is a kernel object. The first field must be the
106 	 * current ops table for the object.
107 	 */
108 	KOBJ_FIELDS;
109 
110 	/*
111 	 * Device hierarchy.
112 	 */
113 	TAILQ_ENTRY(device)	link;	/**< list of devices in parent */
114 	TAILQ_ENTRY(device)	devlink; /**< global device list membership */
115 	device_t	parent;		/**< parent of this device  */
116 	device_list_t	children;	/**< list of child devices */
117 
118 	/*
119 	 * Details of this device.
120 	 */
121 	driver_t	*driver;	/**< current driver */
122 	devclass_t	devclass;	/**< current device class */
123 	int		unit;		/**< current unit number */
124 	char*		nameunit;	/**< name+unit e.g. foodev0 */
125 	char*		desc;		/**< driver specific description */
126 	int		busy;		/**< count of calls to device_busy() */
127 	device_state_t	state;		/**< current device state  */
128 	uint32_t	devflags;	/**< api level flags for device_get_flags() */
129 	u_int		flags;		/**< internal device flags  */
130 #define	DF_ENABLED	0x01		/* device should be probed/attached */
131 #define	DF_FIXEDCLASS	0x02		/* devclass specified at create time */
132 #define	DF_WILDCARD	0x04		/* unit was originally wildcard */
133 #define	DF_DESCMALLOCED	0x08		/* description was malloced */
134 #define	DF_QUIET	0x10		/* don't print verbose attach message */
135 #define	DF_DONENOMATCH	0x20		/* don't execute DEVICE_NOMATCH again */
136 #define	DF_EXTERNALSOFTC 0x40		/* softc not allocated by us */
137 #define	DF_REBID	0x80		/* Can rebid after attach */
138 	u_int	order;			/**< order from device_add_child_ordered() */
139 	void	*ivars;			/**< instance variables  */
140 	void	*softc;			/**< current driver's variables  */
141 
142 	struct sysctl_ctx_list sysctl_ctx; /**< state for sysctl variables  */
143 	struct sysctl_oid *sysctl_tree;	/**< state for sysctl variables */
144 };
145 
146 static MALLOC_DEFINE(M_BUS, "bus", "Bus data structures");
147 static MALLOC_DEFINE(M_BUS_SC, "bus-sc", "Bus data structures, softc");
148 
149 #ifdef BUS_DEBUG
150 
151 static int bus_debug = 1;
152 TUNABLE_INT("bus.debug", &bus_debug);
153 SYSCTL_INT(_debug, OID_AUTO, bus_debug, CTLFLAG_RW, &bus_debug, 0,
154     "Debug bus code");
155 
156 #define PDEBUG(a)	if (bus_debug) {printf("%s:%d: ", __func__, __LINE__), printf a; printf("\n");}
157 #define DEVICENAME(d)	((d)? device_get_name(d): "no device")
158 #define DRIVERNAME(d)	((d)? d->name : "no driver")
159 #define DEVCLANAME(d)	((d)? d->name : "no devclass")
160 
161 /**
162  * Produce the indenting, indent*2 spaces plus a '.' ahead of that to
163  * prevent syslog from deleting initial spaces
164  */
165 #define indentprintf(p)	do { int iJ; printf("."); for (iJ=0; iJ<indent; iJ++) printf("  "); printf p ; } while (0)
166 
167 static void print_device_short(device_t dev, int indent);
168 static void print_device(device_t dev, int indent);
169 void print_device_tree_short(device_t dev, int indent);
170 void print_device_tree(device_t dev, int indent);
171 static void print_driver_short(driver_t *driver, int indent);
172 static void print_driver(driver_t *driver, int indent);
173 static void print_driver_list(driver_list_t drivers, int indent);
174 static void print_devclass_short(devclass_t dc, int indent);
175 static void print_devclass(devclass_t dc, int indent);
176 void print_devclass_list_short(void);
177 void print_devclass_list(void);
178 
179 #else
180 /* Make the compiler ignore the function calls */
181 #define PDEBUG(a)			/* nop */
182 #define DEVICENAME(d)			/* nop */
183 #define DRIVERNAME(d)			/* nop */
184 #define DEVCLANAME(d)			/* nop */
185 
186 #define print_device_short(d,i)		/* nop */
187 #define print_device(d,i)		/* nop */
188 #define print_device_tree_short(d,i)	/* nop */
189 #define print_device_tree(d,i)		/* nop */
190 #define print_driver_short(d,i)		/* nop */
191 #define print_driver(d,i)		/* nop */
192 #define print_driver_list(d,i)		/* nop */
193 #define print_devclass_short(d,i)	/* nop */
194 #define print_devclass(d,i)		/* nop */
195 #define print_devclass_list_short()	/* nop */
196 #define print_devclass_list()		/* nop */
197 #endif
198 
199 /*
200  * dev sysctl tree
201  */
202 
203 enum {
204 	DEVCLASS_SYSCTL_PARENT,
205 };
206 
207 static int
208 devclass_sysctl_handler(SYSCTL_HANDLER_ARGS)
209 {
210 	devclass_t dc = (devclass_t)arg1;
211 	const char *value;
212 
213 	switch (arg2) {
214 	case DEVCLASS_SYSCTL_PARENT:
215 		value = dc->parent ? dc->parent->name : "";
216 		break;
217 	default:
218 		return (EINVAL);
219 	}
220 	return (SYSCTL_OUT(req, value, strlen(value)));
221 }
222 
223 static void
224 devclass_sysctl_init(devclass_t dc)
225 {
226 
227 	if (dc->sysctl_tree != NULL)
228 		return;
229 	sysctl_ctx_init(&dc->sysctl_ctx);
230 	dc->sysctl_tree = SYSCTL_ADD_NODE(&dc->sysctl_ctx,
231 	    SYSCTL_STATIC_CHILDREN(_dev), OID_AUTO, dc->name,
232 	    CTLFLAG_RD, NULL, "");
233 	SYSCTL_ADD_PROC(&dc->sysctl_ctx, SYSCTL_CHILDREN(dc->sysctl_tree),
234 	    OID_AUTO, "%parent", CTLTYPE_STRING | CTLFLAG_RD,
235 	    dc, DEVCLASS_SYSCTL_PARENT, devclass_sysctl_handler, "A",
236 	    "parent class");
237 }
238 
239 enum {
240 	DEVICE_SYSCTL_DESC,
241 	DEVICE_SYSCTL_DRIVER,
242 	DEVICE_SYSCTL_LOCATION,
243 	DEVICE_SYSCTL_PNPINFO,
244 	DEVICE_SYSCTL_PARENT,
245 };
246 
247 static int
248 device_sysctl_handler(SYSCTL_HANDLER_ARGS)
249 {
250 	device_t dev = (device_t)arg1;
251 	const char *value;
252 	char *buf;
253 	int error;
254 
255 	buf = NULL;
256 	switch (arg2) {
257 	case DEVICE_SYSCTL_DESC:
258 		value = dev->desc ? dev->desc : "";
259 		break;
260 	case DEVICE_SYSCTL_DRIVER:
261 		value = dev->driver ? dev->driver->name : "";
262 		break;
263 	case DEVICE_SYSCTL_LOCATION:
264 		value = buf = malloc(1024, M_BUS, M_WAITOK | M_ZERO);
265 		bus_child_location_str(dev, buf, 1024);
266 		break;
267 	case DEVICE_SYSCTL_PNPINFO:
268 		value = buf = malloc(1024, M_BUS, M_WAITOK | M_ZERO);
269 		bus_child_pnpinfo_str(dev, buf, 1024);
270 		break;
271 	case DEVICE_SYSCTL_PARENT:
272 		value = dev->parent ? dev->parent->nameunit : "";
273 		break;
274 	default:
275 		return (EINVAL);
276 	}
277 	error = SYSCTL_OUT(req, value, strlen(value));
278 	if (buf != NULL)
279 		free(buf, M_BUS);
280 	return (error);
281 }
282 
283 static void
284 device_sysctl_init(device_t dev)
285 {
286 	devclass_t dc = dev->devclass;
287 
288 	if (dev->sysctl_tree != NULL)
289 		return;
290 	devclass_sysctl_init(dc);
291 	sysctl_ctx_init(&dev->sysctl_ctx);
292 	dev->sysctl_tree = SYSCTL_ADD_NODE(&dev->sysctl_ctx,
293 	    SYSCTL_CHILDREN(dc->sysctl_tree), OID_AUTO,
294 	    dev->nameunit + strlen(dc->name),
295 	    CTLFLAG_RD, NULL, "");
296 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
297 	    OID_AUTO, "%desc", CTLTYPE_STRING | CTLFLAG_RD,
298 	    dev, DEVICE_SYSCTL_DESC, device_sysctl_handler, "A",
299 	    "device description");
300 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
301 	    OID_AUTO, "%driver", CTLTYPE_STRING | CTLFLAG_RD,
302 	    dev, DEVICE_SYSCTL_DRIVER, device_sysctl_handler, "A",
303 	    "device driver name");
304 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
305 	    OID_AUTO, "%location", CTLTYPE_STRING | CTLFLAG_RD,
306 	    dev, DEVICE_SYSCTL_LOCATION, device_sysctl_handler, "A",
307 	    "device location relative to parent");
308 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
309 	    OID_AUTO, "%pnpinfo", CTLTYPE_STRING | CTLFLAG_RD,
310 	    dev, DEVICE_SYSCTL_PNPINFO, device_sysctl_handler, "A",
311 	    "device identification");
312 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
313 	    OID_AUTO, "%parent", CTLTYPE_STRING | CTLFLAG_RD,
314 	    dev, DEVICE_SYSCTL_PARENT, device_sysctl_handler, "A",
315 	    "parent device");
316 }
317 
318 static void
319 device_sysctl_update(device_t dev)
320 {
321 	devclass_t dc = dev->devclass;
322 
323 	if (dev->sysctl_tree == NULL)
324 		return;
325 	sysctl_rename_oid(dev->sysctl_tree, dev->nameunit + strlen(dc->name));
326 }
327 
328 static void
329 device_sysctl_fini(device_t dev)
330 {
331 	if (dev->sysctl_tree == NULL)
332 		return;
333 	sysctl_ctx_free(&dev->sysctl_ctx);
334 	dev->sysctl_tree = NULL;
335 }
336 
337 /*
338  * /dev/devctl implementation
339  */
340 
341 /*
342  * This design allows only one reader for /dev/devctl.  This is not desirable
343  * in the long run, but will get a lot of hair out of this implementation.
344  * Maybe we should make this device a clonable device.
345  *
346  * Also note: we specifically do not attach a device to the device_t tree
347  * to avoid potential chicken and egg problems.  One could argue that all
348  * of this belongs to the root node.  One could also further argue that the
349  * sysctl interface that we have not might more properly be an ioctl
350  * interface, but at this stage of the game, I'm not inclined to rock that
351  * boat.
352  *
353  * I'm also not sure that the SIGIO support is done correctly or not, as
354  * I copied it from a driver that had SIGIO support that likely hasn't been
355  * tested since 3.4 or 2.2.8!
356  */
357 
358 /* Deprecated way to adjust queue length */
359 static int sysctl_devctl_disable(SYSCTL_HANDLER_ARGS);
360 /* XXX Need to support old-style tunable hw.bus.devctl_disable" */
361 SYSCTL_PROC(_hw_bus, OID_AUTO, devctl_disable, CTLTYPE_INT | CTLFLAG_RW, NULL,
362     0, sysctl_devctl_disable, "I", "devctl disable -- deprecated");
363 
364 #define DEVCTL_DEFAULT_QUEUE_LEN 1000
365 static int sysctl_devctl_queue(SYSCTL_HANDLER_ARGS);
366 static int devctl_queue_length = DEVCTL_DEFAULT_QUEUE_LEN;
367 TUNABLE_INT("hw.bus.devctl_queue", &devctl_queue_length);
368 SYSCTL_PROC(_hw_bus, OID_AUTO, devctl_queue, CTLTYPE_INT | CTLFLAG_RW, NULL,
369     0, sysctl_devctl_queue, "I", "devctl queue length");
370 
371 static d_open_t		devopen;
372 static d_close_t	devclose;
373 static d_read_t		devread;
374 static d_ioctl_t	devioctl;
375 static d_poll_t		devpoll;
376 
377 static struct cdevsw dev_cdevsw = {
378 	.d_version =	D_VERSION,
379 	.d_flags =	D_NEEDGIANT,
380 	.d_open =	devopen,
381 	.d_close =	devclose,
382 	.d_read =	devread,
383 	.d_ioctl =	devioctl,
384 	.d_poll =	devpoll,
385 	.d_name =	"devctl",
386 };
387 
388 struct dev_event_info
389 {
390 	char *dei_data;
391 	TAILQ_ENTRY(dev_event_info) dei_link;
392 };
393 
394 TAILQ_HEAD(devq, dev_event_info);
395 
396 static struct dev_softc
397 {
398 	int	inuse;
399 	int	nonblock;
400 	int	queued;
401 	struct mtx mtx;
402 	struct cv cv;
403 	struct selinfo sel;
404 	struct devq devq;
405 	struct proc *async_proc;
406 } devsoftc;
407 
408 static struct cdev *devctl_dev;
409 
410 static void
411 devinit(void)
412 {
413 	devctl_dev = make_dev_credf(MAKEDEV_ETERNAL, &dev_cdevsw, 0, NULL,
414 	    UID_ROOT, GID_WHEEL, 0600, "devctl");
415 	mtx_init(&devsoftc.mtx, "dev mtx", "devd", MTX_DEF);
416 	cv_init(&devsoftc.cv, "dev cv");
417 	TAILQ_INIT(&devsoftc.devq);
418 }
419 
420 static int
421 devopen(struct cdev *dev, int oflags, int devtype, struct thread *td)
422 {
423 	if (devsoftc.inuse)
424 		return (EBUSY);
425 	/* move to init */
426 	devsoftc.inuse = 1;
427 	devsoftc.nonblock = 0;
428 	devsoftc.async_proc = NULL;
429 	return (0);
430 }
431 
432 static int
433 devclose(struct cdev *dev, int fflag, int devtype, struct thread *td)
434 {
435 	devsoftc.inuse = 0;
436 	mtx_lock(&devsoftc.mtx);
437 	cv_broadcast(&devsoftc.cv);
438 	mtx_unlock(&devsoftc.mtx);
439 	devsoftc.async_proc = NULL;
440 	return (0);
441 }
442 
443 /*
444  * The read channel for this device is used to report changes to
445  * userland in realtime.  We are required to free the data as well as
446  * the n1 object because we allocate them separately.  Also note that
447  * we return one record at a time.  If you try to read this device a
448  * character at a time, you will lose the rest of the data.  Listening
449  * programs are expected to cope.
450  */
451 static int
452 devread(struct cdev *dev, struct uio *uio, int ioflag)
453 {
454 	struct dev_event_info *n1;
455 	int rv;
456 
457 	mtx_lock(&devsoftc.mtx);
458 	while (TAILQ_EMPTY(&devsoftc.devq)) {
459 		if (devsoftc.nonblock) {
460 			mtx_unlock(&devsoftc.mtx);
461 			return (EAGAIN);
462 		}
463 		rv = cv_wait_sig(&devsoftc.cv, &devsoftc.mtx);
464 		if (rv) {
465 			/*
466 			 * Need to translate ERESTART to EINTR here? -- jake
467 			 */
468 			mtx_unlock(&devsoftc.mtx);
469 			return (rv);
470 		}
471 	}
472 	n1 = TAILQ_FIRST(&devsoftc.devq);
473 	TAILQ_REMOVE(&devsoftc.devq, n1, dei_link);
474 	devsoftc.queued--;
475 	mtx_unlock(&devsoftc.mtx);
476 	rv = uiomove(n1->dei_data, strlen(n1->dei_data), uio);
477 	free(n1->dei_data, M_BUS);
478 	free(n1, M_BUS);
479 	return (rv);
480 }
481 
482 static	int
483 devioctl(struct cdev *dev, u_long cmd, caddr_t data, int fflag, struct thread *td)
484 {
485 	switch (cmd) {
486 
487 	case FIONBIO:
488 		if (*(int*)data)
489 			devsoftc.nonblock = 1;
490 		else
491 			devsoftc.nonblock = 0;
492 		return (0);
493 	case FIOASYNC:
494 		if (*(int*)data)
495 			devsoftc.async_proc = td->td_proc;
496 		else
497 			devsoftc.async_proc = NULL;
498 		return (0);
499 
500 		/* (un)Support for other fcntl() calls. */
501 	case FIOCLEX:
502 	case FIONCLEX:
503 	case FIONREAD:
504 	case FIOSETOWN:
505 	case FIOGETOWN:
506 	default:
507 		break;
508 	}
509 	return (ENOTTY);
510 }
511 
512 static	int
513 devpoll(struct cdev *dev, int events, struct thread *td)
514 {
515 	int	revents = 0;
516 
517 	mtx_lock(&devsoftc.mtx);
518 	if (events & (POLLIN | POLLRDNORM)) {
519 		if (!TAILQ_EMPTY(&devsoftc.devq))
520 			revents = events & (POLLIN | POLLRDNORM);
521 		else
522 			selrecord(td, &devsoftc.sel);
523 	}
524 	mtx_unlock(&devsoftc.mtx);
525 
526 	return (revents);
527 }
528 
529 /**
530  * @brief Return whether the userland process is running
531  */
532 boolean_t
533 devctl_process_running(void)
534 {
535 	return (devsoftc.inuse == 1);
536 }
537 
538 /**
539  * @brief Queue data to be read from the devctl device
540  *
541  * Generic interface to queue data to the devctl device.  It is
542  * assumed that @p data is properly formatted.  It is further assumed
543  * that @p data is allocated using the M_BUS malloc type.
544  */
545 void
546 devctl_queue_data_f(char *data, int flags)
547 {
548 	struct dev_event_info *n1 = NULL, *n2 = NULL;
549 	struct proc *p;
550 
551 	if (strlen(data) == 0)
552 		goto out;
553 	if (devctl_queue_length == 0)
554 		goto out;
555 	n1 = malloc(sizeof(*n1), M_BUS, flags);
556 	if (n1 == NULL)
557 		goto out;
558 	n1->dei_data = data;
559 	mtx_lock(&devsoftc.mtx);
560 	if (devctl_queue_length == 0) {
561 		mtx_unlock(&devsoftc.mtx);
562 		free(n1->dei_data, M_BUS);
563 		free(n1, M_BUS);
564 		return;
565 	}
566 	/* Leave at least one spot in the queue... */
567 	while (devsoftc.queued > devctl_queue_length - 1) {
568 		n2 = TAILQ_FIRST(&devsoftc.devq);
569 		TAILQ_REMOVE(&devsoftc.devq, n2, dei_link);
570 		free(n2->dei_data, M_BUS);
571 		free(n2, M_BUS);
572 		devsoftc.queued--;
573 	}
574 	TAILQ_INSERT_TAIL(&devsoftc.devq, n1, dei_link);
575 	devsoftc.queued++;
576 	cv_broadcast(&devsoftc.cv);
577 	mtx_unlock(&devsoftc.mtx);
578 	selwakeup(&devsoftc.sel);
579 	p = devsoftc.async_proc;
580 	if (p != NULL) {
581 		PROC_LOCK(p);
582 		kern_psignal(p, SIGIO);
583 		PROC_UNLOCK(p);
584 	}
585 	return;
586 out:
587 	/*
588 	 * We have to free data on all error paths since the caller
589 	 * assumes it will be free'd when this item is dequeued.
590 	 */
591 	free(data, M_BUS);
592 	return;
593 }
594 
595 void
596 devctl_queue_data(char *data)
597 {
598 
599 	devctl_queue_data_f(data, M_NOWAIT);
600 }
601 
602 /**
603  * @brief Send a 'notification' to userland, using standard ways
604  */
605 void
606 devctl_notify_f(const char *system, const char *subsystem, const char *type,
607     const char *data, int flags)
608 {
609 	int len = 0;
610 	char *msg;
611 
612 	if (system == NULL)
613 		return;		/* BOGUS!  Must specify system. */
614 	if (subsystem == NULL)
615 		return;		/* BOGUS!  Must specify subsystem. */
616 	if (type == NULL)
617 		return;		/* BOGUS!  Must specify type. */
618 	len += strlen(" system=") + strlen(system);
619 	len += strlen(" subsystem=") + strlen(subsystem);
620 	len += strlen(" type=") + strlen(type);
621 	/* add in the data message plus newline. */
622 	if (data != NULL)
623 		len += strlen(data);
624 	len += 3;	/* '!', '\n', and NUL */
625 	msg = malloc(len, M_BUS, flags);
626 	if (msg == NULL)
627 		return;		/* Drop it on the floor */
628 	if (data != NULL)
629 		snprintf(msg, len, "!system=%s subsystem=%s type=%s %s\n",
630 		    system, subsystem, type, data);
631 	else
632 		snprintf(msg, len, "!system=%s subsystem=%s type=%s\n",
633 		    system, subsystem, type);
634 	devctl_queue_data_f(msg, flags);
635 }
636 
637 void
638 devctl_notify(const char *system, const char *subsystem, const char *type,
639     const char *data)
640 {
641 
642 	devctl_notify_f(system, subsystem, type, data, M_NOWAIT);
643 }
644 
645 /*
646  * Common routine that tries to make sending messages as easy as possible.
647  * We allocate memory for the data, copy strings into that, but do not
648  * free it unless there's an error.  The dequeue part of the driver should
649  * free the data.  We don't send data when the device is disabled.  We do
650  * send data, even when we have no listeners, because we wish to avoid
651  * races relating to startup and restart of listening applications.
652  *
653  * devaddq is designed to string together the type of event, with the
654  * object of that event, plus the plug and play info and location info
655  * for that event.  This is likely most useful for devices, but less
656  * useful for other consumers of this interface.  Those should use
657  * the devctl_queue_data() interface instead.
658  */
659 static void
660 devaddq(const char *type, const char *what, device_t dev)
661 {
662 	char *data = NULL;
663 	char *loc = NULL;
664 	char *pnp = NULL;
665 	const char *parstr;
666 
667 	if (!devctl_queue_length)/* Rare race, but lost races safely discard */
668 		return;
669 	data = malloc(1024, M_BUS, M_NOWAIT);
670 	if (data == NULL)
671 		goto bad;
672 
673 	/* get the bus specific location of this device */
674 	loc = malloc(1024, M_BUS, M_NOWAIT);
675 	if (loc == NULL)
676 		goto bad;
677 	*loc = '\0';
678 	bus_child_location_str(dev, loc, 1024);
679 
680 	/* Get the bus specific pnp info of this device */
681 	pnp = malloc(1024, M_BUS, M_NOWAIT);
682 	if (pnp == NULL)
683 		goto bad;
684 	*pnp = '\0';
685 	bus_child_pnpinfo_str(dev, pnp, 1024);
686 
687 	/* Get the parent of this device, or / if high enough in the tree. */
688 	if (device_get_parent(dev) == NULL)
689 		parstr = ".";	/* Or '/' ? */
690 	else
691 		parstr = device_get_nameunit(device_get_parent(dev));
692 	/* String it all together. */
693 	snprintf(data, 1024, "%s%s at %s %s on %s\n", type, what, loc, pnp,
694 	  parstr);
695 	free(loc, M_BUS);
696 	free(pnp, M_BUS);
697 	devctl_queue_data(data);
698 	return;
699 bad:
700 	free(pnp, M_BUS);
701 	free(loc, M_BUS);
702 	free(data, M_BUS);
703 	return;
704 }
705 
706 /*
707  * A device was added to the tree.  We are called just after it successfully
708  * attaches (that is, probe and attach success for this device).  No call
709  * is made if a device is merely parented into the tree.  See devnomatch
710  * if probe fails.  If attach fails, no notification is sent (but maybe
711  * we should have a different message for this).
712  */
713 static void
714 devadded(device_t dev)
715 {
716 	devaddq("+", device_get_nameunit(dev), dev);
717 }
718 
719 /*
720  * A device was removed from the tree.  We are called just before this
721  * happens.
722  */
723 static void
724 devremoved(device_t dev)
725 {
726 	devaddq("-", device_get_nameunit(dev), dev);
727 }
728 
729 /*
730  * Called when there's no match for this device.  This is only called
731  * the first time that no match happens, so we don't keep getting this
732  * message.  Should that prove to be undesirable, we can change it.
733  * This is called when all drivers that can attach to a given bus
734  * decline to accept this device.  Other errors may not be detected.
735  */
736 static void
737 devnomatch(device_t dev)
738 {
739 	devaddq("?", "", dev);
740 }
741 
742 static int
743 sysctl_devctl_disable(SYSCTL_HANDLER_ARGS)
744 {
745 	struct dev_event_info *n1;
746 	int dis, error;
747 
748 	dis = devctl_queue_length == 0;
749 	error = sysctl_handle_int(oidp, &dis, 0, req);
750 	if (error || !req->newptr)
751 		return (error);
752 	mtx_lock(&devsoftc.mtx);
753 	if (dis) {
754 		while (!TAILQ_EMPTY(&devsoftc.devq)) {
755 			n1 = TAILQ_FIRST(&devsoftc.devq);
756 			TAILQ_REMOVE(&devsoftc.devq, n1, dei_link);
757 			free(n1->dei_data, M_BUS);
758 			free(n1, M_BUS);
759 		}
760 		devsoftc.queued = 0;
761 		devctl_queue_length = 0;
762 	} else {
763 		devctl_queue_length = DEVCTL_DEFAULT_QUEUE_LEN;
764 	}
765 	mtx_unlock(&devsoftc.mtx);
766 	return (0);
767 }
768 
769 static int
770 sysctl_devctl_queue(SYSCTL_HANDLER_ARGS)
771 {
772 	struct dev_event_info *n1;
773 	int q, error;
774 
775 	q = devctl_queue_length;
776 	error = sysctl_handle_int(oidp, &q, 0, req);
777 	if (error || !req->newptr)
778 		return (error);
779 	if (q < 0)
780 		return (EINVAL);
781 	mtx_lock(&devsoftc.mtx);
782 	devctl_queue_length = q;
783 	while (devsoftc.queued > devctl_queue_length) {
784 		n1 = TAILQ_FIRST(&devsoftc.devq);
785 		TAILQ_REMOVE(&devsoftc.devq, n1, dei_link);
786 		free(n1->dei_data, M_BUS);
787 		free(n1, M_BUS);
788 		devsoftc.queued--;
789 	}
790 	mtx_unlock(&devsoftc.mtx);
791 	return (0);
792 }
793 
794 /* End of /dev/devctl code */
795 
796 static TAILQ_HEAD(,device)	bus_data_devices;
797 static int bus_data_generation = 1;
798 
799 static kobj_method_t null_methods[] = {
800 	KOBJMETHOD_END
801 };
802 
803 DEFINE_CLASS(null, null_methods, 0);
804 
805 /*
806  * Bus pass implementation
807  */
808 
809 static driver_list_t passes = TAILQ_HEAD_INITIALIZER(passes);
810 int bus_current_pass = BUS_PASS_ROOT;
811 
812 /**
813  * @internal
814  * @brief Register the pass level of a new driver attachment
815  *
816  * Register a new driver attachment's pass level.  If no driver
817  * attachment with the same pass level has been added, then @p new
818  * will be added to the global passes list.
819  *
820  * @param new		the new driver attachment
821  */
822 static void
823 driver_register_pass(struct driverlink *new)
824 {
825 	struct driverlink *dl;
826 
827 	/* We only consider pass numbers during boot. */
828 	if (bus_current_pass == BUS_PASS_DEFAULT)
829 		return;
830 
831 	/*
832 	 * Walk the passes list.  If we already know about this pass
833 	 * then there is nothing to do.  If we don't, then insert this
834 	 * driver link into the list.
835 	 */
836 	TAILQ_FOREACH(dl, &passes, passlink) {
837 		if (dl->pass < new->pass)
838 			continue;
839 		if (dl->pass == new->pass)
840 			return;
841 		TAILQ_INSERT_BEFORE(dl, new, passlink);
842 		return;
843 	}
844 	TAILQ_INSERT_TAIL(&passes, new, passlink);
845 }
846 
847 /**
848  * @brief Raise the current bus pass
849  *
850  * Raise the current bus pass level to @p pass.  Call the BUS_NEW_PASS()
851  * method on the root bus to kick off a new device tree scan for each
852  * new pass level that has at least one driver.
853  */
854 void
855 bus_set_pass(int pass)
856 {
857 	struct driverlink *dl;
858 
859 	if (bus_current_pass > pass)
860 		panic("Attempt to lower bus pass level");
861 
862 	TAILQ_FOREACH(dl, &passes, passlink) {
863 		/* Skip pass values below the current pass level. */
864 		if (dl->pass <= bus_current_pass)
865 			continue;
866 
867 		/*
868 		 * Bail once we hit a driver with a pass level that is
869 		 * too high.
870 		 */
871 		if (dl->pass > pass)
872 			break;
873 
874 		/*
875 		 * Raise the pass level to the next level and rescan
876 		 * the tree.
877 		 */
878 		bus_current_pass = dl->pass;
879 		BUS_NEW_PASS(root_bus);
880 	}
881 
882 	/*
883 	 * If there isn't a driver registered for the requested pass,
884 	 * then bus_current_pass might still be less than 'pass'.  Set
885 	 * it to 'pass' in that case.
886 	 */
887 	if (bus_current_pass < pass)
888 		bus_current_pass = pass;
889 	KASSERT(bus_current_pass == pass, ("Failed to update bus pass level"));
890 }
891 
892 /*
893  * Devclass implementation
894  */
895 
896 static devclass_list_t devclasses = TAILQ_HEAD_INITIALIZER(devclasses);
897 
898 /**
899  * @internal
900  * @brief Find or create a device class
901  *
902  * If a device class with the name @p classname exists, return it,
903  * otherwise if @p create is non-zero create and return a new device
904  * class.
905  *
906  * If @p parentname is non-NULL, the parent of the devclass is set to
907  * the devclass of that name.
908  *
909  * @param classname	the devclass name to find or create
910  * @param parentname	the parent devclass name or @c NULL
911  * @param create	non-zero to create a devclass
912  */
913 static devclass_t
914 devclass_find_internal(const char *classname, const char *parentname,
915 		       int create)
916 {
917 	devclass_t dc;
918 
919 	PDEBUG(("looking for %s", classname));
920 	if (!classname)
921 		return (NULL);
922 
923 	TAILQ_FOREACH(dc, &devclasses, link) {
924 		if (!strcmp(dc->name, classname))
925 			break;
926 	}
927 
928 	if (create && !dc) {
929 		PDEBUG(("creating %s", classname));
930 		dc = malloc(sizeof(struct devclass) + strlen(classname) + 1,
931 		    M_BUS, M_NOWAIT | M_ZERO);
932 		if (!dc)
933 			return (NULL);
934 		dc->parent = NULL;
935 		dc->name = (char*) (dc + 1);
936 		strcpy(dc->name, classname);
937 		TAILQ_INIT(&dc->drivers);
938 		TAILQ_INSERT_TAIL(&devclasses, dc, link);
939 
940 		bus_data_generation_update();
941 	}
942 
943 	/*
944 	 * If a parent class is specified, then set that as our parent so
945 	 * that this devclass will support drivers for the parent class as
946 	 * well.  If the parent class has the same name don't do this though
947 	 * as it creates a cycle that can trigger an infinite loop in
948 	 * device_probe_child() if a device exists for which there is no
949 	 * suitable driver.
950 	 */
951 	if (parentname && dc && !dc->parent &&
952 	    strcmp(classname, parentname) != 0) {
953 		dc->parent = devclass_find_internal(parentname, NULL, TRUE);
954 		dc->parent->flags |= DC_HAS_CHILDREN;
955 	}
956 
957 	return (dc);
958 }
959 
960 /**
961  * @brief Create a device class
962  *
963  * If a device class with the name @p classname exists, return it,
964  * otherwise create and return a new device class.
965  *
966  * @param classname	the devclass name to find or create
967  */
968 devclass_t
969 devclass_create(const char *classname)
970 {
971 	return (devclass_find_internal(classname, NULL, TRUE));
972 }
973 
974 /**
975  * @brief Find a device class
976  *
977  * If a device class with the name @p classname exists, return it,
978  * otherwise return @c NULL.
979  *
980  * @param classname	the devclass name to find
981  */
982 devclass_t
983 devclass_find(const char *classname)
984 {
985 	return (devclass_find_internal(classname, NULL, FALSE));
986 }
987 
988 /**
989  * @brief Register that a device driver has been added to a devclass
990  *
991  * Register that a device driver has been added to a devclass.  This
992  * is called by devclass_add_driver to accomplish the recursive
993  * notification of all the children classes of dc, as well as dc.
994  * Each layer will have BUS_DRIVER_ADDED() called for all instances of
995  * the devclass.
996  *
997  * We do a full search here of the devclass list at each iteration
998  * level to save storing children-lists in the devclass structure.  If
999  * we ever move beyond a few dozen devices doing this, we may need to
1000  * reevaluate...
1001  *
1002  * @param dc		the devclass to edit
1003  * @param driver	the driver that was just added
1004  */
1005 static void
1006 devclass_driver_added(devclass_t dc, driver_t *driver)
1007 {
1008 	devclass_t parent;
1009 	int i;
1010 
1011 	/*
1012 	 * Call BUS_DRIVER_ADDED for any existing busses in this class.
1013 	 */
1014 	for (i = 0; i < dc->maxunit; i++)
1015 		if (dc->devices[i] && device_is_attached(dc->devices[i]))
1016 			BUS_DRIVER_ADDED(dc->devices[i], driver);
1017 
1018 	/*
1019 	 * Walk through the children classes.  Since we only keep a
1020 	 * single parent pointer around, we walk the entire list of
1021 	 * devclasses looking for children.  We set the
1022 	 * DC_HAS_CHILDREN flag when a child devclass is created on
1023 	 * the parent, so we only walk the list for those devclasses
1024 	 * that have children.
1025 	 */
1026 	if (!(dc->flags & DC_HAS_CHILDREN))
1027 		return;
1028 	parent = dc;
1029 	TAILQ_FOREACH(dc, &devclasses, link) {
1030 		if (dc->parent == parent)
1031 			devclass_driver_added(dc, driver);
1032 	}
1033 }
1034 
1035 /**
1036  * @brief Add a device driver to a device class
1037  *
1038  * Add a device driver to a devclass. This is normally called
1039  * automatically by DRIVER_MODULE(). The BUS_DRIVER_ADDED() method of
1040  * all devices in the devclass will be called to allow them to attempt
1041  * to re-probe any unmatched children.
1042  *
1043  * @param dc		the devclass to edit
1044  * @param driver	the driver to register
1045  */
1046 int
1047 devclass_add_driver(devclass_t dc, driver_t *driver, int pass, devclass_t *dcp)
1048 {
1049 	driverlink_t dl;
1050 	const char *parentname;
1051 
1052 	PDEBUG(("%s", DRIVERNAME(driver)));
1053 
1054 	/* Don't allow invalid pass values. */
1055 	if (pass <= BUS_PASS_ROOT)
1056 		return (EINVAL);
1057 
1058 	dl = malloc(sizeof *dl, M_BUS, M_NOWAIT|M_ZERO);
1059 	if (!dl)
1060 		return (ENOMEM);
1061 
1062 	/*
1063 	 * Compile the driver's methods. Also increase the reference count
1064 	 * so that the class doesn't get freed when the last instance
1065 	 * goes. This means we can safely use static methods and avoids a
1066 	 * double-free in devclass_delete_driver.
1067 	 */
1068 	kobj_class_compile((kobj_class_t) driver);
1069 
1070 	/*
1071 	 * If the driver has any base classes, make the
1072 	 * devclass inherit from the devclass of the driver's
1073 	 * first base class. This will allow the system to
1074 	 * search for drivers in both devclasses for children
1075 	 * of a device using this driver.
1076 	 */
1077 	if (driver->baseclasses)
1078 		parentname = driver->baseclasses[0]->name;
1079 	else
1080 		parentname = NULL;
1081 	*dcp = devclass_find_internal(driver->name, parentname, TRUE);
1082 
1083 	dl->driver = driver;
1084 	TAILQ_INSERT_TAIL(&dc->drivers, dl, link);
1085 	driver->refs++;		/* XXX: kobj_mtx */
1086 	dl->pass = pass;
1087 	driver_register_pass(dl);
1088 
1089 	devclass_driver_added(dc, driver);
1090 	bus_data_generation_update();
1091 	return (0);
1092 }
1093 
1094 /**
1095  * @brief Register that a device driver has been deleted from a devclass
1096  *
1097  * Register that a device driver has been removed from a devclass.
1098  * This is called by devclass_delete_driver to accomplish the
1099  * recursive notification of all the children classes of busclass, as
1100  * well as busclass.  Each layer will attempt to detach the driver
1101  * from any devices that are children of the bus's devclass.  The function
1102  * will return an error if a device fails to detach.
1103  *
1104  * We do a full search here of the devclass list at each iteration
1105  * level to save storing children-lists in the devclass structure.  If
1106  * we ever move beyond a few dozen devices doing this, we may need to
1107  * reevaluate...
1108  *
1109  * @param busclass	the devclass of the parent bus
1110  * @param dc		the devclass of the driver being deleted
1111  * @param driver	the driver being deleted
1112  */
1113 static int
1114 devclass_driver_deleted(devclass_t busclass, devclass_t dc, driver_t *driver)
1115 {
1116 	devclass_t parent;
1117 	device_t dev;
1118 	int error, i;
1119 
1120 	/*
1121 	 * Disassociate from any devices.  We iterate through all the
1122 	 * devices in the devclass of the driver and detach any which are
1123 	 * using the driver and which have a parent in the devclass which
1124 	 * we are deleting from.
1125 	 *
1126 	 * Note that since a driver can be in multiple devclasses, we
1127 	 * should not detach devices which are not children of devices in
1128 	 * the affected devclass.
1129 	 */
1130 	for (i = 0; i < dc->maxunit; i++) {
1131 		if (dc->devices[i]) {
1132 			dev = dc->devices[i];
1133 			if (dev->driver == driver && dev->parent &&
1134 			    dev->parent->devclass == busclass) {
1135 				if ((error = device_detach(dev)) != 0)
1136 					return (error);
1137 				BUS_PROBE_NOMATCH(dev->parent, dev);
1138 				devnomatch(dev);
1139 				dev->flags |= DF_DONENOMATCH;
1140 			}
1141 		}
1142 	}
1143 
1144 	/*
1145 	 * Walk through the children classes.  Since we only keep a
1146 	 * single parent pointer around, we walk the entire list of
1147 	 * devclasses looking for children.  We set the
1148 	 * DC_HAS_CHILDREN flag when a child devclass is created on
1149 	 * the parent, so we only walk the list for those devclasses
1150 	 * that have children.
1151 	 */
1152 	if (!(busclass->flags & DC_HAS_CHILDREN))
1153 		return (0);
1154 	parent = busclass;
1155 	TAILQ_FOREACH(busclass, &devclasses, link) {
1156 		if (busclass->parent == parent) {
1157 			error = devclass_driver_deleted(busclass, dc, driver);
1158 			if (error)
1159 				return (error);
1160 		}
1161 	}
1162 	return (0);
1163 }
1164 
1165 /**
1166  * @brief Delete a device driver from a device class
1167  *
1168  * Delete a device driver from a devclass. This is normally called
1169  * automatically by DRIVER_MODULE().
1170  *
1171  * If the driver is currently attached to any devices,
1172  * devclass_delete_driver() will first attempt to detach from each
1173  * device. If one of the detach calls fails, the driver will not be
1174  * deleted.
1175  *
1176  * @param dc		the devclass to edit
1177  * @param driver	the driver to unregister
1178  */
1179 int
1180 devclass_delete_driver(devclass_t busclass, driver_t *driver)
1181 {
1182 	devclass_t dc = devclass_find(driver->name);
1183 	driverlink_t dl;
1184 	int error;
1185 
1186 	PDEBUG(("%s from devclass %s", driver->name, DEVCLANAME(busclass)));
1187 
1188 	if (!dc)
1189 		return (0);
1190 
1191 	/*
1192 	 * Find the link structure in the bus' list of drivers.
1193 	 */
1194 	TAILQ_FOREACH(dl, &busclass->drivers, link) {
1195 		if (dl->driver == driver)
1196 			break;
1197 	}
1198 
1199 	if (!dl) {
1200 		PDEBUG(("%s not found in %s list", driver->name,
1201 		    busclass->name));
1202 		return (ENOENT);
1203 	}
1204 
1205 	error = devclass_driver_deleted(busclass, dc, driver);
1206 	if (error != 0)
1207 		return (error);
1208 
1209 	TAILQ_REMOVE(&busclass->drivers, dl, link);
1210 	free(dl, M_BUS);
1211 
1212 	/* XXX: kobj_mtx */
1213 	driver->refs--;
1214 	if (driver->refs == 0)
1215 		kobj_class_free((kobj_class_t) driver);
1216 
1217 	bus_data_generation_update();
1218 	return (0);
1219 }
1220 
1221 /**
1222  * @brief Quiesces a set of device drivers from a device class
1223  *
1224  * Quiesce a device driver from a devclass. This is normally called
1225  * automatically by DRIVER_MODULE().
1226  *
1227  * If the driver is currently attached to any devices,
1228  * devclass_quiesece_driver() will first attempt to quiesce each
1229  * device.
1230  *
1231  * @param dc		the devclass to edit
1232  * @param driver	the driver to unregister
1233  */
1234 static int
1235 devclass_quiesce_driver(devclass_t busclass, driver_t *driver)
1236 {
1237 	devclass_t dc = devclass_find(driver->name);
1238 	driverlink_t dl;
1239 	device_t dev;
1240 	int i;
1241 	int error;
1242 
1243 	PDEBUG(("%s from devclass %s", driver->name, DEVCLANAME(busclass)));
1244 
1245 	if (!dc)
1246 		return (0);
1247 
1248 	/*
1249 	 * Find the link structure in the bus' list of drivers.
1250 	 */
1251 	TAILQ_FOREACH(dl, &busclass->drivers, link) {
1252 		if (dl->driver == driver)
1253 			break;
1254 	}
1255 
1256 	if (!dl) {
1257 		PDEBUG(("%s not found in %s list", driver->name,
1258 		    busclass->name));
1259 		return (ENOENT);
1260 	}
1261 
1262 	/*
1263 	 * Quiesce all devices.  We iterate through all the devices in
1264 	 * the devclass of the driver and quiesce any which are using
1265 	 * the driver and which have a parent in the devclass which we
1266 	 * are quiescing.
1267 	 *
1268 	 * Note that since a driver can be in multiple devclasses, we
1269 	 * should not quiesce devices which are not children of
1270 	 * devices in the affected devclass.
1271 	 */
1272 	for (i = 0; i < dc->maxunit; i++) {
1273 		if (dc->devices[i]) {
1274 			dev = dc->devices[i];
1275 			if (dev->driver == driver && dev->parent &&
1276 			    dev->parent->devclass == busclass) {
1277 				if ((error = device_quiesce(dev)) != 0)
1278 					return (error);
1279 			}
1280 		}
1281 	}
1282 
1283 	return (0);
1284 }
1285 
1286 /**
1287  * @internal
1288  */
1289 static driverlink_t
1290 devclass_find_driver_internal(devclass_t dc, const char *classname)
1291 {
1292 	driverlink_t dl;
1293 
1294 	PDEBUG(("%s in devclass %s", classname, DEVCLANAME(dc)));
1295 
1296 	TAILQ_FOREACH(dl, &dc->drivers, link) {
1297 		if (!strcmp(dl->driver->name, classname))
1298 			return (dl);
1299 	}
1300 
1301 	PDEBUG(("not found"));
1302 	return (NULL);
1303 }
1304 
1305 /**
1306  * @brief Return the name of the devclass
1307  */
1308 const char *
1309 devclass_get_name(devclass_t dc)
1310 {
1311 	return (dc->name);
1312 }
1313 
1314 /**
1315  * @brief Find a device given a unit number
1316  *
1317  * @param dc		the devclass to search
1318  * @param unit		the unit number to search for
1319  *
1320  * @returns		the device with the given unit number or @c
1321  *			NULL if there is no such device
1322  */
1323 device_t
1324 devclass_get_device(devclass_t dc, int unit)
1325 {
1326 	if (dc == NULL || unit < 0 || unit >= dc->maxunit)
1327 		return (NULL);
1328 	return (dc->devices[unit]);
1329 }
1330 
1331 /**
1332  * @brief Find the softc field of a device given a unit number
1333  *
1334  * @param dc		the devclass to search
1335  * @param unit		the unit number to search for
1336  *
1337  * @returns		the softc field of the device with the given
1338  *			unit number or @c NULL if there is no such
1339  *			device
1340  */
1341 void *
1342 devclass_get_softc(devclass_t dc, int unit)
1343 {
1344 	device_t dev;
1345 
1346 	dev = devclass_get_device(dc, unit);
1347 	if (!dev)
1348 		return (NULL);
1349 
1350 	return (device_get_softc(dev));
1351 }
1352 
1353 /**
1354  * @brief Get a list of devices in the devclass
1355  *
1356  * An array containing a list of all the devices in the given devclass
1357  * is allocated and returned in @p *devlistp. The number of devices
1358  * in the array is returned in @p *devcountp. The caller should free
1359  * the array using @c free(p, M_TEMP), even if @p *devcountp is 0.
1360  *
1361  * @param dc		the devclass to examine
1362  * @param devlistp	points at location for array pointer return
1363  *			value
1364  * @param devcountp	points at location for array size return value
1365  *
1366  * @retval 0		success
1367  * @retval ENOMEM	the array allocation failed
1368  */
1369 int
1370 devclass_get_devices(devclass_t dc, device_t **devlistp, int *devcountp)
1371 {
1372 	int count, i;
1373 	device_t *list;
1374 
1375 	count = devclass_get_count(dc);
1376 	list = malloc(count * sizeof(device_t), M_TEMP, M_NOWAIT|M_ZERO);
1377 	if (!list)
1378 		return (ENOMEM);
1379 
1380 	count = 0;
1381 	for (i = 0; i < dc->maxunit; i++) {
1382 		if (dc->devices[i]) {
1383 			list[count] = dc->devices[i];
1384 			count++;
1385 		}
1386 	}
1387 
1388 	*devlistp = list;
1389 	*devcountp = count;
1390 
1391 	return (0);
1392 }
1393 
1394 /**
1395  * @brief Get a list of drivers in the devclass
1396  *
1397  * An array containing a list of pointers to all the drivers in the
1398  * given devclass is allocated and returned in @p *listp.  The number
1399  * of drivers in the array is returned in @p *countp. The caller should
1400  * free the array using @c free(p, M_TEMP).
1401  *
1402  * @param dc		the devclass to examine
1403  * @param listp		gives location for array pointer return value
1404  * @param countp	gives location for number of array elements
1405  *			return value
1406  *
1407  * @retval 0		success
1408  * @retval ENOMEM	the array allocation failed
1409  */
1410 int
1411 devclass_get_drivers(devclass_t dc, driver_t ***listp, int *countp)
1412 {
1413 	driverlink_t dl;
1414 	driver_t **list;
1415 	int count;
1416 
1417 	count = 0;
1418 	TAILQ_FOREACH(dl, &dc->drivers, link)
1419 		count++;
1420 	list = malloc(count * sizeof(driver_t *), M_TEMP, M_NOWAIT);
1421 	if (list == NULL)
1422 		return (ENOMEM);
1423 
1424 	count = 0;
1425 	TAILQ_FOREACH(dl, &dc->drivers, link) {
1426 		list[count] = dl->driver;
1427 		count++;
1428 	}
1429 	*listp = list;
1430 	*countp = count;
1431 
1432 	return (0);
1433 }
1434 
1435 /**
1436  * @brief Get the number of devices in a devclass
1437  *
1438  * @param dc		the devclass to examine
1439  */
1440 int
1441 devclass_get_count(devclass_t dc)
1442 {
1443 	int count, i;
1444 
1445 	count = 0;
1446 	for (i = 0; i < dc->maxunit; i++)
1447 		if (dc->devices[i])
1448 			count++;
1449 	return (count);
1450 }
1451 
1452 /**
1453  * @brief Get the maximum unit number used in a devclass
1454  *
1455  * Note that this is one greater than the highest currently-allocated
1456  * unit.  If a null devclass_t is passed in, -1 is returned to indicate
1457  * that not even the devclass has been allocated yet.
1458  *
1459  * @param dc		the devclass to examine
1460  */
1461 int
1462 devclass_get_maxunit(devclass_t dc)
1463 {
1464 	if (dc == NULL)
1465 		return (-1);
1466 	return (dc->maxunit);
1467 }
1468 
1469 /**
1470  * @brief Find a free unit number in a devclass
1471  *
1472  * This function searches for the first unused unit number greater
1473  * that or equal to @p unit.
1474  *
1475  * @param dc		the devclass to examine
1476  * @param unit		the first unit number to check
1477  */
1478 int
1479 devclass_find_free_unit(devclass_t dc, int unit)
1480 {
1481 	if (dc == NULL)
1482 		return (unit);
1483 	while (unit < dc->maxunit && dc->devices[unit] != NULL)
1484 		unit++;
1485 	return (unit);
1486 }
1487 
1488 /**
1489  * @brief Set the parent of a devclass
1490  *
1491  * The parent class is normally initialised automatically by
1492  * DRIVER_MODULE().
1493  *
1494  * @param dc		the devclass to edit
1495  * @param pdc		the new parent devclass
1496  */
1497 void
1498 devclass_set_parent(devclass_t dc, devclass_t pdc)
1499 {
1500 	dc->parent = pdc;
1501 }
1502 
1503 /**
1504  * @brief Get the parent of a devclass
1505  *
1506  * @param dc		the devclass to examine
1507  */
1508 devclass_t
1509 devclass_get_parent(devclass_t dc)
1510 {
1511 	return (dc->parent);
1512 }
1513 
1514 struct sysctl_ctx_list *
1515 devclass_get_sysctl_ctx(devclass_t dc)
1516 {
1517 	return (&dc->sysctl_ctx);
1518 }
1519 
1520 struct sysctl_oid *
1521 devclass_get_sysctl_tree(devclass_t dc)
1522 {
1523 	return (dc->sysctl_tree);
1524 }
1525 
1526 /**
1527  * @internal
1528  * @brief Allocate a unit number
1529  *
1530  * On entry, @p *unitp is the desired unit number (or @c -1 if any
1531  * will do). The allocated unit number is returned in @p *unitp.
1532 
1533  * @param dc		the devclass to allocate from
1534  * @param unitp		points at the location for the allocated unit
1535  *			number
1536  *
1537  * @retval 0		success
1538  * @retval EEXIST	the requested unit number is already allocated
1539  * @retval ENOMEM	memory allocation failure
1540  */
1541 static int
1542 devclass_alloc_unit(devclass_t dc, device_t dev, int *unitp)
1543 {
1544 	const char *s;
1545 	int unit = *unitp;
1546 
1547 	PDEBUG(("unit %d in devclass %s", unit, DEVCLANAME(dc)));
1548 
1549 	/* Ask the parent bus if it wants to wire this device. */
1550 	if (unit == -1)
1551 		BUS_HINT_DEVICE_UNIT(device_get_parent(dev), dev, dc->name,
1552 		    &unit);
1553 
1554 	/* If we were given a wired unit number, check for existing device */
1555 	/* XXX imp XXX */
1556 	if (unit != -1) {
1557 		if (unit >= 0 && unit < dc->maxunit &&
1558 		    dc->devices[unit] != NULL) {
1559 			if (bootverbose)
1560 				printf("%s: %s%d already exists; skipping it\n",
1561 				    dc->name, dc->name, *unitp);
1562 			return (EEXIST);
1563 		}
1564 	} else {
1565 		/* Unwired device, find the next available slot for it */
1566 		unit = 0;
1567 		for (unit = 0;; unit++) {
1568 			/* If there is an "at" hint for a unit then skip it. */
1569 			if (resource_string_value(dc->name, unit, "at", &s) ==
1570 			    0)
1571 				continue;
1572 
1573 			/* If this device slot is already in use, skip it. */
1574 			if (unit < dc->maxunit && dc->devices[unit] != NULL)
1575 				continue;
1576 
1577 			break;
1578 		}
1579 	}
1580 
1581 	/*
1582 	 * We've selected a unit beyond the length of the table, so let's
1583 	 * extend the table to make room for all units up to and including
1584 	 * this one.
1585 	 */
1586 	if (unit >= dc->maxunit) {
1587 		device_t *newlist, *oldlist;
1588 		int newsize;
1589 
1590 		oldlist = dc->devices;
1591 		newsize = roundup((unit + 1), MINALLOCSIZE / sizeof(device_t));
1592 		newlist = malloc(sizeof(device_t) * newsize, M_BUS, M_NOWAIT);
1593 		if (!newlist)
1594 			return (ENOMEM);
1595 		if (oldlist != NULL)
1596 			bcopy(oldlist, newlist, sizeof(device_t) * dc->maxunit);
1597 		bzero(newlist + dc->maxunit,
1598 		    sizeof(device_t) * (newsize - dc->maxunit));
1599 		dc->devices = newlist;
1600 		dc->maxunit = newsize;
1601 		if (oldlist != NULL)
1602 			free(oldlist, M_BUS);
1603 	}
1604 	PDEBUG(("now: unit %d in devclass %s", unit, DEVCLANAME(dc)));
1605 
1606 	*unitp = unit;
1607 	return (0);
1608 }
1609 
1610 /**
1611  * @internal
1612  * @brief Add a device to a devclass
1613  *
1614  * A unit number is allocated for the device (using the device's
1615  * preferred unit number if any) and the device is registered in the
1616  * devclass. This allows the device to be looked up by its unit
1617  * number, e.g. by decoding a dev_t minor number.
1618  *
1619  * @param dc		the devclass to add to
1620  * @param dev		the device to add
1621  *
1622  * @retval 0		success
1623  * @retval EEXIST	the requested unit number is already allocated
1624  * @retval ENOMEM	memory allocation failure
1625  */
1626 static int
1627 devclass_add_device(devclass_t dc, device_t dev)
1628 {
1629 	int buflen, error;
1630 
1631 	PDEBUG(("%s in devclass %s", DEVICENAME(dev), DEVCLANAME(dc)));
1632 
1633 	buflen = snprintf(NULL, 0, "%s%d$", dc->name, INT_MAX);
1634 	if (buflen < 0)
1635 		return (ENOMEM);
1636 	dev->nameunit = malloc(buflen, M_BUS, M_NOWAIT|M_ZERO);
1637 	if (!dev->nameunit)
1638 		return (ENOMEM);
1639 
1640 	if ((error = devclass_alloc_unit(dc, dev, &dev->unit)) != 0) {
1641 		free(dev->nameunit, M_BUS);
1642 		dev->nameunit = NULL;
1643 		return (error);
1644 	}
1645 	dc->devices[dev->unit] = dev;
1646 	dev->devclass = dc;
1647 	snprintf(dev->nameunit, buflen, "%s%d", dc->name, dev->unit);
1648 
1649 	return (0);
1650 }
1651 
1652 /**
1653  * @internal
1654  * @brief Delete a device from a devclass
1655  *
1656  * The device is removed from the devclass's device list and its unit
1657  * number is freed.
1658 
1659  * @param dc		the devclass to delete from
1660  * @param dev		the device to delete
1661  *
1662  * @retval 0		success
1663  */
1664 static int
1665 devclass_delete_device(devclass_t dc, device_t dev)
1666 {
1667 	if (!dc || !dev)
1668 		return (0);
1669 
1670 	PDEBUG(("%s in devclass %s", DEVICENAME(dev), DEVCLANAME(dc)));
1671 
1672 	if (dev->devclass != dc || dc->devices[dev->unit] != dev)
1673 		panic("devclass_delete_device: inconsistent device class");
1674 	dc->devices[dev->unit] = NULL;
1675 	if (dev->flags & DF_WILDCARD)
1676 		dev->unit = -1;
1677 	dev->devclass = NULL;
1678 	free(dev->nameunit, M_BUS);
1679 	dev->nameunit = NULL;
1680 
1681 	return (0);
1682 }
1683 
1684 /**
1685  * @internal
1686  * @brief Make a new device and add it as a child of @p parent
1687  *
1688  * @param parent	the parent of the new device
1689  * @param name		the devclass name of the new device or @c NULL
1690  *			to leave the devclass unspecified
1691  * @parem unit		the unit number of the new device of @c -1 to
1692  *			leave the unit number unspecified
1693  *
1694  * @returns the new device
1695  */
1696 static device_t
1697 make_device(device_t parent, const char *name, int unit)
1698 {
1699 	device_t dev;
1700 	devclass_t dc;
1701 
1702 	PDEBUG(("%s at %s as unit %d", name, DEVICENAME(parent), unit));
1703 
1704 	if (name) {
1705 		dc = devclass_find_internal(name, NULL, TRUE);
1706 		if (!dc) {
1707 			printf("make_device: can't find device class %s\n",
1708 			    name);
1709 			return (NULL);
1710 		}
1711 	} else {
1712 		dc = NULL;
1713 	}
1714 
1715 	dev = malloc(sizeof(struct device), M_BUS, M_NOWAIT|M_ZERO);
1716 	if (!dev)
1717 		return (NULL);
1718 
1719 	dev->parent = parent;
1720 	TAILQ_INIT(&dev->children);
1721 	kobj_init((kobj_t) dev, &null_class);
1722 	dev->driver = NULL;
1723 	dev->devclass = NULL;
1724 	dev->unit = unit;
1725 	dev->nameunit = NULL;
1726 	dev->desc = NULL;
1727 	dev->busy = 0;
1728 	dev->devflags = 0;
1729 	dev->flags = DF_ENABLED;
1730 	dev->order = 0;
1731 	if (unit == -1)
1732 		dev->flags |= DF_WILDCARD;
1733 	if (name) {
1734 		dev->flags |= DF_FIXEDCLASS;
1735 		if (devclass_add_device(dc, dev)) {
1736 			kobj_delete((kobj_t) dev, M_BUS);
1737 			return (NULL);
1738 		}
1739 	}
1740 	dev->ivars = NULL;
1741 	dev->softc = NULL;
1742 
1743 	dev->state = DS_NOTPRESENT;
1744 
1745 	TAILQ_INSERT_TAIL(&bus_data_devices, dev, devlink);
1746 	bus_data_generation_update();
1747 
1748 	return (dev);
1749 }
1750 
1751 /**
1752  * @internal
1753  * @brief Print a description of a device.
1754  */
1755 static int
1756 device_print_child(device_t dev, device_t child)
1757 {
1758 	int retval = 0;
1759 
1760 	if (device_is_alive(child))
1761 		retval += BUS_PRINT_CHILD(dev, child);
1762 	else
1763 		retval += device_printf(child, " not found\n");
1764 
1765 	return (retval);
1766 }
1767 
1768 /**
1769  * @brief Create a new device
1770  *
1771  * This creates a new device and adds it as a child of an existing
1772  * parent device. The new device will be added after the last existing
1773  * child with order zero.
1774  *
1775  * @param dev		the device which will be the parent of the
1776  *			new child device
1777  * @param name		devclass name for new device or @c NULL if not
1778  *			specified
1779  * @param unit		unit number for new device or @c -1 if not
1780  *			specified
1781  *
1782  * @returns		the new device
1783  */
1784 device_t
1785 device_add_child(device_t dev, const char *name, int unit)
1786 {
1787 	return (device_add_child_ordered(dev, 0, name, unit));
1788 }
1789 
1790 /**
1791  * @brief Create a new device
1792  *
1793  * This creates a new device and adds it as a child of an existing
1794  * parent device. The new device will be added after the last existing
1795  * child with the same order.
1796  *
1797  * @param dev		the device which will be the parent of the
1798  *			new child device
1799  * @param order		a value which is used to partially sort the
1800  *			children of @p dev - devices created using
1801  *			lower values of @p order appear first in @p
1802  *			dev's list of children
1803  * @param name		devclass name for new device or @c NULL if not
1804  *			specified
1805  * @param unit		unit number for new device or @c -1 if not
1806  *			specified
1807  *
1808  * @returns		the new device
1809  */
1810 device_t
1811 device_add_child_ordered(device_t dev, u_int order, const char *name, int unit)
1812 {
1813 	device_t child;
1814 	device_t place;
1815 
1816 	PDEBUG(("%s at %s with order %u as unit %d",
1817 	    name, DEVICENAME(dev), order, unit));
1818 	KASSERT(name != NULL || unit == -1,
1819 	    ("child device with wildcard name and specific unit number"));
1820 
1821 	child = make_device(dev, name, unit);
1822 	if (child == NULL)
1823 		return (child);
1824 	child->order = order;
1825 
1826 	TAILQ_FOREACH(place, &dev->children, link) {
1827 		if (place->order > order)
1828 			break;
1829 	}
1830 
1831 	if (place) {
1832 		/*
1833 		 * The device 'place' is the first device whose order is
1834 		 * greater than the new child.
1835 		 */
1836 		TAILQ_INSERT_BEFORE(place, child, link);
1837 	} else {
1838 		/*
1839 		 * The new child's order is greater or equal to the order of
1840 		 * any existing device. Add the child to the tail of the list.
1841 		 */
1842 		TAILQ_INSERT_TAIL(&dev->children, child, link);
1843 	}
1844 
1845 	bus_data_generation_update();
1846 	return (child);
1847 }
1848 
1849 /**
1850  * @brief Delete a device
1851  *
1852  * This function deletes a device along with all of its children. If
1853  * the device currently has a driver attached to it, the device is
1854  * detached first using device_detach().
1855  *
1856  * @param dev		the parent device
1857  * @param child		the device to delete
1858  *
1859  * @retval 0		success
1860  * @retval non-zero	a unit error code describing the error
1861  */
1862 int
1863 device_delete_child(device_t dev, device_t child)
1864 {
1865 	int error;
1866 	device_t grandchild;
1867 
1868 	PDEBUG(("%s from %s", DEVICENAME(child), DEVICENAME(dev)));
1869 
1870 	/* remove children first */
1871 	while ((grandchild = TAILQ_FIRST(&child->children)) != NULL) {
1872 		error = device_delete_child(child, grandchild);
1873 		if (error)
1874 			return (error);
1875 	}
1876 
1877 	if ((error = device_detach(child)) != 0)
1878 		return (error);
1879 	if (child->devclass)
1880 		devclass_delete_device(child->devclass, child);
1881 	if (child->parent)
1882 		BUS_CHILD_DELETED(dev, child);
1883 	TAILQ_REMOVE(&dev->children, child, link);
1884 	TAILQ_REMOVE(&bus_data_devices, child, devlink);
1885 	kobj_delete((kobj_t) child, M_BUS);
1886 
1887 	bus_data_generation_update();
1888 	return (0);
1889 }
1890 
1891 /**
1892  * @brief Delete all children devices of the given device, if any.
1893  *
1894  * This function deletes all children devices of the given device, if
1895  * any, using the device_delete_child() function for each device it
1896  * finds. If a child device cannot be deleted, this function will
1897  * return an error code.
1898  *
1899  * @param dev		the parent device
1900  *
1901  * @retval 0		success
1902  * @retval non-zero	a device would not detach
1903  */
1904 int
1905 device_delete_children(device_t dev)
1906 {
1907 	device_t child;
1908 	int error;
1909 
1910 	PDEBUG(("Deleting all children of %s", DEVICENAME(dev)));
1911 
1912 	error = 0;
1913 
1914 	while ((child = TAILQ_FIRST(&dev->children)) != NULL) {
1915 		error = device_delete_child(dev, child);
1916 		if (error) {
1917 			PDEBUG(("Failed deleting %s", DEVICENAME(child)));
1918 			break;
1919 		}
1920 	}
1921 	return (error);
1922 }
1923 
1924 /**
1925  * @brief Find a device given a unit number
1926  *
1927  * This is similar to devclass_get_devices() but only searches for
1928  * devices which have @p dev as a parent.
1929  *
1930  * @param dev		the parent device to search
1931  * @param unit		the unit number to search for.  If the unit is -1,
1932  *			return the first child of @p dev which has name
1933  *			@p classname (that is, the one with the lowest unit.)
1934  *
1935  * @returns		the device with the given unit number or @c
1936  *			NULL if there is no such device
1937  */
1938 device_t
1939 device_find_child(device_t dev, const char *classname, int unit)
1940 {
1941 	devclass_t dc;
1942 	device_t child;
1943 
1944 	dc = devclass_find(classname);
1945 	if (!dc)
1946 		return (NULL);
1947 
1948 	if (unit != -1) {
1949 		child = devclass_get_device(dc, unit);
1950 		if (child && child->parent == dev)
1951 			return (child);
1952 	} else {
1953 		for (unit = 0; unit < devclass_get_maxunit(dc); unit++) {
1954 			child = devclass_get_device(dc, unit);
1955 			if (child && child->parent == dev)
1956 				return (child);
1957 		}
1958 	}
1959 	return (NULL);
1960 }
1961 
1962 /**
1963  * @internal
1964  */
1965 static driverlink_t
1966 first_matching_driver(devclass_t dc, device_t dev)
1967 {
1968 	if (dev->devclass)
1969 		return (devclass_find_driver_internal(dc, dev->devclass->name));
1970 	return (TAILQ_FIRST(&dc->drivers));
1971 }
1972 
1973 /**
1974  * @internal
1975  */
1976 static driverlink_t
1977 next_matching_driver(devclass_t dc, device_t dev, driverlink_t last)
1978 {
1979 	if (dev->devclass) {
1980 		driverlink_t dl;
1981 		for (dl = TAILQ_NEXT(last, link); dl; dl = TAILQ_NEXT(dl, link))
1982 			if (!strcmp(dev->devclass->name, dl->driver->name))
1983 				return (dl);
1984 		return (NULL);
1985 	}
1986 	return (TAILQ_NEXT(last, link));
1987 }
1988 
1989 /**
1990  * @internal
1991  */
1992 int
1993 device_probe_child(device_t dev, device_t child)
1994 {
1995 	devclass_t dc;
1996 	driverlink_t best = NULL;
1997 	driverlink_t dl;
1998 	int result, pri = 0;
1999 	int hasclass = (child->devclass != NULL);
2000 
2001 	GIANT_REQUIRED;
2002 
2003 	dc = dev->devclass;
2004 	if (!dc)
2005 		panic("device_probe_child: parent device has no devclass");
2006 
2007 	/*
2008 	 * If the state is already probed, then return.  However, don't
2009 	 * return if we can rebid this object.
2010 	 */
2011 	if (child->state == DS_ALIVE && (child->flags & DF_REBID) == 0)
2012 		return (0);
2013 
2014 	for (; dc; dc = dc->parent) {
2015 		for (dl = first_matching_driver(dc, child);
2016 		     dl;
2017 		     dl = next_matching_driver(dc, child, dl)) {
2018 			/* If this driver's pass is too high, then ignore it. */
2019 			if (dl->pass > bus_current_pass)
2020 				continue;
2021 
2022 			PDEBUG(("Trying %s", DRIVERNAME(dl->driver)));
2023 			result = device_set_driver(child, dl->driver);
2024 			if (result == ENOMEM)
2025 				return (result);
2026 			else if (result != 0)
2027 				continue;
2028 			if (!hasclass) {
2029 				if (device_set_devclass(child,
2030 				    dl->driver->name) != 0) {
2031 					char const * devname =
2032 					    device_get_name(child);
2033 					if (devname == NULL)
2034 						devname = "(unknown)";
2035 					printf("driver bug: Unable to set "
2036 					    "devclass (class: %s "
2037 					    "devname: %s)\n",
2038 					    dl->driver->name,
2039 					    devname);
2040 					(void)device_set_driver(child, NULL);
2041 					continue;
2042 				}
2043 			}
2044 
2045 			/* Fetch any flags for the device before probing. */
2046 			resource_int_value(dl->driver->name, child->unit,
2047 			    "flags", &child->devflags);
2048 
2049 			result = DEVICE_PROBE(child);
2050 
2051 			/* Reset flags and devclass before the next probe. */
2052 			child->devflags = 0;
2053 			if (!hasclass)
2054 				(void)device_set_devclass(child, NULL);
2055 
2056 			/*
2057 			 * If the driver returns SUCCESS, there can be
2058 			 * no higher match for this device.
2059 			 */
2060 			if (result == 0) {
2061 				best = dl;
2062 				pri = 0;
2063 				break;
2064 			}
2065 
2066 			/*
2067 			 * The driver returned an error so it
2068 			 * certainly doesn't match.
2069 			 */
2070 			if (result > 0) {
2071 				(void)device_set_driver(child, NULL);
2072 				continue;
2073 			}
2074 
2075 			/*
2076 			 * A priority lower than SUCCESS, remember the
2077 			 * best matching driver. Initialise the value
2078 			 * of pri for the first match.
2079 			 */
2080 			if (best == NULL || result > pri) {
2081 				/*
2082 				 * Probes that return BUS_PROBE_NOWILDCARD
2083 				 * or lower only match on devices whose
2084 				 * driver was explicitly specified.
2085 				 */
2086 				if (result <= BUS_PROBE_NOWILDCARD &&
2087 				    !(child->flags & DF_FIXEDCLASS))
2088 					continue;
2089 				best = dl;
2090 				pri = result;
2091 				continue;
2092 			}
2093 		}
2094 		/*
2095 		 * If we have an unambiguous match in this devclass,
2096 		 * don't look in the parent.
2097 		 */
2098 		if (best && pri == 0)
2099 			break;
2100 	}
2101 
2102 	/*
2103 	 * If we found a driver, change state and initialise the devclass.
2104 	 */
2105 	/* XXX What happens if we rebid and got no best? */
2106 	if (best) {
2107 		/*
2108 		 * If this device was attached, and we were asked to
2109 		 * rescan, and it is a different driver, then we have
2110 		 * to detach the old driver and reattach this new one.
2111 		 * Note, we don't have to check for DF_REBID here
2112 		 * because if the state is > DS_ALIVE, we know it must
2113 		 * be.
2114 		 *
2115 		 * This assumes that all DF_REBID drivers can have
2116 		 * their probe routine called at any time and that
2117 		 * they are idempotent as well as completely benign in
2118 		 * normal operations.
2119 		 *
2120 		 * We also have to make sure that the detach
2121 		 * succeeded, otherwise we fail the operation (or
2122 		 * maybe it should just fail silently?  I'm torn).
2123 		 */
2124 		if (child->state > DS_ALIVE && best->driver != child->driver)
2125 			if ((result = device_detach(dev)) != 0)
2126 				return (result);
2127 
2128 		/* Set the winning driver, devclass, and flags. */
2129 		if (!child->devclass) {
2130 			result = device_set_devclass(child, best->driver->name);
2131 			if (result != 0)
2132 				return (result);
2133 		}
2134 		result = device_set_driver(child, best->driver);
2135 		if (result != 0)
2136 			return (result);
2137 		resource_int_value(best->driver->name, child->unit,
2138 		    "flags", &child->devflags);
2139 
2140 		if (pri < 0) {
2141 			/*
2142 			 * A bit bogus. Call the probe method again to make
2143 			 * sure that we have the right description.
2144 			 */
2145 			DEVICE_PROBE(child);
2146 #if 0
2147 			child->flags |= DF_REBID;
2148 #endif
2149 		} else
2150 			child->flags &= ~DF_REBID;
2151 		child->state = DS_ALIVE;
2152 
2153 		bus_data_generation_update();
2154 		return (0);
2155 	}
2156 
2157 	return (ENXIO);
2158 }
2159 
2160 /**
2161  * @brief Return the parent of a device
2162  */
2163 device_t
2164 device_get_parent(device_t dev)
2165 {
2166 	return (dev->parent);
2167 }
2168 
2169 /**
2170  * @brief Get a list of children of a device
2171  *
2172  * An array containing a list of all the children of the given device
2173  * is allocated and returned in @p *devlistp. The number of devices
2174  * in the array is returned in @p *devcountp. The caller should free
2175  * the array using @c free(p, M_TEMP).
2176  *
2177  * @param dev		the device to examine
2178  * @param devlistp	points at location for array pointer return
2179  *			value
2180  * @param devcountp	points at location for array size return value
2181  *
2182  * @retval 0		success
2183  * @retval ENOMEM	the array allocation failed
2184  */
2185 int
2186 device_get_children(device_t dev, device_t **devlistp, int *devcountp)
2187 {
2188 	int count;
2189 	device_t child;
2190 	device_t *list;
2191 
2192 	count = 0;
2193 	TAILQ_FOREACH(child, &dev->children, link) {
2194 		count++;
2195 	}
2196 	if (count == 0) {
2197 		*devlistp = NULL;
2198 		*devcountp = 0;
2199 		return (0);
2200 	}
2201 
2202 	list = malloc(count * sizeof(device_t), M_TEMP, M_NOWAIT|M_ZERO);
2203 	if (!list)
2204 		return (ENOMEM);
2205 
2206 	count = 0;
2207 	TAILQ_FOREACH(child, &dev->children, link) {
2208 		list[count] = child;
2209 		count++;
2210 	}
2211 
2212 	*devlistp = list;
2213 	*devcountp = count;
2214 
2215 	return (0);
2216 }
2217 
2218 /**
2219  * @brief Return the current driver for the device or @c NULL if there
2220  * is no driver currently attached
2221  */
2222 driver_t *
2223 device_get_driver(device_t dev)
2224 {
2225 	return (dev->driver);
2226 }
2227 
2228 /**
2229  * @brief Return the current devclass for the device or @c NULL if
2230  * there is none.
2231  */
2232 devclass_t
2233 device_get_devclass(device_t dev)
2234 {
2235 	return (dev->devclass);
2236 }
2237 
2238 /**
2239  * @brief Return the name of the device's devclass or @c NULL if there
2240  * is none.
2241  */
2242 const char *
2243 device_get_name(device_t dev)
2244 {
2245 	if (dev != NULL && dev->devclass)
2246 		return (devclass_get_name(dev->devclass));
2247 	return (NULL);
2248 }
2249 
2250 /**
2251  * @brief Return a string containing the device's devclass name
2252  * followed by an ascii representation of the device's unit number
2253  * (e.g. @c "foo2").
2254  */
2255 const char *
2256 device_get_nameunit(device_t dev)
2257 {
2258 	return (dev->nameunit);
2259 }
2260 
2261 /**
2262  * @brief Return the device's unit number.
2263  */
2264 int
2265 device_get_unit(device_t dev)
2266 {
2267 	return (dev->unit);
2268 }
2269 
2270 /**
2271  * @brief Return the device's description string
2272  */
2273 const char *
2274 device_get_desc(device_t dev)
2275 {
2276 	return (dev->desc);
2277 }
2278 
2279 /**
2280  * @brief Return the device's flags
2281  */
2282 uint32_t
2283 device_get_flags(device_t dev)
2284 {
2285 	return (dev->devflags);
2286 }
2287 
2288 struct sysctl_ctx_list *
2289 device_get_sysctl_ctx(device_t dev)
2290 {
2291 	return (&dev->sysctl_ctx);
2292 }
2293 
2294 struct sysctl_oid *
2295 device_get_sysctl_tree(device_t dev)
2296 {
2297 	return (dev->sysctl_tree);
2298 }
2299 
2300 /**
2301  * @brief Print the name of the device followed by a colon and a space
2302  *
2303  * @returns the number of characters printed
2304  */
2305 int
2306 device_print_prettyname(device_t dev)
2307 {
2308 	const char *name = device_get_name(dev);
2309 
2310 	if (name == NULL)
2311 		return (printf("unknown: "));
2312 	return (printf("%s%d: ", name, device_get_unit(dev)));
2313 }
2314 
2315 /**
2316  * @brief Print the name of the device followed by a colon, a space
2317  * and the result of calling vprintf() with the value of @p fmt and
2318  * the following arguments.
2319  *
2320  * @returns the number of characters printed
2321  */
2322 int
2323 device_printf(device_t dev, const char * fmt, ...)
2324 {
2325 	va_list ap;
2326 	int retval;
2327 
2328 	retval = device_print_prettyname(dev);
2329 	va_start(ap, fmt);
2330 	retval += vprintf(fmt, ap);
2331 	va_end(ap);
2332 	return (retval);
2333 }
2334 
2335 /**
2336  * @internal
2337  */
2338 static void
2339 device_set_desc_internal(device_t dev, const char* desc, int copy)
2340 {
2341 	if (dev->desc && (dev->flags & DF_DESCMALLOCED)) {
2342 		free(dev->desc, M_BUS);
2343 		dev->flags &= ~DF_DESCMALLOCED;
2344 		dev->desc = NULL;
2345 	}
2346 
2347 	if (copy && desc) {
2348 		dev->desc = malloc(strlen(desc) + 1, M_BUS, M_NOWAIT);
2349 		if (dev->desc) {
2350 			strcpy(dev->desc, desc);
2351 			dev->flags |= DF_DESCMALLOCED;
2352 		}
2353 	} else {
2354 		/* Avoid a -Wcast-qual warning */
2355 		dev->desc = (char *)(uintptr_t) desc;
2356 	}
2357 
2358 	bus_data_generation_update();
2359 }
2360 
2361 /**
2362  * @brief Set the device's description
2363  *
2364  * The value of @c desc should be a string constant that will not
2365  * change (at least until the description is changed in a subsequent
2366  * call to device_set_desc() or device_set_desc_copy()).
2367  */
2368 void
2369 device_set_desc(device_t dev, const char* desc)
2370 {
2371 	device_set_desc_internal(dev, desc, FALSE);
2372 }
2373 
2374 /**
2375  * @brief Set the device's description
2376  *
2377  * The string pointed to by @c desc is copied. Use this function if
2378  * the device description is generated, (e.g. with sprintf()).
2379  */
2380 void
2381 device_set_desc_copy(device_t dev, const char* desc)
2382 {
2383 	device_set_desc_internal(dev, desc, TRUE);
2384 }
2385 
2386 /**
2387  * @brief Set the device's flags
2388  */
2389 void
2390 device_set_flags(device_t dev, uint32_t flags)
2391 {
2392 	dev->devflags = flags;
2393 }
2394 
2395 /**
2396  * @brief Return the device's softc field
2397  *
2398  * The softc is allocated and zeroed when a driver is attached, based
2399  * on the size field of the driver.
2400  */
2401 void *
2402 device_get_softc(device_t dev)
2403 {
2404 	return (dev->softc);
2405 }
2406 
2407 /**
2408  * @brief Set the device's softc field
2409  *
2410  * Most drivers do not need to use this since the softc is allocated
2411  * automatically when the driver is attached.
2412  */
2413 void
2414 device_set_softc(device_t dev, void *softc)
2415 {
2416 	if (dev->softc && !(dev->flags & DF_EXTERNALSOFTC))
2417 		free(dev->softc, M_BUS_SC);
2418 	dev->softc = softc;
2419 	if (dev->softc)
2420 		dev->flags |= DF_EXTERNALSOFTC;
2421 	else
2422 		dev->flags &= ~DF_EXTERNALSOFTC;
2423 }
2424 
2425 /**
2426  * @brief Free claimed softc
2427  *
2428  * Most drivers do not need to use this since the softc is freed
2429  * automatically when the driver is detached.
2430  */
2431 void
2432 device_free_softc(void *softc)
2433 {
2434 	free(softc, M_BUS_SC);
2435 }
2436 
2437 /**
2438  * @brief Claim softc
2439  *
2440  * This function can be used to let the driver free the automatically
2441  * allocated softc using "device_free_softc()". This function is
2442  * useful when the driver is refcounting the softc and the softc
2443  * cannot be freed when the "device_detach" method is called.
2444  */
2445 void
2446 device_claim_softc(device_t dev)
2447 {
2448 	if (dev->softc)
2449 		dev->flags |= DF_EXTERNALSOFTC;
2450 	else
2451 		dev->flags &= ~DF_EXTERNALSOFTC;
2452 }
2453 
2454 /**
2455  * @brief Get the device's ivars field
2456  *
2457  * The ivars field is used by the parent device to store per-device
2458  * state (e.g. the physical location of the device or a list of
2459  * resources).
2460  */
2461 void *
2462 device_get_ivars(device_t dev)
2463 {
2464 
2465 	KASSERT(dev != NULL, ("device_get_ivars(NULL, ...)"));
2466 	return (dev->ivars);
2467 }
2468 
2469 /**
2470  * @brief Set the device's ivars field
2471  */
2472 void
2473 device_set_ivars(device_t dev, void * ivars)
2474 {
2475 
2476 	KASSERT(dev != NULL, ("device_set_ivars(NULL, ...)"));
2477 	dev->ivars = ivars;
2478 }
2479 
2480 /**
2481  * @brief Return the device's state
2482  */
2483 device_state_t
2484 device_get_state(device_t dev)
2485 {
2486 	return (dev->state);
2487 }
2488 
2489 /**
2490  * @brief Set the DF_ENABLED flag for the device
2491  */
2492 void
2493 device_enable(device_t dev)
2494 {
2495 	dev->flags |= DF_ENABLED;
2496 }
2497 
2498 /**
2499  * @brief Clear the DF_ENABLED flag for the device
2500  */
2501 void
2502 device_disable(device_t dev)
2503 {
2504 	dev->flags &= ~DF_ENABLED;
2505 }
2506 
2507 /**
2508  * @brief Increment the busy counter for the device
2509  */
2510 void
2511 device_busy(device_t dev)
2512 {
2513 	if (dev->state < DS_ATTACHING)
2514 		panic("device_busy: called for unattached device");
2515 	if (dev->busy == 0 && dev->parent)
2516 		device_busy(dev->parent);
2517 	dev->busy++;
2518 	if (dev->state == DS_ATTACHED)
2519 		dev->state = DS_BUSY;
2520 }
2521 
2522 /**
2523  * @brief Decrement the busy counter for the device
2524  */
2525 void
2526 device_unbusy(device_t dev)
2527 {
2528 	if (dev->busy != 0 && dev->state != DS_BUSY &&
2529 	    dev->state != DS_ATTACHING)
2530 		panic("device_unbusy: called for non-busy device %s",
2531 		    device_get_nameunit(dev));
2532 	dev->busy--;
2533 	if (dev->busy == 0) {
2534 		if (dev->parent)
2535 			device_unbusy(dev->parent);
2536 		if (dev->state == DS_BUSY)
2537 			dev->state = DS_ATTACHED;
2538 	}
2539 }
2540 
2541 /**
2542  * @brief Set the DF_QUIET flag for the device
2543  */
2544 void
2545 device_quiet(device_t dev)
2546 {
2547 	dev->flags |= DF_QUIET;
2548 }
2549 
2550 /**
2551  * @brief Clear the DF_QUIET flag for the device
2552  */
2553 void
2554 device_verbose(device_t dev)
2555 {
2556 	dev->flags &= ~DF_QUIET;
2557 }
2558 
2559 /**
2560  * @brief Return non-zero if the DF_QUIET flag is set on the device
2561  */
2562 int
2563 device_is_quiet(device_t dev)
2564 {
2565 	return ((dev->flags & DF_QUIET) != 0);
2566 }
2567 
2568 /**
2569  * @brief Return non-zero if the DF_ENABLED flag is set on the device
2570  */
2571 int
2572 device_is_enabled(device_t dev)
2573 {
2574 	return ((dev->flags & DF_ENABLED) != 0);
2575 }
2576 
2577 /**
2578  * @brief Return non-zero if the device was successfully probed
2579  */
2580 int
2581 device_is_alive(device_t dev)
2582 {
2583 	return (dev->state >= DS_ALIVE);
2584 }
2585 
2586 /**
2587  * @brief Return non-zero if the device currently has a driver
2588  * attached to it
2589  */
2590 int
2591 device_is_attached(device_t dev)
2592 {
2593 	return (dev->state >= DS_ATTACHED);
2594 }
2595 
2596 /**
2597  * @brief Set the devclass of a device
2598  * @see devclass_add_device().
2599  */
2600 int
2601 device_set_devclass(device_t dev, const char *classname)
2602 {
2603 	devclass_t dc;
2604 	int error;
2605 
2606 	if (!classname) {
2607 		if (dev->devclass)
2608 			devclass_delete_device(dev->devclass, dev);
2609 		return (0);
2610 	}
2611 
2612 	if (dev->devclass) {
2613 		printf("device_set_devclass: device class already set\n");
2614 		return (EINVAL);
2615 	}
2616 
2617 	dc = devclass_find_internal(classname, NULL, TRUE);
2618 	if (!dc)
2619 		return (ENOMEM);
2620 
2621 	error = devclass_add_device(dc, dev);
2622 
2623 	bus_data_generation_update();
2624 	return (error);
2625 }
2626 
2627 /**
2628  * @brief Set the driver of a device
2629  *
2630  * @retval 0		success
2631  * @retval EBUSY	the device already has a driver attached
2632  * @retval ENOMEM	a memory allocation failure occurred
2633  */
2634 int
2635 device_set_driver(device_t dev, driver_t *driver)
2636 {
2637 	if (dev->state >= DS_ATTACHED)
2638 		return (EBUSY);
2639 
2640 	if (dev->driver == driver)
2641 		return (0);
2642 
2643 	if (dev->softc && !(dev->flags & DF_EXTERNALSOFTC)) {
2644 		free(dev->softc, M_BUS_SC);
2645 		dev->softc = NULL;
2646 	}
2647 	device_set_desc(dev, NULL);
2648 	kobj_delete((kobj_t) dev, NULL);
2649 	dev->driver = driver;
2650 	if (driver) {
2651 		kobj_init((kobj_t) dev, (kobj_class_t) driver);
2652 		if (!(dev->flags & DF_EXTERNALSOFTC) && driver->size > 0) {
2653 			dev->softc = malloc(driver->size, M_BUS_SC,
2654 			    M_NOWAIT | M_ZERO);
2655 			if (!dev->softc) {
2656 				kobj_delete((kobj_t) dev, NULL);
2657 				kobj_init((kobj_t) dev, &null_class);
2658 				dev->driver = NULL;
2659 				return (ENOMEM);
2660 			}
2661 		}
2662 	} else {
2663 		kobj_init((kobj_t) dev, &null_class);
2664 	}
2665 
2666 	bus_data_generation_update();
2667 	return (0);
2668 }
2669 
2670 /**
2671  * @brief Probe a device, and return this status.
2672  *
2673  * This function is the core of the device autoconfiguration
2674  * system. Its purpose is to select a suitable driver for a device and
2675  * then call that driver to initialise the hardware appropriately. The
2676  * driver is selected by calling the DEVICE_PROBE() method of a set of
2677  * candidate drivers and then choosing the driver which returned the
2678  * best value. This driver is then attached to the device using
2679  * device_attach().
2680  *
2681  * The set of suitable drivers is taken from the list of drivers in
2682  * the parent device's devclass. If the device was originally created
2683  * with a specific class name (see device_add_child()), only drivers
2684  * with that name are probed, otherwise all drivers in the devclass
2685  * are probed. If no drivers return successful probe values in the
2686  * parent devclass, the search continues in the parent of that
2687  * devclass (see devclass_get_parent()) if any.
2688  *
2689  * @param dev		the device to initialise
2690  *
2691  * @retval 0		success
2692  * @retval ENXIO	no driver was found
2693  * @retval ENOMEM	memory allocation failure
2694  * @retval non-zero	some other unix error code
2695  * @retval -1		Device already attached
2696  */
2697 int
2698 device_probe(device_t dev)
2699 {
2700 	int error;
2701 
2702 	GIANT_REQUIRED;
2703 
2704 	if (dev->state >= DS_ALIVE && (dev->flags & DF_REBID) == 0)
2705 		return (-1);
2706 
2707 	if (!(dev->flags & DF_ENABLED)) {
2708 		if (bootverbose && device_get_name(dev) != NULL) {
2709 			device_print_prettyname(dev);
2710 			printf("not probed (disabled)\n");
2711 		}
2712 		return (-1);
2713 	}
2714 	if ((error = device_probe_child(dev->parent, dev)) != 0) {
2715 		if (bus_current_pass == BUS_PASS_DEFAULT &&
2716 		    !(dev->flags & DF_DONENOMATCH)) {
2717 			BUS_PROBE_NOMATCH(dev->parent, dev);
2718 			devnomatch(dev);
2719 			dev->flags |= DF_DONENOMATCH;
2720 		}
2721 		return (error);
2722 	}
2723 	return (0);
2724 }
2725 
2726 /**
2727  * @brief Probe a device and attach a driver if possible
2728  *
2729  * calls device_probe() and attaches if that was successful.
2730  */
2731 int
2732 device_probe_and_attach(device_t dev)
2733 {
2734 	int error;
2735 
2736 	GIANT_REQUIRED;
2737 
2738 	error = device_probe(dev);
2739 	if (error == -1)
2740 		return (0);
2741 	else if (error != 0)
2742 		return (error);
2743 
2744 	CURVNET_SET_QUIET(vnet0);
2745 	error = device_attach(dev);
2746 	CURVNET_RESTORE();
2747 	return error;
2748 }
2749 
2750 /**
2751  * @brief Attach a device driver to a device
2752  *
2753  * This function is a wrapper around the DEVICE_ATTACH() driver
2754  * method. In addition to calling DEVICE_ATTACH(), it initialises the
2755  * device's sysctl tree, optionally prints a description of the device
2756  * and queues a notification event for user-based device management
2757  * services.
2758  *
2759  * Normally this function is only called internally from
2760  * device_probe_and_attach().
2761  *
2762  * @param dev		the device to initialise
2763  *
2764  * @retval 0		success
2765  * @retval ENXIO	no driver was found
2766  * @retval ENOMEM	memory allocation failure
2767  * @retval non-zero	some other unix error code
2768  */
2769 int
2770 device_attach(device_t dev)
2771 {
2772 	uint64_t attachtime;
2773 	int error;
2774 
2775 	if (resource_disabled(dev->driver->name, dev->unit)) {
2776 		device_disable(dev);
2777 		if (bootverbose)
2778 			 device_printf(dev, "disabled via hints entry\n");
2779 		return (ENXIO);
2780 	}
2781 
2782 	device_sysctl_init(dev);
2783 	if (!device_is_quiet(dev))
2784 		device_print_child(dev->parent, dev);
2785 	attachtime = get_cyclecount();
2786 	dev->state = DS_ATTACHING;
2787 	if ((error = DEVICE_ATTACH(dev)) != 0) {
2788 		printf("device_attach: %s%d attach returned %d\n",
2789 		    dev->driver->name, dev->unit, error);
2790 		if (!(dev->flags & DF_FIXEDCLASS))
2791 			devclass_delete_device(dev->devclass, dev);
2792 		(void)device_set_driver(dev, NULL);
2793 		device_sysctl_fini(dev);
2794 		KASSERT(dev->busy == 0, ("attach failed but busy"));
2795 		dev->state = DS_NOTPRESENT;
2796 		return (error);
2797 	}
2798 	attachtime = get_cyclecount() - attachtime;
2799 	/*
2800 	 * 4 bits per device is a reasonable value for desktop and server
2801 	 * hardware with good get_cyclecount() implementations, but may
2802 	 * need to be adjusted on other platforms.
2803 	 */
2804 #ifdef RANDOM_DEBUG
2805 	printf("%s(): feeding %d bit(s) of entropy from %s%d\n",
2806 	    __func__, 4, dev->driver->name, dev->unit);
2807 #endif
2808 	random_harvest(&attachtime, sizeof(attachtime), 4, RANDOM_ATTACH);
2809 	device_sysctl_update(dev);
2810 	if (dev->busy)
2811 		dev->state = DS_BUSY;
2812 	else
2813 		dev->state = DS_ATTACHED;
2814 	dev->flags &= ~DF_DONENOMATCH;
2815 	devadded(dev);
2816 	return (0);
2817 }
2818 
2819 /**
2820  * @brief Detach a driver from a device
2821  *
2822  * This function is a wrapper around the DEVICE_DETACH() driver
2823  * method. If the call to DEVICE_DETACH() succeeds, it calls
2824  * BUS_CHILD_DETACHED() for the parent of @p dev, queues a
2825  * notification event for user-based device management services and
2826  * cleans up the device's sysctl tree.
2827  *
2828  * @param dev		the device to un-initialise
2829  *
2830  * @retval 0		success
2831  * @retval ENXIO	no driver was found
2832  * @retval ENOMEM	memory allocation failure
2833  * @retval non-zero	some other unix error code
2834  */
2835 int
2836 device_detach(device_t dev)
2837 {
2838 	int error;
2839 
2840 	GIANT_REQUIRED;
2841 
2842 	PDEBUG(("%s", DEVICENAME(dev)));
2843 	if (dev->state == DS_BUSY)
2844 		return (EBUSY);
2845 	if (dev->state != DS_ATTACHED)
2846 		return (0);
2847 
2848 	if ((error = DEVICE_DETACH(dev)) != 0)
2849 		return (error);
2850 	devremoved(dev);
2851 	if (!device_is_quiet(dev))
2852 		device_printf(dev, "detached\n");
2853 	if (dev->parent)
2854 		BUS_CHILD_DETACHED(dev->parent, dev);
2855 
2856 	if (!(dev->flags & DF_FIXEDCLASS))
2857 		devclass_delete_device(dev->devclass, dev);
2858 
2859 	dev->state = DS_NOTPRESENT;
2860 	(void)device_set_driver(dev, NULL);
2861 	device_sysctl_fini(dev);
2862 
2863 	return (0);
2864 }
2865 
2866 /**
2867  * @brief Tells a driver to quiesce itself.
2868  *
2869  * This function is a wrapper around the DEVICE_QUIESCE() driver
2870  * method. If the call to DEVICE_QUIESCE() succeeds.
2871  *
2872  * @param dev		the device to quiesce
2873  *
2874  * @retval 0		success
2875  * @retval ENXIO	no driver was found
2876  * @retval ENOMEM	memory allocation failure
2877  * @retval non-zero	some other unix error code
2878  */
2879 int
2880 device_quiesce(device_t dev)
2881 {
2882 
2883 	PDEBUG(("%s", DEVICENAME(dev)));
2884 	if (dev->state == DS_BUSY)
2885 		return (EBUSY);
2886 	if (dev->state != DS_ATTACHED)
2887 		return (0);
2888 
2889 	return (DEVICE_QUIESCE(dev));
2890 }
2891 
2892 /**
2893  * @brief Notify a device of system shutdown
2894  *
2895  * This function calls the DEVICE_SHUTDOWN() driver method if the
2896  * device currently has an attached driver.
2897  *
2898  * @returns the value returned by DEVICE_SHUTDOWN()
2899  */
2900 int
2901 device_shutdown(device_t dev)
2902 {
2903 	if (dev->state < DS_ATTACHED)
2904 		return (0);
2905 	return (DEVICE_SHUTDOWN(dev));
2906 }
2907 
2908 /**
2909  * @brief Set the unit number of a device
2910  *
2911  * This function can be used to override the unit number used for a
2912  * device (e.g. to wire a device to a pre-configured unit number).
2913  */
2914 int
2915 device_set_unit(device_t dev, int unit)
2916 {
2917 	devclass_t dc;
2918 	int err;
2919 
2920 	dc = device_get_devclass(dev);
2921 	if (unit < dc->maxunit && dc->devices[unit])
2922 		return (EBUSY);
2923 	err = devclass_delete_device(dc, dev);
2924 	if (err)
2925 		return (err);
2926 	dev->unit = unit;
2927 	err = devclass_add_device(dc, dev);
2928 	if (err)
2929 		return (err);
2930 
2931 	bus_data_generation_update();
2932 	return (0);
2933 }
2934 
2935 /*======================================*/
2936 /*
2937  * Some useful method implementations to make life easier for bus drivers.
2938  */
2939 
2940 /**
2941  * @brief Initialise a resource list.
2942  *
2943  * @param rl		the resource list to initialise
2944  */
2945 void
2946 resource_list_init(struct resource_list *rl)
2947 {
2948 	STAILQ_INIT(rl);
2949 }
2950 
2951 /**
2952  * @brief Reclaim memory used by a resource list.
2953  *
2954  * This function frees the memory for all resource entries on the list
2955  * (if any).
2956  *
2957  * @param rl		the resource list to free
2958  */
2959 void
2960 resource_list_free(struct resource_list *rl)
2961 {
2962 	struct resource_list_entry *rle;
2963 
2964 	while ((rle = STAILQ_FIRST(rl)) != NULL) {
2965 		if (rle->res)
2966 			panic("resource_list_free: resource entry is busy");
2967 		STAILQ_REMOVE_HEAD(rl, link);
2968 		free(rle, M_BUS);
2969 	}
2970 }
2971 
2972 /**
2973  * @brief Add a resource entry.
2974  *
2975  * This function adds a resource entry using the given @p type, @p
2976  * start, @p end and @p count values. A rid value is chosen by
2977  * searching sequentially for the first unused rid starting at zero.
2978  *
2979  * @param rl		the resource list to edit
2980  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2981  * @param start		the start address of the resource
2982  * @param end		the end address of the resource
2983  * @param count		XXX end-start+1
2984  */
2985 int
2986 resource_list_add_next(struct resource_list *rl, int type, u_long start,
2987     u_long end, u_long count)
2988 {
2989 	int rid;
2990 
2991 	rid = 0;
2992 	while (resource_list_find(rl, type, rid) != NULL)
2993 		rid++;
2994 	resource_list_add(rl, type, rid, start, end, count);
2995 	return (rid);
2996 }
2997 
2998 /**
2999  * @brief Add or modify a resource entry.
3000  *
3001  * If an existing entry exists with the same type and rid, it will be
3002  * modified using the given values of @p start, @p end and @p
3003  * count. If no entry exists, a new one will be created using the
3004  * given values.  The resource list entry that matches is then returned.
3005  *
3006  * @param rl		the resource list to edit
3007  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
3008  * @param rid		the resource identifier
3009  * @param start		the start address of the resource
3010  * @param end		the end address of the resource
3011  * @param count		XXX end-start+1
3012  */
3013 struct resource_list_entry *
3014 resource_list_add(struct resource_list *rl, int type, int rid,
3015     u_long start, u_long end, u_long count)
3016 {
3017 	struct resource_list_entry *rle;
3018 
3019 	rle = resource_list_find(rl, type, rid);
3020 	if (!rle) {
3021 		rle = malloc(sizeof(struct resource_list_entry), M_BUS,
3022 		    M_NOWAIT);
3023 		if (!rle)
3024 			panic("resource_list_add: can't record entry");
3025 		STAILQ_INSERT_TAIL(rl, rle, link);
3026 		rle->type = type;
3027 		rle->rid = rid;
3028 		rle->res = NULL;
3029 		rle->flags = 0;
3030 	}
3031 
3032 	if (rle->res)
3033 		panic("resource_list_add: resource entry is busy");
3034 
3035 	rle->start = start;
3036 	rle->end = end;
3037 	rle->count = count;
3038 	return (rle);
3039 }
3040 
3041 /**
3042  * @brief Determine if a resource entry is busy.
3043  *
3044  * Returns true if a resource entry is busy meaning that it has an
3045  * associated resource that is not an unallocated "reserved" resource.
3046  *
3047  * @param rl		the resource list to search
3048  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
3049  * @param rid		the resource identifier
3050  *
3051  * @returns Non-zero if the entry is busy, zero otherwise.
3052  */
3053 int
3054 resource_list_busy(struct resource_list *rl, int type, int rid)
3055 {
3056 	struct resource_list_entry *rle;
3057 
3058 	rle = resource_list_find(rl, type, rid);
3059 	if (rle == NULL || rle->res == NULL)
3060 		return (0);
3061 	if ((rle->flags & (RLE_RESERVED | RLE_ALLOCATED)) == RLE_RESERVED) {
3062 		KASSERT(!(rman_get_flags(rle->res) & RF_ACTIVE),
3063 		    ("reserved resource is active"));
3064 		return (0);
3065 	}
3066 	return (1);
3067 }
3068 
3069 /**
3070  * @brief Determine if a resource entry is reserved.
3071  *
3072  * Returns true if a resource entry is reserved meaning that it has an
3073  * associated "reserved" resource.  The resource can either be
3074  * allocated or unallocated.
3075  *
3076  * @param rl		the resource list to search
3077  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
3078  * @param rid		the resource identifier
3079  *
3080  * @returns Non-zero if the entry is reserved, zero otherwise.
3081  */
3082 int
3083 resource_list_reserved(struct resource_list *rl, int type, int rid)
3084 {
3085 	struct resource_list_entry *rle;
3086 
3087 	rle = resource_list_find(rl, type, rid);
3088 	if (rle != NULL && rle->flags & RLE_RESERVED)
3089 		return (1);
3090 	return (0);
3091 }
3092 
3093 /**
3094  * @brief Find a resource entry by type and rid.
3095  *
3096  * @param rl		the resource list to search
3097  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
3098  * @param rid		the resource identifier
3099  *
3100  * @returns the resource entry pointer or NULL if there is no such
3101  * entry.
3102  */
3103 struct resource_list_entry *
3104 resource_list_find(struct resource_list *rl, int type, int rid)
3105 {
3106 	struct resource_list_entry *rle;
3107 
3108 	STAILQ_FOREACH(rle, rl, link) {
3109 		if (rle->type == type && rle->rid == rid)
3110 			return (rle);
3111 	}
3112 	return (NULL);
3113 }
3114 
3115 /**
3116  * @brief Delete a resource entry.
3117  *
3118  * @param rl		the resource list to edit
3119  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
3120  * @param rid		the resource identifier
3121  */
3122 void
3123 resource_list_delete(struct resource_list *rl, int type, int rid)
3124 {
3125 	struct resource_list_entry *rle = resource_list_find(rl, type, rid);
3126 
3127 	if (rle) {
3128 		if (rle->res != NULL)
3129 			panic("resource_list_delete: resource has not been released");
3130 		STAILQ_REMOVE(rl, rle, resource_list_entry, link);
3131 		free(rle, M_BUS);
3132 	}
3133 }
3134 
3135 /**
3136  * @brief Allocate a reserved resource
3137  *
3138  * This can be used by busses to force the allocation of resources
3139  * that are always active in the system even if they are not allocated
3140  * by a driver (e.g. PCI BARs).  This function is usually called when
3141  * adding a new child to the bus.  The resource is allocated from the
3142  * parent bus when it is reserved.  The resource list entry is marked
3143  * with RLE_RESERVED to note that it is a reserved resource.
3144  *
3145  * Subsequent attempts to allocate the resource with
3146  * resource_list_alloc() will succeed the first time and will set
3147  * RLE_ALLOCATED to note that it has been allocated.  When a reserved
3148  * resource that has been allocated is released with
3149  * resource_list_release() the resource RLE_ALLOCATED is cleared, but
3150  * the actual resource remains allocated.  The resource can be released to
3151  * the parent bus by calling resource_list_unreserve().
3152  *
3153  * @param rl		the resource list to allocate from
3154  * @param bus		the parent device of @p child
3155  * @param child		the device for which the resource is being reserved
3156  * @param type		the type of resource to allocate
3157  * @param rid		a pointer to the resource identifier
3158  * @param start		hint at the start of the resource range - pass
3159  *			@c 0UL for any start address
3160  * @param end		hint at the end of the resource range - pass
3161  *			@c ~0UL for any end address
3162  * @param count		hint at the size of range required - pass @c 1
3163  *			for any size
3164  * @param flags		any extra flags to control the resource
3165  *			allocation - see @c RF_XXX flags in
3166  *			<sys/rman.h> for details
3167  *
3168  * @returns		the resource which was allocated or @c NULL if no
3169  *			resource could be allocated
3170  */
3171 struct resource *
3172 resource_list_reserve(struct resource_list *rl, device_t bus, device_t child,
3173     int type, int *rid, u_long start, u_long end, u_long count, u_int flags)
3174 {
3175 	struct resource_list_entry *rle = NULL;
3176 	int passthrough = (device_get_parent(child) != bus);
3177 	struct resource *r;
3178 
3179 	if (passthrough)
3180 		panic(
3181     "resource_list_reserve() should only be called for direct children");
3182 	if (flags & RF_ACTIVE)
3183 		panic(
3184     "resource_list_reserve() should only reserve inactive resources");
3185 
3186 	r = resource_list_alloc(rl, bus, child, type, rid, start, end, count,
3187 	    flags);
3188 	if (r != NULL) {
3189 		rle = resource_list_find(rl, type, *rid);
3190 		rle->flags |= RLE_RESERVED;
3191 	}
3192 	return (r);
3193 }
3194 
3195 /**
3196  * @brief Helper function for implementing BUS_ALLOC_RESOURCE()
3197  *
3198  * Implement BUS_ALLOC_RESOURCE() by looking up a resource from the list
3199  * and passing the allocation up to the parent of @p bus. This assumes
3200  * that the first entry of @c device_get_ivars(child) is a struct
3201  * resource_list. This also handles 'passthrough' allocations where a
3202  * child is a remote descendant of bus by passing the allocation up to
3203  * the parent of bus.
3204  *
3205  * Typically, a bus driver would store a list of child resources
3206  * somewhere in the child device's ivars (see device_get_ivars()) and
3207  * its implementation of BUS_ALLOC_RESOURCE() would find that list and
3208  * then call resource_list_alloc() to perform the allocation.
3209  *
3210  * @param rl		the resource list to allocate from
3211  * @param bus		the parent device of @p child
3212  * @param child		the device which is requesting an allocation
3213  * @param type		the type of resource to allocate
3214  * @param rid		a pointer to the resource identifier
3215  * @param start		hint at the start of the resource range - pass
3216  *			@c 0UL for any start address
3217  * @param end		hint at the end of the resource range - pass
3218  *			@c ~0UL for any end address
3219  * @param count		hint at the size of range required - pass @c 1
3220  *			for any size
3221  * @param flags		any extra flags to control the resource
3222  *			allocation - see @c RF_XXX flags in
3223  *			<sys/rman.h> for details
3224  *
3225  * @returns		the resource which was allocated or @c NULL if no
3226  *			resource could be allocated
3227  */
3228 struct resource *
3229 resource_list_alloc(struct resource_list *rl, device_t bus, device_t child,
3230     int type, int *rid, u_long start, u_long end, u_long count, u_int flags)
3231 {
3232 	struct resource_list_entry *rle = NULL;
3233 	int passthrough = (device_get_parent(child) != bus);
3234 	int isdefault = (start == 0UL && end == ~0UL);
3235 
3236 	if (passthrough) {
3237 		return (BUS_ALLOC_RESOURCE(device_get_parent(bus), child,
3238 		    type, rid, start, end, count, flags));
3239 	}
3240 
3241 	rle = resource_list_find(rl, type, *rid);
3242 
3243 	if (!rle)
3244 		return (NULL);		/* no resource of that type/rid */
3245 
3246 	if (rle->res) {
3247 		if (rle->flags & RLE_RESERVED) {
3248 			if (rle->flags & RLE_ALLOCATED)
3249 				return (NULL);
3250 			if ((flags & RF_ACTIVE) &&
3251 			    bus_activate_resource(child, type, *rid,
3252 			    rle->res) != 0)
3253 				return (NULL);
3254 			rle->flags |= RLE_ALLOCATED;
3255 			return (rle->res);
3256 		}
3257 		panic("resource_list_alloc: resource entry is busy");
3258 	}
3259 
3260 	if (isdefault) {
3261 		start = rle->start;
3262 		count = ulmax(count, rle->count);
3263 		end = ulmax(rle->end, start + count - 1);
3264 	}
3265 
3266 	rle->res = BUS_ALLOC_RESOURCE(device_get_parent(bus), child,
3267 	    type, rid, start, end, count, flags);
3268 
3269 	/*
3270 	 * Record the new range.
3271 	 */
3272 	if (rle->res) {
3273 		rle->start = rman_get_start(rle->res);
3274 		rle->end = rman_get_end(rle->res);
3275 		rle->count = count;
3276 	}
3277 
3278 	return (rle->res);
3279 }
3280 
3281 /**
3282  * @brief Helper function for implementing BUS_RELEASE_RESOURCE()
3283  *
3284  * Implement BUS_RELEASE_RESOURCE() using a resource list. Normally
3285  * used with resource_list_alloc().
3286  *
3287  * @param rl		the resource list which was allocated from
3288  * @param bus		the parent device of @p child
3289  * @param child		the device which is requesting a release
3290  * @param type		the type of resource to release
3291  * @param rid		the resource identifier
3292  * @param res		the resource to release
3293  *
3294  * @retval 0		success
3295  * @retval non-zero	a standard unix error code indicating what
3296  *			error condition prevented the operation
3297  */
3298 int
3299 resource_list_release(struct resource_list *rl, device_t bus, device_t child,
3300     int type, int rid, struct resource *res)
3301 {
3302 	struct resource_list_entry *rle = NULL;
3303 	int passthrough = (device_get_parent(child) != bus);
3304 	int error;
3305 
3306 	if (passthrough) {
3307 		return (BUS_RELEASE_RESOURCE(device_get_parent(bus), child,
3308 		    type, rid, res));
3309 	}
3310 
3311 	rle = resource_list_find(rl, type, rid);
3312 
3313 	if (!rle)
3314 		panic("resource_list_release: can't find resource");
3315 	if (!rle->res)
3316 		panic("resource_list_release: resource entry is not busy");
3317 	if (rle->flags & RLE_RESERVED) {
3318 		if (rle->flags & RLE_ALLOCATED) {
3319 			if (rman_get_flags(res) & RF_ACTIVE) {
3320 				error = bus_deactivate_resource(child, type,
3321 				    rid, res);
3322 				if (error)
3323 					return (error);
3324 			}
3325 			rle->flags &= ~RLE_ALLOCATED;
3326 			return (0);
3327 		}
3328 		return (EINVAL);
3329 	}
3330 
3331 	error = BUS_RELEASE_RESOURCE(device_get_parent(bus), child,
3332 	    type, rid, res);
3333 	if (error)
3334 		return (error);
3335 
3336 	rle->res = NULL;
3337 	return (0);
3338 }
3339 
3340 /**
3341  * @brief Release all active resources of a given type
3342  *
3343  * Release all active resources of a specified type.  This is intended
3344  * to be used to cleanup resources leaked by a driver after detach or
3345  * a failed attach.
3346  *
3347  * @param rl		the resource list which was allocated from
3348  * @param bus		the parent device of @p child
3349  * @param child		the device whose active resources are being released
3350  * @param type		the type of resources to release
3351  *
3352  * @retval 0		success
3353  * @retval EBUSY	at least one resource was active
3354  */
3355 int
3356 resource_list_release_active(struct resource_list *rl, device_t bus,
3357     device_t child, int type)
3358 {
3359 	struct resource_list_entry *rle;
3360 	int error, retval;
3361 
3362 	retval = 0;
3363 	STAILQ_FOREACH(rle, rl, link) {
3364 		if (rle->type != type)
3365 			continue;
3366 		if (rle->res == NULL)
3367 			continue;
3368 		if ((rle->flags & (RLE_RESERVED | RLE_ALLOCATED)) ==
3369 		    RLE_RESERVED)
3370 			continue;
3371 		retval = EBUSY;
3372 		error = resource_list_release(rl, bus, child, type,
3373 		    rman_get_rid(rle->res), rle->res);
3374 		if (error != 0)
3375 			device_printf(bus,
3376 			    "Failed to release active resource: %d\n", error);
3377 	}
3378 	return (retval);
3379 }
3380 
3381 
3382 /**
3383  * @brief Fully release a reserved resource
3384  *
3385  * Fully releases a resource reserved via resource_list_reserve().
3386  *
3387  * @param rl		the resource list which was allocated from
3388  * @param bus		the parent device of @p child
3389  * @param child		the device whose reserved resource is being released
3390  * @param type		the type of resource to release
3391  * @param rid		the resource identifier
3392  * @param res		the resource to release
3393  *
3394  * @retval 0		success
3395  * @retval non-zero	a standard unix error code indicating what
3396  *			error condition prevented the operation
3397  */
3398 int
3399 resource_list_unreserve(struct resource_list *rl, device_t bus, device_t child,
3400     int type, int rid)
3401 {
3402 	struct resource_list_entry *rle = NULL;
3403 	int passthrough = (device_get_parent(child) != bus);
3404 
3405 	if (passthrough)
3406 		panic(
3407     "resource_list_unreserve() should only be called for direct children");
3408 
3409 	rle = resource_list_find(rl, type, rid);
3410 
3411 	if (!rle)
3412 		panic("resource_list_unreserve: can't find resource");
3413 	if (!(rle->flags & RLE_RESERVED))
3414 		return (EINVAL);
3415 	if (rle->flags & RLE_ALLOCATED)
3416 		return (EBUSY);
3417 	rle->flags &= ~RLE_RESERVED;
3418 	return (resource_list_release(rl, bus, child, type, rid, rle->res));
3419 }
3420 
3421 /**
3422  * @brief Print a description of resources in a resource list
3423  *
3424  * Print all resources of a specified type, for use in BUS_PRINT_CHILD().
3425  * The name is printed if at least one resource of the given type is available.
3426  * The format is used to print resource start and end.
3427  *
3428  * @param rl		the resource list to print
3429  * @param name		the name of @p type, e.g. @c "memory"
3430  * @param type		type type of resource entry to print
3431  * @param format	printf(9) format string to print resource
3432  *			start and end values
3433  *
3434  * @returns		the number of characters printed
3435  */
3436 int
3437 resource_list_print_type(struct resource_list *rl, const char *name, int type,
3438     const char *format)
3439 {
3440 	struct resource_list_entry *rle;
3441 	int printed, retval;
3442 
3443 	printed = 0;
3444 	retval = 0;
3445 	/* Yes, this is kinda cheating */
3446 	STAILQ_FOREACH(rle, rl, link) {
3447 		if (rle->type == type) {
3448 			if (printed == 0)
3449 				retval += printf(" %s ", name);
3450 			else
3451 				retval += printf(",");
3452 			printed++;
3453 			retval += printf(format, rle->start);
3454 			if (rle->count > 1) {
3455 				retval += printf("-");
3456 				retval += printf(format, rle->start +
3457 						 rle->count - 1);
3458 			}
3459 		}
3460 	}
3461 	return (retval);
3462 }
3463 
3464 /**
3465  * @brief Releases all the resources in a list.
3466  *
3467  * @param rl		The resource list to purge.
3468  *
3469  * @returns		nothing
3470  */
3471 void
3472 resource_list_purge(struct resource_list *rl)
3473 {
3474 	struct resource_list_entry *rle;
3475 
3476 	while ((rle = STAILQ_FIRST(rl)) != NULL) {
3477 		if (rle->res)
3478 			bus_release_resource(rman_get_device(rle->res),
3479 			    rle->type, rle->rid, rle->res);
3480 		STAILQ_REMOVE_HEAD(rl, link);
3481 		free(rle, M_BUS);
3482 	}
3483 }
3484 
3485 device_t
3486 bus_generic_add_child(device_t dev, u_int order, const char *name, int unit)
3487 {
3488 
3489 	return (device_add_child_ordered(dev, order, name, unit));
3490 }
3491 
3492 /**
3493  * @brief Helper function for implementing DEVICE_PROBE()
3494  *
3495  * This function can be used to help implement the DEVICE_PROBE() for
3496  * a bus (i.e. a device which has other devices attached to it). It
3497  * calls the DEVICE_IDENTIFY() method of each driver in the device's
3498  * devclass.
3499  */
3500 int
3501 bus_generic_probe(device_t dev)
3502 {
3503 	devclass_t dc = dev->devclass;
3504 	driverlink_t dl;
3505 
3506 	TAILQ_FOREACH(dl, &dc->drivers, link) {
3507 		/*
3508 		 * If this driver's pass is too high, then ignore it.
3509 		 * For most drivers in the default pass, this will
3510 		 * never be true.  For early-pass drivers they will
3511 		 * only call the identify routines of eligible drivers
3512 		 * when this routine is called.  Drivers for later
3513 		 * passes should have their identify routines called
3514 		 * on early-pass busses during BUS_NEW_PASS().
3515 		 */
3516 		if (dl->pass > bus_current_pass)
3517 			continue;
3518 		DEVICE_IDENTIFY(dl->driver, dev);
3519 	}
3520 
3521 	return (0);
3522 }
3523 
3524 /**
3525  * @brief Helper function for implementing DEVICE_ATTACH()
3526  *
3527  * This function can be used to help implement the DEVICE_ATTACH() for
3528  * a bus. It calls device_probe_and_attach() for each of the device's
3529  * children.
3530  */
3531 int
3532 bus_generic_attach(device_t dev)
3533 {
3534 	device_t child;
3535 
3536 	TAILQ_FOREACH(child, &dev->children, link) {
3537 		device_probe_and_attach(child);
3538 	}
3539 
3540 	return (0);
3541 }
3542 
3543 /**
3544  * @brief Helper function for implementing DEVICE_DETACH()
3545  *
3546  * This function can be used to help implement the DEVICE_DETACH() for
3547  * a bus. It calls device_detach() for each of the device's
3548  * children.
3549  */
3550 int
3551 bus_generic_detach(device_t dev)
3552 {
3553 	device_t child;
3554 	int error;
3555 
3556 	if (dev->state != DS_ATTACHED)
3557 		return (EBUSY);
3558 
3559 	TAILQ_FOREACH(child, &dev->children, link) {
3560 		if ((error = device_detach(child)) != 0)
3561 			return (error);
3562 	}
3563 
3564 	return (0);
3565 }
3566 
3567 /**
3568  * @brief Helper function for implementing DEVICE_SHUTDOWN()
3569  *
3570  * This function can be used to help implement the DEVICE_SHUTDOWN()
3571  * for a bus. It calls device_shutdown() for each of the device's
3572  * children.
3573  */
3574 int
3575 bus_generic_shutdown(device_t dev)
3576 {
3577 	device_t child;
3578 
3579 	TAILQ_FOREACH(child, &dev->children, link) {
3580 		device_shutdown(child);
3581 	}
3582 
3583 	return (0);
3584 }
3585 
3586 /**
3587  * @brief Helper function for implementing DEVICE_SUSPEND()
3588  *
3589  * This function can be used to help implement the DEVICE_SUSPEND()
3590  * for a bus. It calls DEVICE_SUSPEND() for each of the device's
3591  * children. If any call to DEVICE_SUSPEND() fails, the suspend
3592  * operation is aborted and any devices which were suspended are
3593  * resumed immediately by calling their DEVICE_RESUME() methods.
3594  */
3595 int
3596 bus_generic_suspend(device_t dev)
3597 {
3598 	int		error;
3599 	device_t	child, child2;
3600 
3601 	TAILQ_FOREACH(child, &dev->children, link) {
3602 		error = DEVICE_SUSPEND(child);
3603 		if (error) {
3604 			for (child2 = TAILQ_FIRST(&dev->children);
3605 			     child2 && child2 != child;
3606 			     child2 = TAILQ_NEXT(child2, link))
3607 				DEVICE_RESUME(child2);
3608 			return (error);
3609 		}
3610 	}
3611 	return (0);
3612 }
3613 
3614 /**
3615  * @brief Helper function for implementing DEVICE_RESUME()
3616  *
3617  * This function can be used to help implement the DEVICE_RESUME() for
3618  * a bus. It calls DEVICE_RESUME() on each of the device's children.
3619  */
3620 int
3621 bus_generic_resume(device_t dev)
3622 {
3623 	device_t	child;
3624 
3625 	TAILQ_FOREACH(child, &dev->children, link) {
3626 		DEVICE_RESUME(child);
3627 		/* if resume fails, there's nothing we can usefully do... */
3628 	}
3629 	return (0);
3630 }
3631 
3632 /**
3633  * @brief Helper function for implementing BUS_PRINT_CHILD().
3634  *
3635  * This function prints the first part of the ascii representation of
3636  * @p child, including its name, unit and description (if any - see
3637  * device_set_desc()).
3638  *
3639  * @returns the number of characters printed
3640  */
3641 int
3642 bus_print_child_header(device_t dev, device_t child)
3643 {
3644 	int	retval = 0;
3645 
3646 	if (device_get_desc(child)) {
3647 		retval += device_printf(child, "<%s>", device_get_desc(child));
3648 	} else {
3649 		retval += printf("%s", device_get_nameunit(child));
3650 	}
3651 
3652 	return (retval);
3653 }
3654 
3655 /**
3656  * @brief Helper function for implementing BUS_PRINT_CHILD().
3657  *
3658  * This function prints the last part of the ascii representation of
3659  * @p child, which consists of the string @c " on " followed by the
3660  * name and unit of the @p dev.
3661  *
3662  * @returns the number of characters printed
3663  */
3664 int
3665 bus_print_child_footer(device_t dev, device_t child)
3666 {
3667 	return (printf(" on %s\n", device_get_nameunit(dev)));
3668 }
3669 
3670 /**
3671  * @brief Helper function for implementing BUS_PRINT_CHILD().
3672  *
3673  * This function simply calls bus_print_child_header() followed by
3674  * bus_print_child_footer().
3675  *
3676  * @returns the number of characters printed
3677  */
3678 int
3679 bus_generic_print_child(device_t dev, device_t child)
3680 {
3681 	int	retval = 0;
3682 
3683 	retval += bus_print_child_header(dev, child);
3684 	retval += bus_print_child_footer(dev, child);
3685 
3686 	return (retval);
3687 }
3688 
3689 /**
3690  * @brief Stub function for implementing BUS_READ_IVAR().
3691  *
3692  * @returns ENOENT
3693  */
3694 int
3695 bus_generic_read_ivar(device_t dev, device_t child, int index,
3696     uintptr_t * result)
3697 {
3698 	return (ENOENT);
3699 }
3700 
3701 /**
3702  * @brief Stub function for implementing BUS_WRITE_IVAR().
3703  *
3704  * @returns ENOENT
3705  */
3706 int
3707 bus_generic_write_ivar(device_t dev, device_t child, int index,
3708     uintptr_t value)
3709 {
3710 	return (ENOENT);
3711 }
3712 
3713 /**
3714  * @brief Stub function for implementing BUS_GET_RESOURCE_LIST().
3715  *
3716  * @returns NULL
3717  */
3718 struct resource_list *
3719 bus_generic_get_resource_list(device_t dev, device_t child)
3720 {
3721 	return (NULL);
3722 }
3723 
3724 /**
3725  * @brief Helper function for implementing BUS_DRIVER_ADDED().
3726  *
3727  * This implementation of BUS_DRIVER_ADDED() simply calls the driver's
3728  * DEVICE_IDENTIFY() method to allow it to add new children to the bus
3729  * and then calls device_probe_and_attach() for each unattached child.
3730  */
3731 void
3732 bus_generic_driver_added(device_t dev, driver_t *driver)
3733 {
3734 	device_t child;
3735 
3736 	DEVICE_IDENTIFY(driver, dev);
3737 	TAILQ_FOREACH(child, &dev->children, link) {
3738 		if (child->state == DS_NOTPRESENT ||
3739 		    (child->flags & DF_REBID))
3740 			device_probe_and_attach(child);
3741 	}
3742 }
3743 
3744 /**
3745  * @brief Helper function for implementing BUS_NEW_PASS().
3746  *
3747  * This implementing of BUS_NEW_PASS() first calls the identify
3748  * routines for any drivers that probe at the current pass.  Then it
3749  * walks the list of devices for this bus.  If a device is already
3750  * attached, then it calls BUS_NEW_PASS() on that device.  If the
3751  * device is not already attached, it attempts to attach a driver to
3752  * it.
3753  */
3754 void
3755 bus_generic_new_pass(device_t dev)
3756 {
3757 	driverlink_t dl;
3758 	devclass_t dc;
3759 	device_t child;
3760 
3761 	dc = dev->devclass;
3762 	TAILQ_FOREACH(dl, &dc->drivers, link) {
3763 		if (dl->pass == bus_current_pass)
3764 			DEVICE_IDENTIFY(dl->driver, dev);
3765 	}
3766 	TAILQ_FOREACH(child, &dev->children, link) {
3767 		if (child->state >= DS_ATTACHED)
3768 			BUS_NEW_PASS(child);
3769 		else if (child->state == DS_NOTPRESENT)
3770 			device_probe_and_attach(child);
3771 	}
3772 }
3773 
3774 /**
3775  * @brief Helper function for implementing BUS_SETUP_INTR().
3776  *
3777  * This simple implementation of BUS_SETUP_INTR() simply calls the
3778  * BUS_SETUP_INTR() method of the parent of @p dev.
3779  */
3780 int
3781 bus_generic_setup_intr(device_t dev, device_t child, struct resource *irq,
3782     int flags, driver_filter_t *filter, driver_intr_t *intr, void *arg,
3783     void **cookiep)
3784 {
3785 	/* Propagate up the bus hierarchy until someone handles it. */
3786 	if (dev->parent)
3787 		return (BUS_SETUP_INTR(dev->parent, child, irq, flags,
3788 		    filter, intr, arg, cookiep));
3789 	return (EINVAL);
3790 }
3791 
3792 /**
3793  * @brief Helper function for implementing BUS_TEARDOWN_INTR().
3794  *
3795  * This simple implementation of BUS_TEARDOWN_INTR() simply calls the
3796  * BUS_TEARDOWN_INTR() method of the parent of @p dev.
3797  */
3798 int
3799 bus_generic_teardown_intr(device_t dev, device_t child, struct resource *irq,
3800     void *cookie)
3801 {
3802 	/* Propagate up the bus hierarchy until someone handles it. */
3803 	if (dev->parent)
3804 		return (BUS_TEARDOWN_INTR(dev->parent, child, irq, cookie));
3805 	return (EINVAL);
3806 }
3807 
3808 /**
3809  * @brief Helper function for implementing BUS_ADJUST_RESOURCE().
3810  *
3811  * This simple implementation of BUS_ADJUST_RESOURCE() simply calls the
3812  * BUS_ADJUST_RESOURCE() method of the parent of @p dev.
3813  */
3814 int
3815 bus_generic_adjust_resource(device_t dev, device_t child, int type,
3816     struct resource *r, u_long start, u_long end)
3817 {
3818 	/* Propagate up the bus hierarchy until someone handles it. */
3819 	if (dev->parent)
3820 		return (BUS_ADJUST_RESOURCE(dev->parent, child, type, r, start,
3821 		    end));
3822 	return (EINVAL);
3823 }
3824 
3825 /**
3826  * @brief Helper function for implementing BUS_ALLOC_RESOURCE().
3827  *
3828  * This simple implementation of BUS_ALLOC_RESOURCE() simply calls the
3829  * BUS_ALLOC_RESOURCE() method of the parent of @p dev.
3830  */
3831 struct resource *
3832 bus_generic_alloc_resource(device_t dev, device_t child, int type, int *rid,
3833     u_long start, u_long end, u_long count, u_int flags)
3834 {
3835 	/* Propagate up the bus hierarchy until someone handles it. */
3836 	if (dev->parent)
3837 		return (BUS_ALLOC_RESOURCE(dev->parent, child, type, rid,
3838 		    start, end, count, flags));
3839 	return (NULL);
3840 }
3841 
3842 /**
3843  * @brief Helper function for implementing BUS_RELEASE_RESOURCE().
3844  *
3845  * This simple implementation of BUS_RELEASE_RESOURCE() simply calls the
3846  * BUS_RELEASE_RESOURCE() method of the parent of @p dev.
3847  */
3848 int
3849 bus_generic_release_resource(device_t dev, device_t child, int type, int rid,
3850     struct resource *r)
3851 {
3852 	/* Propagate up the bus hierarchy until someone handles it. */
3853 	if (dev->parent)
3854 		return (BUS_RELEASE_RESOURCE(dev->parent, child, type, rid,
3855 		    r));
3856 	return (EINVAL);
3857 }
3858 
3859 /**
3860  * @brief Helper function for implementing BUS_ACTIVATE_RESOURCE().
3861  *
3862  * This simple implementation of BUS_ACTIVATE_RESOURCE() simply calls the
3863  * BUS_ACTIVATE_RESOURCE() method of the parent of @p dev.
3864  */
3865 int
3866 bus_generic_activate_resource(device_t dev, device_t child, int type, int rid,
3867     struct resource *r)
3868 {
3869 	/* Propagate up the bus hierarchy until someone handles it. */
3870 	if (dev->parent)
3871 		return (BUS_ACTIVATE_RESOURCE(dev->parent, child, type, rid,
3872 		    r));
3873 	return (EINVAL);
3874 }
3875 
3876 /**
3877  * @brief Helper function for implementing BUS_DEACTIVATE_RESOURCE().
3878  *
3879  * This simple implementation of BUS_DEACTIVATE_RESOURCE() simply calls the
3880  * BUS_DEACTIVATE_RESOURCE() method of the parent of @p dev.
3881  */
3882 int
3883 bus_generic_deactivate_resource(device_t dev, device_t child, int type,
3884     int rid, struct resource *r)
3885 {
3886 	/* Propagate up the bus hierarchy until someone handles it. */
3887 	if (dev->parent)
3888 		return (BUS_DEACTIVATE_RESOURCE(dev->parent, child, type, rid,
3889 		    r));
3890 	return (EINVAL);
3891 }
3892 
3893 /**
3894  * @brief Helper function for implementing BUS_BIND_INTR().
3895  *
3896  * This simple implementation of BUS_BIND_INTR() simply calls the
3897  * BUS_BIND_INTR() method of the parent of @p dev.
3898  */
3899 int
3900 bus_generic_bind_intr(device_t dev, device_t child, struct resource *irq,
3901     int cpu)
3902 {
3903 
3904 	/* Propagate up the bus hierarchy until someone handles it. */
3905 	if (dev->parent)
3906 		return (BUS_BIND_INTR(dev->parent, child, irq, cpu));
3907 	return (EINVAL);
3908 }
3909 
3910 /**
3911  * @brief Helper function for implementing BUS_CONFIG_INTR().
3912  *
3913  * This simple implementation of BUS_CONFIG_INTR() simply calls the
3914  * BUS_CONFIG_INTR() method of the parent of @p dev.
3915  */
3916 int
3917 bus_generic_config_intr(device_t dev, int irq, enum intr_trigger trig,
3918     enum intr_polarity pol)
3919 {
3920 
3921 	/* Propagate up the bus hierarchy until someone handles it. */
3922 	if (dev->parent)
3923 		return (BUS_CONFIG_INTR(dev->parent, irq, trig, pol));
3924 	return (EINVAL);
3925 }
3926 
3927 /**
3928  * @brief Helper function for implementing BUS_DESCRIBE_INTR().
3929  *
3930  * This simple implementation of BUS_DESCRIBE_INTR() simply calls the
3931  * BUS_DESCRIBE_INTR() method of the parent of @p dev.
3932  */
3933 int
3934 bus_generic_describe_intr(device_t dev, device_t child, struct resource *irq,
3935     void *cookie, const char *descr)
3936 {
3937 
3938 	/* Propagate up the bus hierarchy until someone handles it. */
3939 	if (dev->parent)
3940 		return (BUS_DESCRIBE_INTR(dev->parent, child, irq, cookie,
3941 		    descr));
3942 	return (EINVAL);
3943 }
3944 
3945 /**
3946  * @brief Helper function for implementing BUS_GET_DMA_TAG().
3947  *
3948  * This simple implementation of BUS_GET_DMA_TAG() simply calls the
3949  * BUS_GET_DMA_TAG() method of the parent of @p dev.
3950  */
3951 bus_dma_tag_t
3952 bus_generic_get_dma_tag(device_t dev, device_t child)
3953 {
3954 
3955 	/* Propagate up the bus hierarchy until someone handles it. */
3956 	if (dev->parent != NULL)
3957 		return (BUS_GET_DMA_TAG(dev->parent, child));
3958 	return (NULL);
3959 }
3960 
3961 /**
3962  * @brief Helper function for implementing BUS_GET_RESOURCE().
3963  *
3964  * This implementation of BUS_GET_RESOURCE() uses the
3965  * resource_list_find() function to do most of the work. It calls
3966  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
3967  * search.
3968  */
3969 int
3970 bus_generic_rl_get_resource(device_t dev, device_t child, int type, int rid,
3971     u_long *startp, u_long *countp)
3972 {
3973 	struct resource_list *		rl = NULL;
3974 	struct resource_list_entry *	rle = NULL;
3975 
3976 	rl = BUS_GET_RESOURCE_LIST(dev, child);
3977 	if (!rl)
3978 		return (EINVAL);
3979 
3980 	rle = resource_list_find(rl, type, rid);
3981 	if (!rle)
3982 		return (ENOENT);
3983 
3984 	if (startp)
3985 		*startp = rle->start;
3986 	if (countp)
3987 		*countp = rle->count;
3988 
3989 	return (0);
3990 }
3991 
3992 /**
3993  * @brief Helper function for implementing BUS_SET_RESOURCE().
3994  *
3995  * This implementation of BUS_SET_RESOURCE() uses the
3996  * resource_list_add() function to do most of the work. It calls
3997  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
3998  * edit.
3999  */
4000 int
4001 bus_generic_rl_set_resource(device_t dev, device_t child, int type, int rid,
4002     u_long start, u_long count)
4003 {
4004 	struct resource_list *		rl = NULL;
4005 
4006 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4007 	if (!rl)
4008 		return (EINVAL);
4009 
4010 	resource_list_add(rl, type, rid, start, (start + count - 1), count);
4011 
4012 	return (0);
4013 }
4014 
4015 /**
4016  * @brief Helper function for implementing BUS_DELETE_RESOURCE().
4017  *
4018  * This implementation of BUS_DELETE_RESOURCE() uses the
4019  * resource_list_delete() function to do most of the work. It calls
4020  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
4021  * edit.
4022  */
4023 void
4024 bus_generic_rl_delete_resource(device_t dev, device_t child, int type, int rid)
4025 {
4026 	struct resource_list *		rl = NULL;
4027 
4028 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4029 	if (!rl)
4030 		return;
4031 
4032 	resource_list_delete(rl, type, rid);
4033 
4034 	return;
4035 }
4036 
4037 /**
4038  * @brief Helper function for implementing BUS_RELEASE_RESOURCE().
4039  *
4040  * This implementation of BUS_RELEASE_RESOURCE() uses the
4041  * resource_list_release() function to do most of the work. It calls
4042  * BUS_GET_RESOURCE_LIST() to find a suitable resource list.
4043  */
4044 int
4045 bus_generic_rl_release_resource(device_t dev, device_t child, int type,
4046     int rid, struct resource *r)
4047 {
4048 	struct resource_list *		rl = NULL;
4049 
4050 	if (device_get_parent(child) != dev)
4051 		return (BUS_RELEASE_RESOURCE(device_get_parent(dev), child,
4052 		    type, rid, r));
4053 
4054 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4055 	if (!rl)
4056 		return (EINVAL);
4057 
4058 	return (resource_list_release(rl, dev, child, type, rid, r));
4059 }
4060 
4061 /**
4062  * @brief Helper function for implementing BUS_ALLOC_RESOURCE().
4063  *
4064  * This implementation of BUS_ALLOC_RESOURCE() uses the
4065  * resource_list_alloc() function to do most of the work. It calls
4066  * BUS_GET_RESOURCE_LIST() to find a suitable resource list.
4067  */
4068 struct resource *
4069 bus_generic_rl_alloc_resource(device_t dev, device_t child, int type,
4070     int *rid, u_long start, u_long end, u_long count, u_int flags)
4071 {
4072 	struct resource_list *		rl = NULL;
4073 
4074 	if (device_get_parent(child) != dev)
4075 		return (BUS_ALLOC_RESOURCE(device_get_parent(dev), child,
4076 		    type, rid, start, end, count, flags));
4077 
4078 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4079 	if (!rl)
4080 		return (NULL);
4081 
4082 	return (resource_list_alloc(rl, dev, child, type, rid,
4083 	    start, end, count, flags));
4084 }
4085 
4086 /**
4087  * @brief Helper function for implementing BUS_CHILD_PRESENT().
4088  *
4089  * This simple implementation of BUS_CHILD_PRESENT() simply calls the
4090  * BUS_CHILD_PRESENT() method of the parent of @p dev.
4091  */
4092 int
4093 bus_generic_child_present(device_t dev, device_t child)
4094 {
4095 	return (BUS_CHILD_PRESENT(device_get_parent(dev), dev));
4096 }
4097 
4098 /*
4099  * Some convenience functions to make it easier for drivers to use the
4100  * resource-management functions.  All these really do is hide the
4101  * indirection through the parent's method table, making for slightly
4102  * less-wordy code.  In the future, it might make sense for this code
4103  * to maintain some sort of a list of resources allocated by each device.
4104  */
4105 
4106 int
4107 bus_alloc_resources(device_t dev, struct resource_spec *rs,
4108     struct resource **res)
4109 {
4110 	int i;
4111 
4112 	for (i = 0; rs[i].type != -1; i++)
4113 		res[i] = NULL;
4114 	for (i = 0; rs[i].type != -1; i++) {
4115 		res[i] = bus_alloc_resource_any(dev,
4116 		    rs[i].type, &rs[i].rid, rs[i].flags);
4117 		if (res[i] == NULL && !(rs[i].flags & RF_OPTIONAL)) {
4118 			bus_release_resources(dev, rs, res);
4119 			return (ENXIO);
4120 		}
4121 	}
4122 	return (0);
4123 }
4124 
4125 void
4126 bus_release_resources(device_t dev, const struct resource_spec *rs,
4127     struct resource **res)
4128 {
4129 	int i;
4130 
4131 	for (i = 0; rs[i].type != -1; i++)
4132 		if (res[i] != NULL) {
4133 			bus_release_resource(
4134 			    dev, rs[i].type, rs[i].rid, res[i]);
4135 			res[i] = NULL;
4136 		}
4137 }
4138 
4139 /**
4140  * @brief Wrapper function for BUS_ALLOC_RESOURCE().
4141  *
4142  * This function simply calls the BUS_ALLOC_RESOURCE() method of the
4143  * parent of @p dev.
4144  */
4145 struct resource *
4146 bus_alloc_resource(device_t dev, int type, int *rid, u_long start, u_long end,
4147     u_long count, u_int flags)
4148 {
4149 	if (dev->parent == NULL)
4150 		return (NULL);
4151 	return (BUS_ALLOC_RESOURCE(dev->parent, dev, type, rid, start, end,
4152 	    count, flags));
4153 }
4154 
4155 /**
4156  * @brief Wrapper function for BUS_ADJUST_RESOURCE().
4157  *
4158  * This function simply calls the BUS_ADJUST_RESOURCE() method of the
4159  * parent of @p dev.
4160  */
4161 int
4162 bus_adjust_resource(device_t dev, int type, struct resource *r, u_long start,
4163     u_long end)
4164 {
4165 	if (dev->parent == NULL)
4166 		return (EINVAL);
4167 	return (BUS_ADJUST_RESOURCE(dev->parent, dev, type, r, start, end));
4168 }
4169 
4170 /**
4171  * @brief Wrapper function for BUS_ACTIVATE_RESOURCE().
4172  *
4173  * This function simply calls the BUS_ACTIVATE_RESOURCE() method of the
4174  * parent of @p dev.
4175  */
4176 int
4177 bus_activate_resource(device_t dev, int type, int rid, struct resource *r)
4178 {
4179 	if (dev->parent == NULL)
4180 		return (EINVAL);
4181 	return (BUS_ACTIVATE_RESOURCE(dev->parent, dev, type, rid, r));
4182 }
4183 
4184 /**
4185  * @brief Wrapper function for BUS_DEACTIVATE_RESOURCE().
4186  *
4187  * This function simply calls the BUS_DEACTIVATE_RESOURCE() method of the
4188  * parent of @p dev.
4189  */
4190 int
4191 bus_deactivate_resource(device_t dev, int type, int rid, struct resource *r)
4192 {
4193 	if (dev->parent == NULL)
4194 		return (EINVAL);
4195 	return (BUS_DEACTIVATE_RESOURCE(dev->parent, dev, type, rid, r));
4196 }
4197 
4198 /**
4199  * @brief Wrapper function for BUS_RELEASE_RESOURCE().
4200  *
4201  * This function simply calls the BUS_RELEASE_RESOURCE() method of the
4202  * parent of @p dev.
4203  */
4204 int
4205 bus_release_resource(device_t dev, int type, int rid, struct resource *r)
4206 {
4207 	if (dev->parent == NULL)
4208 		return (EINVAL);
4209 	return (BUS_RELEASE_RESOURCE(dev->parent, dev, type, rid, r));
4210 }
4211 
4212 /**
4213  * @brief Wrapper function for BUS_SETUP_INTR().
4214  *
4215  * This function simply calls the BUS_SETUP_INTR() method of the
4216  * parent of @p dev.
4217  */
4218 int
4219 bus_setup_intr(device_t dev, struct resource *r, int flags,
4220     driver_filter_t filter, driver_intr_t handler, void *arg, void **cookiep)
4221 {
4222 	int error;
4223 
4224 	if (dev->parent == NULL)
4225 		return (EINVAL);
4226 	error = BUS_SETUP_INTR(dev->parent, dev, r, flags, filter, handler,
4227 	    arg, cookiep);
4228 	if (error != 0)
4229 		return (error);
4230 	if (handler != NULL && !(flags & INTR_MPSAFE))
4231 		device_printf(dev, "[GIANT-LOCKED]\n");
4232 	return (0);
4233 }
4234 
4235 /**
4236  * @brief Wrapper function for BUS_TEARDOWN_INTR().
4237  *
4238  * This function simply calls the BUS_TEARDOWN_INTR() method of the
4239  * parent of @p dev.
4240  */
4241 int
4242 bus_teardown_intr(device_t dev, struct resource *r, void *cookie)
4243 {
4244 	if (dev->parent == NULL)
4245 		return (EINVAL);
4246 	return (BUS_TEARDOWN_INTR(dev->parent, dev, r, cookie));
4247 }
4248 
4249 /**
4250  * @brief Wrapper function for BUS_BIND_INTR().
4251  *
4252  * This function simply calls the BUS_BIND_INTR() method of the
4253  * parent of @p dev.
4254  */
4255 int
4256 bus_bind_intr(device_t dev, struct resource *r, int cpu)
4257 {
4258 	if (dev->parent == NULL)
4259 		return (EINVAL);
4260 	return (BUS_BIND_INTR(dev->parent, dev, r, cpu));
4261 }
4262 
4263 /**
4264  * @brief Wrapper function for BUS_DESCRIBE_INTR().
4265  *
4266  * This function first formats the requested description into a
4267  * temporary buffer and then calls the BUS_DESCRIBE_INTR() method of
4268  * the parent of @p dev.
4269  */
4270 int
4271 bus_describe_intr(device_t dev, struct resource *irq, void *cookie,
4272     const char *fmt, ...)
4273 {
4274 	va_list ap;
4275 	char descr[MAXCOMLEN + 1];
4276 
4277 	if (dev->parent == NULL)
4278 		return (EINVAL);
4279 	va_start(ap, fmt);
4280 	vsnprintf(descr, sizeof(descr), fmt, ap);
4281 	va_end(ap);
4282 	return (BUS_DESCRIBE_INTR(dev->parent, dev, irq, cookie, descr));
4283 }
4284 
4285 /**
4286  * @brief Wrapper function for BUS_SET_RESOURCE().
4287  *
4288  * This function simply calls the BUS_SET_RESOURCE() method of the
4289  * parent of @p dev.
4290  */
4291 int
4292 bus_set_resource(device_t dev, int type, int rid,
4293     u_long start, u_long count)
4294 {
4295 	return (BUS_SET_RESOURCE(device_get_parent(dev), dev, type, rid,
4296 	    start, count));
4297 }
4298 
4299 /**
4300  * @brief Wrapper function for BUS_GET_RESOURCE().
4301  *
4302  * This function simply calls the BUS_GET_RESOURCE() method of the
4303  * parent of @p dev.
4304  */
4305 int
4306 bus_get_resource(device_t dev, int type, int rid,
4307     u_long *startp, u_long *countp)
4308 {
4309 	return (BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4310 	    startp, countp));
4311 }
4312 
4313 /**
4314  * @brief Wrapper function for BUS_GET_RESOURCE().
4315  *
4316  * This function simply calls the BUS_GET_RESOURCE() method of the
4317  * parent of @p dev and returns the start value.
4318  */
4319 u_long
4320 bus_get_resource_start(device_t dev, int type, int rid)
4321 {
4322 	u_long start, count;
4323 	int error;
4324 
4325 	error = BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4326 	    &start, &count);
4327 	if (error)
4328 		return (0);
4329 	return (start);
4330 }
4331 
4332 /**
4333  * @brief Wrapper function for BUS_GET_RESOURCE().
4334  *
4335  * This function simply calls the BUS_GET_RESOURCE() method of the
4336  * parent of @p dev and returns the count value.
4337  */
4338 u_long
4339 bus_get_resource_count(device_t dev, int type, int rid)
4340 {
4341 	u_long start, count;
4342 	int error;
4343 
4344 	error = BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4345 	    &start, &count);
4346 	if (error)
4347 		return (0);
4348 	return (count);
4349 }
4350 
4351 /**
4352  * @brief Wrapper function for BUS_DELETE_RESOURCE().
4353  *
4354  * This function simply calls the BUS_DELETE_RESOURCE() method of the
4355  * parent of @p dev.
4356  */
4357 void
4358 bus_delete_resource(device_t dev, int type, int rid)
4359 {
4360 	BUS_DELETE_RESOURCE(device_get_parent(dev), dev, type, rid);
4361 }
4362 
4363 /**
4364  * @brief Wrapper function for BUS_CHILD_PRESENT().
4365  *
4366  * This function simply calls the BUS_CHILD_PRESENT() method of the
4367  * parent of @p dev.
4368  */
4369 int
4370 bus_child_present(device_t child)
4371 {
4372 	return (BUS_CHILD_PRESENT(device_get_parent(child), child));
4373 }
4374 
4375 /**
4376  * @brief Wrapper function for BUS_CHILD_PNPINFO_STR().
4377  *
4378  * This function simply calls the BUS_CHILD_PNPINFO_STR() method of the
4379  * parent of @p dev.
4380  */
4381 int
4382 bus_child_pnpinfo_str(device_t child, char *buf, size_t buflen)
4383 {
4384 	device_t parent;
4385 
4386 	parent = device_get_parent(child);
4387 	if (parent == NULL) {
4388 		*buf = '\0';
4389 		return (0);
4390 	}
4391 	return (BUS_CHILD_PNPINFO_STR(parent, child, buf, buflen));
4392 }
4393 
4394 /**
4395  * @brief Wrapper function for BUS_CHILD_LOCATION_STR().
4396  *
4397  * This function simply calls the BUS_CHILD_LOCATION_STR() method of the
4398  * parent of @p dev.
4399  */
4400 int
4401 bus_child_location_str(device_t child, char *buf, size_t buflen)
4402 {
4403 	device_t parent;
4404 
4405 	parent = device_get_parent(child);
4406 	if (parent == NULL) {
4407 		*buf = '\0';
4408 		return (0);
4409 	}
4410 	return (BUS_CHILD_LOCATION_STR(parent, child, buf, buflen));
4411 }
4412 
4413 /**
4414  * @brief Wrapper function for BUS_GET_DMA_TAG().
4415  *
4416  * This function simply calls the BUS_GET_DMA_TAG() method of the
4417  * parent of @p dev.
4418  */
4419 bus_dma_tag_t
4420 bus_get_dma_tag(device_t dev)
4421 {
4422 	device_t parent;
4423 
4424 	parent = device_get_parent(dev);
4425 	if (parent == NULL)
4426 		return (NULL);
4427 	return (BUS_GET_DMA_TAG(parent, dev));
4428 }
4429 
4430 /* Resume all devices and then notify userland that we're up again. */
4431 static int
4432 root_resume(device_t dev)
4433 {
4434 	int error;
4435 
4436 	error = bus_generic_resume(dev);
4437 	if (error == 0)
4438 		devctl_notify("kern", "power", "resume", NULL);
4439 	return (error);
4440 }
4441 
4442 static int
4443 root_print_child(device_t dev, device_t child)
4444 {
4445 	int	retval = 0;
4446 
4447 	retval += bus_print_child_header(dev, child);
4448 	retval += printf("\n");
4449 
4450 	return (retval);
4451 }
4452 
4453 static int
4454 root_setup_intr(device_t dev, device_t child, struct resource *irq, int flags,
4455     driver_filter_t *filter, driver_intr_t *intr, void *arg, void **cookiep)
4456 {
4457 	/*
4458 	 * If an interrupt mapping gets to here something bad has happened.
4459 	 */
4460 	panic("root_setup_intr");
4461 }
4462 
4463 /*
4464  * If we get here, assume that the device is permanant and really is
4465  * present in the system.  Removable bus drivers are expected to intercept
4466  * this call long before it gets here.  We return -1 so that drivers that
4467  * really care can check vs -1 or some ERRNO returned higher in the food
4468  * chain.
4469  */
4470 static int
4471 root_child_present(device_t dev, device_t child)
4472 {
4473 	return (-1);
4474 }
4475 
4476 static kobj_method_t root_methods[] = {
4477 	/* Device interface */
4478 	KOBJMETHOD(device_shutdown,	bus_generic_shutdown),
4479 	KOBJMETHOD(device_suspend,	bus_generic_suspend),
4480 	KOBJMETHOD(device_resume,	root_resume),
4481 
4482 	/* Bus interface */
4483 	KOBJMETHOD(bus_print_child,	root_print_child),
4484 	KOBJMETHOD(bus_read_ivar,	bus_generic_read_ivar),
4485 	KOBJMETHOD(bus_write_ivar,	bus_generic_write_ivar),
4486 	KOBJMETHOD(bus_setup_intr,	root_setup_intr),
4487 	KOBJMETHOD(bus_child_present,	root_child_present),
4488 
4489 	KOBJMETHOD_END
4490 };
4491 
4492 static driver_t root_driver = {
4493 	"root",
4494 	root_methods,
4495 	1,			/* no softc */
4496 };
4497 
4498 device_t	root_bus;
4499 devclass_t	root_devclass;
4500 
4501 static int
4502 root_bus_module_handler(module_t mod, int what, void* arg)
4503 {
4504 	switch (what) {
4505 	case MOD_LOAD:
4506 		TAILQ_INIT(&bus_data_devices);
4507 		kobj_class_compile((kobj_class_t) &root_driver);
4508 		root_bus = make_device(NULL, "root", 0);
4509 		root_bus->desc = "System root bus";
4510 		kobj_init((kobj_t) root_bus, (kobj_class_t) &root_driver);
4511 		root_bus->driver = &root_driver;
4512 		root_bus->state = DS_ATTACHED;
4513 		root_devclass = devclass_find_internal("root", NULL, FALSE);
4514 		devinit();
4515 		return (0);
4516 
4517 	case MOD_SHUTDOWN:
4518 		device_shutdown(root_bus);
4519 		return (0);
4520 	default:
4521 		return (EOPNOTSUPP);
4522 	}
4523 
4524 	return (0);
4525 }
4526 
4527 static moduledata_t root_bus_mod = {
4528 	"rootbus",
4529 	root_bus_module_handler,
4530 	NULL
4531 };
4532 DECLARE_MODULE(rootbus, root_bus_mod, SI_SUB_DRIVERS, SI_ORDER_FIRST);
4533 
4534 /**
4535  * @brief Automatically configure devices
4536  *
4537  * This function begins the autoconfiguration process by calling
4538  * device_probe_and_attach() for each child of the @c root0 device.
4539  */
4540 void
4541 root_bus_configure(void)
4542 {
4543 
4544 	PDEBUG(("."));
4545 
4546 	/* Eventually this will be split up, but this is sufficient for now. */
4547 	bus_set_pass(BUS_PASS_DEFAULT);
4548 }
4549 
4550 /**
4551  * @brief Module handler for registering device drivers
4552  *
4553  * This module handler is used to automatically register device
4554  * drivers when modules are loaded. If @p what is MOD_LOAD, it calls
4555  * devclass_add_driver() for the driver described by the
4556  * driver_module_data structure pointed to by @p arg
4557  */
4558 int
4559 driver_module_handler(module_t mod, int what, void *arg)
4560 {
4561 	struct driver_module_data *dmd;
4562 	devclass_t bus_devclass;
4563 	kobj_class_t driver;
4564 	int error, pass;
4565 
4566 	dmd = (struct driver_module_data *)arg;
4567 	bus_devclass = devclass_find_internal(dmd->dmd_busname, NULL, TRUE);
4568 	error = 0;
4569 
4570 	switch (what) {
4571 	case MOD_LOAD:
4572 		if (dmd->dmd_chainevh)
4573 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
4574 
4575 		pass = dmd->dmd_pass;
4576 		driver = dmd->dmd_driver;
4577 		PDEBUG(("Loading module: driver %s on bus %s (pass %d)",
4578 		    DRIVERNAME(driver), dmd->dmd_busname, pass));
4579 		error = devclass_add_driver(bus_devclass, driver, pass,
4580 		    dmd->dmd_devclass);
4581 		break;
4582 
4583 	case MOD_UNLOAD:
4584 		PDEBUG(("Unloading module: driver %s from bus %s",
4585 		    DRIVERNAME(dmd->dmd_driver),
4586 		    dmd->dmd_busname));
4587 		error = devclass_delete_driver(bus_devclass,
4588 		    dmd->dmd_driver);
4589 
4590 		if (!error && dmd->dmd_chainevh)
4591 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
4592 		break;
4593 	case MOD_QUIESCE:
4594 		PDEBUG(("Quiesce module: driver %s from bus %s",
4595 		    DRIVERNAME(dmd->dmd_driver),
4596 		    dmd->dmd_busname));
4597 		error = devclass_quiesce_driver(bus_devclass,
4598 		    dmd->dmd_driver);
4599 
4600 		if (!error && dmd->dmd_chainevh)
4601 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
4602 		break;
4603 	default:
4604 		error = EOPNOTSUPP;
4605 		break;
4606 	}
4607 
4608 	return (error);
4609 }
4610 
4611 /**
4612  * @brief Enumerate all hinted devices for this bus.
4613  *
4614  * Walks through the hints for this bus and calls the bus_hinted_child
4615  * routine for each one it fines.  It searches first for the specific
4616  * bus that's being probed for hinted children (eg isa0), and then for
4617  * generic children (eg isa).
4618  *
4619  * @param	dev	bus device to enumerate
4620  */
4621 void
4622 bus_enumerate_hinted_children(device_t bus)
4623 {
4624 	int i;
4625 	const char *dname, *busname;
4626 	int dunit;
4627 
4628 	/*
4629 	 * enumerate all devices on the specific bus
4630 	 */
4631 	busname = device_get_nameunit(bus);
4632 	i = 0;
4633 	while (resource_find_match(&i, &dname, &dunit, "at", busname) == 0)
4634 		BUS_HINTED_CHILD(bus, dname, dunit);
4635 
4636 	/*
4637 	 * and all the generic ones.
4638 	 */
4639 	busname = device_get_name(bus);
4640 	i = 0;
4641 	while (resource_find_match(&i, &dname, &dunit, "at", busname) == 0)
4642 		BUS_HINTED_CHILD(bus, dname, dunit);
4643 }
4644 
4645 #ifdef BUS_DEBUG
4646 
4647 /* the _short versions avoid iteration by not calling anything that prints
4648  * more than oneliners. I love oneliners.
4649  */
4650 
4651 static void
4652 print_device_short(device_t dev, int indent)
4653 {
4654 	if (!dev)
4655 		return;
4656 
4657 	indentprintf(("device %d: <%s> %sparent,%schildren,%s%s%s%s%s,%sivars,%ssoftc,busy=%d\n",
4658 	    dev->unit, dev->desc,
4659 	    (dev->parent? "":"no "),
4660 	    (TAILQ_EMPTY(&dev->children)? "no ":""),
4661 	    (dev->flags&DF_ENABLED? "enabled,":"disabled,"),
4662 	    (dev->flags&DF_FIXEDCLASS? "fixed,":""),
4663 	    (dev->flags&DF_WILDCARD? "wildcard,":""),
4664 	    (dev->flags&DF_DESCMALLOCED? "descmalloced,":""),
4665 	    (dev->flags&DF_REBID? "rebiddable,":""),
4666 	    (dev->ivars? "":"no "),
4667 	    (dev->softc? "":"no "),
4668 	    dev->busy));
4669 }
4670 
4671 static void
4672 print_device(device_t dev, int indent)
4673 {
4674 	if (!dev)
4675 		return;
4676 
4677 	print_device_short(dev, indent);
4678 
4679 	indentprintf(("Parent:\n"));
4680 	print_device_short(dev->parent, indent+1);
4681 	indentprintf(("Driver:\n"));
4682 	print_driver_short(dev->driver, indent+1);
4683 	indentprintf(("Devclass:\n"));
4684 	print_devclass_short(dev->devclass, indent+1);
4685 }
4686 
4687 void
4688 print_device_tree_short(device_t dev, int indent)
4689 /* print the device and all its children (indented) */
4690 {
4691 	device_t child;
4692 
4693 	if (!dev)
4694 		return;
4695 
4696 	print_device_short(dev, indent);
4697 
4698 	TAILQ_FOREACH(child, &dev->children, link) {
4699 		print_device_tree_short(child, indent+1);
4700 	}
4701 }
4702 
4703 void
4704 print_device_tree(device_t dev, int indent)
4705 /* print the device and all its children (indented) */
4706 {
4707 	device_t child;
4708 
4709 	if (!dev)
4710 		return;
4711 
4712 	print_device(dev, indent);
4713 
4714 	TAILQ_FOREACH(child, &dev->children, link) {
4715 		print_device_tree(child, indent+1);
4716 	}
4717 }
4718 
4719 static void
4720 print_driver_short(driver_t *driver, int indent)
4721 {
4722 	if (!driver)
4723 		return;
4724 
4725 	indentprintf(("driver %s: softc size = %zd\n",
4726 	    driver->name, driver->size));
4727 }
4728 
4729 static void
4730 print_driver(driver_t *driver, int indent)
4731 {
4732 	if (!driver)
4733 		return;
4734 
4735 	print_driver_short(driver, indent);
4736 }
4737 
4738 static void
4739 print_driver_list(driver_list_t drivers, int indent)
4740 {
4741 	driverlink_t driver;
4742 
4743 	TAILQ_FOREACH(driver, &drivers, link) {
4744 		print_driver(driver->driver, indent);
4745 	}
4746 }
4747 
4748 static void
4749 print_devclass_short(devclass_t dc, int indent)
4750 {
4751 	if ( !dc )
4752 		return;
4753 
4754 	indentprintf(("devclass %s: max units = %d\n", dc->name, dc->maxunit));
4755 }
4756 
4757 static void
4758 print_devclass(devclass_t dc, int indent)
4759 {
4760 	int i;
4761 
4762 	if ( !dc )
4763 		return;
4764 
4765 	print_devclass_short(dc, indent);
4766 	indentprintf(("Drivers:\n"));
4767 	print_driver_list(dc->drivers, indent+1);
4768 
4769 	indentprintf(("Devices:\n"));
4770 	for (i = 0; i < dc->maxunit; i++)
4771 		if (dc->devices[i])
4772 			print_device(dc->devices[i], indent+1);
4773 }
4774 
4775 void
4776 print_devclass_list_short(void)
4777 {
4778 	devclass_t dc;
4779 
4780 	printf("Short listing of devclasses, drivers & devices:\n");
4781 	TAILQ_FOREACH(dc, &devclasses, link) {
4782 		print_devclass_short(dc, 0);
4783 	}
4784 }
4785 
4786 void
4787 print_devclass_list(void)
4788 {
4789 	devclass_t dc;
4790 
4791 	printf("Full listing of devclasses, drivers & devices:\n");
4792 	TAILQ_FOREACH(dc, &devclasses, link) {
4793 		print_devclass(dc, 0);
4794 	}
4795 }
4796 
4797 #endif
4798 
4799 /*
4800  * User-space access to the device tree.
4801  *
4802  * We implement a small set of nodes:
4803  *
4804  * hw.bus			Single integer read method to obtain the
4805  *				current generation count.
4806  * hw.bus.devices		Reads the entire device tree in flat space.
4807  * hw.bus.rman			Resource manager interface
4808  *
4809  * We might like to add the ability to scan devclasses and/or drivers to
4810  * determine what else is currently loaded/available.
4811  */
4812 
4813 static int
4814 sysctl_bus(SYSCTL_HANDLER_ARGS)
4815 {
4816 	struct u_businfo	ubus;
4817 
4818 	ubus.ub_version = BUS_USER_VERSION;
4819 	ubus.ub_generation = bus_data_generation;
4820 
4821 	return (SYSCTL_OUT(req, &ubus, sizeof(ubus)));
4822 }
4823 SYSCTL_NODE(_hw_bus, OID_AUTO, info, CTLFLAG_RW, sysctl_bus,
4824     "bus-related data");
4825 
4826 static int
4827 sysctl_devices(SYSCTL_HANDLER_ARGS)
4828 {
4829 	int			*name = (int *)arg1;
4830 	u_int			namelen = arg2;
4831 	int			index;
4832 	struct device		*dev;
4833 	struct u_device		udev;	/* XXX this is a bit big */
4834 	int			error;
4835 
4836 	if (namelen != 2)
4837 		return (EINVAL);
4838 
4839 	if (bus_data_generation_check(name[0]))
4840 		return (EINVAL);
4841 
4842 	index = name[1];
4843 
4844 	/*
4845 	 * Scan the list of devices, looking for the requested index.
4846 	 */
4847 	TAILQ_FOREACH(dev, &bus_data_devices, devlink) {
4848 		if (index-- == 0)
4849 			break;
4850 	}
4851 	if (dev == NULL)
4852 		return (ENOENT);
4853 
4854 	/*
4855 	 * Populate the return array.
4856 	 */
4857 	bzero(&udev, sizeof(udev));
4858 	udev.dv_handle = (uintptr_t)dev;
4859 	udev.dv_parent = (uintptr_t)dev->parent;
4860 	if (dev->nameunit != NULL)
4861 		strlcpy(udev.dv_name, dev->nameunit, sizeof(udev.dv_name));
4862 	if (dev->desc != NULL)
4863 		strlcpy(udev.dv_desc, dev->desc, sizeof(udev.dv_desc));
4864 	if (dev->driver != NULL && dev->driver->name != NULL)
4865 		strlcpy(udev.dv_drivername, dev->driver->name,
4866 		    sizeof(udev.dv_drivername));
4867 	bus_child_pnpinfo_str(dev, udev.dv_pnpinfo, sizeof(udev.dv_pnpinfo));
4868 	bus_child_location_str(dev, udev.dv_location, sizeof(udev.dv_location));
4869 	udev.dv_devflags = dev->devflags;
4870 	udev.dv_flags = dev->flags;
4871 	udev.dv_state = dev->state;
4872 	error = SYSCTL_OUT(req, &udev, sizeof(udev));
4873 	return (error);
4874 }
4875 
4876 SYSCTL_NODE(_hw_bus, OID_AUTO, devices, CTLFLAG_RD, sysctl_devices,
4877     "system device tree");
4878 
4879 int
4880 bus_data_generation_check(int generation)
4881 {
4882 	if (generation != bus_data_generation)
4883 		return (1);
4884 
4885 	/* XXX generate optimised lists here? */
4886 	return (0);
4887 }
4888 
4889 void
4890 bus_data_generation_update(void)
4891 {
4892 	bus_data_generation++;
4893 }
4894 
4895 int
4896 bus_free_resource(device_t dev, int type, struct resource *r)
4897 {
4898 	if (r == NULL)
4899 		return (0);
4900 	return (bus_release_resource(dev, type, rman_get_rid(r), r));
4901 }
4902