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