xref: /freebsd/sys/kern/subr_bus.c (revision ed88eef140a1c3d57d546f409c216806dd3da809)
1 /*-
2  * SPDX-License-Identifier: BSD-2-Clause
3  *
4  * Copyright (c) 1997,1998,2003 Doug Rabson
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  */
28 
29 #include <sys/cdefs.h>
30 #include "opt_bus.h"
31 #include "opt_ddb.h"
32 
33 #include <sys/param.h>
34 #include <sys/conf.h>
35 #include <sys/domainset.h>
36 #include <sys/eventhandler.h>
37 #include <sys/lock.h>
38 #include <sys/kernel.h>
39 #include <sys/limits.h>
40 #include <sys/malloc.h>
41 #include <sys/module.h>
42 #include <sys/mutex.h>
43 #include <sys/priv.h>
44 #include <machine/bus.h>
45 #include <sys/random.h>
46 #include <sys/refcount.h>
47 #include <sys/rman.h>
48 #include <sys/sbuf.h>
49 #include <sys/smp.h>
50 #include <sys/sysctl.h>
51 #include <sys/systm.h>
52 #include <sys/bus.h>
53 #include <sys/cpuset.h>
54 
55 #include <net/vnet.h>
56 
57 #include <machine/cpu.h>
58 #include <machine/stdarg.h>
59 
60 #include <vm/uma.h>
61 #include <vm/vm.h>
62 
63 #include <ddb/ddb.h>
64 
65 SYSCTL_NODE(_hw, OID_AUTO, bus, CTLFLAG_RW | CTLFLAG_MPSAFE, NULL,
66     NULL);
67 SYSCTL_ROOT_NODE(OID_AUTO, dev, CTLFLAG_RW | CTLFLAG_MPSAFE, NULL,
68     NULL);
69 
70 static bool disable_failed_devs = false;
71 SYSCTL_BOOL(_hw_bus, OID_AUTO, disable_failed_devices, CTLFLAG_RWTUN, &disable_failed_devs,
72     0, "Do not retry attaching devices that return an error from DEVICE_ATTACH the first time");
73 
74 /*
75  * Used to attach drivers to devclasses.
76  */
77 typedef struct driverlink *driverlink_t;
78 struct driverlink {
79 	kobj_class_t	driver;
80 	TAILQ_ENTRY(driverlink) link;	/* list of drivers in devclass */
81 	int		pass;
82 	int		flags;
83 #define DL_DEFERRED_PROBE	1	/* Probe deferred on this */
84 	TAILQ_ENTRY(driverlink) passlink;
85 };
86 
87 /*
88  * Forward declarations
89  */
90 typedef TAILQ_HEAD(devclass_list, devclass) devclass_list_t;
91 typedef TAILQ_HEAD(driver_list, driverlink) driver_list_t;
92 typedef TAILQ_HEAD(device_list, _device) device_list_t;
93 
94 struct devclass {
95 	TAILQ_ENTRY(devclass) link;
96 	devclass_t	parent;		/* parent in devclass hierarchy */
97 	driver_list_t	drivers;	/* bus devclasses store drivers for bus */
98 	char		*name;
99 	device_t	*devices;	/* array of devices indexed by unit */
100 	int		maxunit;	/* size of devices array */
101 	int		flags;
102 #define DC_HAS_CHILDREN		1
103 
104 	struct sysctl_ctx_list sysctl_ctx;
105 	struct sysctl_oid *sysctl_tree;
106 };
107 
108 /**
109  * @brief Implementation of _device.
110  *
111  * The structure is named "_device" instead of "device" to avoid type confusion
112  * caused by other subsystems defining a (struct device).
113  */
114 struct _device {
115 	/*
116 	 * A device is a kernel object. The first field must be the
117 	 * current ops table for the object.
118 	 */
119 	KOBJ_FIELDS;
120 
121 	/*
122 	 * Device hierarchy.
123 	 */
124 	TAILQ_ENTRY(_device)	link;	/**< list of devices in parent */
125 	TAILQ_ENTRY(_device)	devlink; /**< global device list membership */
126 	device_t	parent;		/**< parent of this device  */
127 	device_list_t	children;	/**< list of child devices */
128 
129 	/*
130 	 * Details of this device.
131 	 */
132 	driver_t	*driver;	/**< current driver */
133 	devclass_t	devclass;	/**< current device class */
134 	int		unit;		/**< current unit number */
135 	char*		nameunit;	/**< name+unit e.g. foodev0 */
136 	char*		desc;		/**< driver specific description */
137 	u_int		busy;		/**< count of calls to device_busy() */
138 	device_state_t	state;		/**< current device state  */
139 	uint32_t	devflags;	/**< api level flags for device_get_flags() */
140 	u_int		flags;		/**< internal device flags  */
141 	u_int	order;			/**< order from device_add_child_ordered() */
142 	void	*ivars;			/**< instance variables  */
143 	void	*softc;			/**< current driver's variables  */
144 
145 	struct sysctl_ctx_list sysctl_ctx; /**< state for sysctl variables  */
146 	struct sysctl_oid *sysctl_tree;	/**< state for sysctl variables */
147 };
148 
149 static MALLOC_DEFINE(M_BUS, "bus", "Bus data structures");
150 static MALLOC_DEFINE(M_BUS_SC, "bus-sc", "Bus data structures, softc");
151 
152 EVENTHANDLER_LIST_DEFINE(device_attach);
153 EVENTHANDLER_LIST_DEFINE(device_detach);
154 EVENTHANDLER_LIST_DEFINE(device_nomatch);
155 EVENTHANDLER_LIST_DEFINE(dev_lookup);
156 
157 static void devctl2_init(void);
158 static bool device_frozen;
159 
160 #define DRIVERNAME(d)	((d)? d->name : "no driver")
161 #define DEVCLANAME(d)	((d)? d->name : "no devclass")
162 
163 #ifdef BUS_DEBUG
164 
165 static int bus_debug = 1;
166 SYSCTL_INT(_debug, OID_AUTO, bus_debug, CTLFLAG_RWTUN, &bus_debug, 0,
167     "Bus debug level");
168 #define PDEBUG(a)	if (bus_debug) {printf("%s:%d: ", __func__, __LINE__), printf a; printf("\n");}
169 #define DEVICENAME(d)	((d)? device_get_name(d): "no device")
170 
171 /**
172  * Produce the indenting, indent*2 spaces plus a '.' ahead of that to
173  * prevent syslog from deleting initial spaces
174  */
175 #define indentprintf(p)	do { int iJ; printf("."); for (iJ=0; iJ<indent; iJ++) printf("  "); printf p ; } while (0)
176 
177 static void print_device_short(device_t dev, int indent);
178 static void print_device(device_t dev, int indent);
179 void print_device_tree_short(device_t dev, int indent);
180 void print_device_tree(device_t dev, int indent);
181 static void print_driver_short(driver_t *driver, int indent);
182 static void print_driver(driver_t *driver, int indent);
183 static void print_driver_list(driver_list_t drivers, int indent);
184 static void print_devclass_short(devclass_t dc, int indent);
185 static void print_devclass(devclass_t dc, int indent);
186 void print_devclass_list_short(void);
187 void print_devclass_list(void);
188 
189 #else
190 /* Make the compiler ignore the function calls */
191 #define PDEBUG(a)			/* nop */
192 #define DEVICENAME(d)			/* nop */
193 
194 #define print_device_short(d,i)		/* nop */
195 #define print_device(d,i)		/* nop */
196 #define print_device_tree_short(d,i)	/* nop */
197 #define print_device_tree(d,i)		/* nop */
198 #define print_driver_short(d,i)		/* nop */
199 #define print_driver(d,i)		/* nop */
200 #define print_driver_list(d,i)		/* nop */
201 #define print_devclass_short(d,i)	/* nop */
202 #define print_devclass(d,i)		/* nop */
203 #define print_devclass_list_short()	/* nop */
204 #define print_devclass_list()		/* nop */
205 #endif
206 
207 /*
208  * dev sysctl tree
209  */
210 
211 enum {
212 	DEVCLASS_SYSCTL_PARENT,
213 };
214 
215 static int
216 devclass_sysctl_handler(SYSCTL_HANDLER_ARGS)
217 {
218 	devclass_t dc = (devclass_t)arg1;
219 	const char *value;
220 
221 	switch (arg2) {
222 	case DEVCLASS_SYSCTL_PARENT:
223 		value = dc->parent ? dc->parent->name : "";
224 		break;
225 	default:
226 		return (EINVAL);
227 	}
228 	return (SYSCTL_OUT_STR(req, value));
229 }
230 
231 static void
232 devclass_sysctl_init(devclass_t dc)
233 {
234 	if (dc->sysctl_tree != NULL)
235 		return;
236 	sysctl_ctx_init(&dc->sysctl_ctx);
237 	dc->sysctl_tree = SYSCTL_ADD_NODE(&dc->sysctl_ctx,
238 	    SYSCTL_STATIC_CHILDREN(_dev), OID_AUTO, dc->name,
239 	    CTLFLAG_RD | CTLFLAG_MPSAFE, NULL, "");
240 	SYSCTL_ADD_PROC(&dc->sysctl_ctx, SYSCTL_CHILDREN(dc->sysctl_tree),
241 	    OID_AUTO, "%parent",
242 	    CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
243 	    dc, DEVCLASS_SYSCTL_PARENT, devclass_sysctl_handler, "A",
244 	    "parent class");
245 }
246 
247 enum {
248 	DEVICE_SYSCTL_DESC,
249 	DEVICE_SYSCTL_DRIVER,
250 	DEVICE_SYSCTL_LOCATION,
251 	DEVICE_SYSCTL_PNPINFO,
252 	DEVICE_SYSCTL_PARENT,
253 };
254 
255 static int
256 device_sysctl_handler(SYSCTL_HANDLER_ARGS)
257 {
258 	struct sbuf sb;
259 	device_t dev = (device_t)arg1;
260 	int error;
261 
262 	sbuf_new_for_sysctl(&sb, NULL, 1024, req);
263 	sbuf_clear_flags(&sb, SBUF_INCLUDENUL);
264 	bus_topo_lock();
265 	switch (arg2) {
266 	case DEVICE_SYSCTL_DESC:
267 		sbuf_cat(&sb, dev->desc ? dev->desc : "");
268 		break;
269 	case DEVICE_SYSCTL_DRIVER:
270 		sbuf_cat(&sb, dev->driver ? dev->driver->name : "");
271 		break;
272 	case DEVICE_SYSCTL_LOCATION:
273 		bus_child_location(dev, &sb);
274 		break;
275 	case DEVICE_SYSCTL_PNPINFO:
276 		bus_child_pnpinfo(dev, &sb);
277 		break;
278 	case DEVICE_SYSCTL_PARENT:
279 		sbuf_cat(&sb, dev->parent ? dev->parent->nameunit : "");
280 		break;
281 	default:
282 		error = EINVAL;
283 		goto out;
284 	}
285 	error = sbuf_finish(&sb);
286 out:
287 	bus_topo_unlock();
288 	sbuf_delete(&sb);
289 	return (error);
290 }
291 
292 static void
293 device_sysctl_init(device_t dev)
294 {
295 	devclass_t dc = dev->devclass;
296 	int domain;
297 
298 	if (dev->sysctl_tree != NULL)
299 		return;
300 	devclass_sysctl_init(dc);
301 	sysctl_ctx_init(&dev->sysctl_ctx);
302 	dev->sysctl_tree = SYSCTL_ADD_NODE_WITH_LABEL(&dev->sysctl_ctx,
303 	    SYSCTL_CHILDREN(dc->sysctl_tree), OID_AUTO,
304 	    dev->nameunit + strlen(dc->name),
305 	    CTLFLAG_RD | CTLFLAG_MPSAFE, NULL, "", "device_index");
306 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
307 	    OID_AUTO, "%desc", CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
308 	    dev, DEVICE_SYSCTL_DESC, device_sysctl_handler, "A",
309 	    "device description");
310 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
311 	    OID_AUTO, "%driver",
312 	    CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
313 	    dev, DEVICE_SYSCTL_DRIVER, device_sysctl_handler, "A",
314 	    "device driver name");
315 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
316 	    OID_AUTO, "%location",
317 	    CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
318 	    dev, DEVICE_SYSCTL_LOCATION, device_sysctl_handler, "A",
319 	    "device location relative to parent");
320 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
321 	    OID_AUTO, "%pnpinfo",
322 	    CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
323 	    dev, DEVICE_SYSCTL_PNPINFO, device_sysctl_handler, "A",
324 	    "device identification");
325 	SYSCTL_ADD_PROC(&dev->sysctl_ctx, SYSCTL_CHILDREN(dev->sysctl_tree),
326 	    OID_AUTO, "%parent",
327 	    CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE,
328 	    dev, DEVICE_SYSCTL_PARENT, device_sysctl_handler, "A",
329 	    "parent device");
330 	if (bus_get_domain(dev, &domain) == 0)
331 		SYSCTL_ADD_INT(&dev->sysctl_ctx,
332 		    SYSCTL_CHILDREN(dev->sysctl_tree), OID_AUTO, "%domain",
333 		    CTLFLAG_RD | CTLFLAG_MPSAFE, NULL, domain, "NUMA domain");
334 }
335 
336 static void
337 device_sysctl_update(device_t dev)
338 {
339 	devclass_t dc = dev->devclass;
340 
341 	if (dev->sysctl_tree == NULL)
342 		return;
343 	sysctl_rename_oid(dev->sysctl_tree, dev->nameunit + strlen(dc->name));
344 }
345 
346 static void
347 device_sysctl_fini(device_t dev)
348 {
349 	if (dev->sysctl_tree == NULL)
350 		return;
351 	sysctl_ctx_free(&dev->sysctl_ctx);
352 	dev->sysctl_tree = NULL;
353 }
354 
355 static struct device_list bus_data_devices;
356 static int bus_data_generation = 1;
357 
358 static kobj_method_t null_methods[] = {
359 	KOBJMETHOD_END
360 };
361 
362 DEFINE_CLASS(null, null_methods, 0);
363 
364 void
365 bus_topo_assert(void)
366 {
367 
368 	GIANT_REQUIRED;
369 }
370 
371 struct mtx *
372 bus_topo_mtx(void)
373 {
374 
375 	return (&Giant);
376 }
377 
378 void
379 bus_topo_lock(void)
380 {
381 
382 	mtx_lock(bus_topo_mtx());
383 }
384 
385 void
386 bus_topo_unlock(void)
387 {
388 
389 	mtx_unlock(bus_topo_mtx());
390 }
391 
392 /*
393  * Bus pass implementation
394  */
395 
396 static driver_list_t passes = TAILQ_HEAD_INITIALIZER(passes);
397 int bus_current_pass = BUS_PASS_ROOT;
398 
399 /**
400  * @internal
401  * @brief Register the pass level of a new driver attachment
402  *
403  * Register a new driver attachment's pass level.  If no driver
404  * attachment with the same pass level has been added, then @p new
405  * will be added to the global passes list.
406  *
407  * @param new		the new driver attachment
408  */
409 static void
410 driver_register_pass(struct driverlink *new)
411 {
412 	struct driverlink *dl;
413 
414 	/* We only consider pass numbers during boot. */
415 	if (bus_current_pass == BUS_PASS_DEFAULT)
416 		return;
417 
418 	/*
419 	 * Walk the passes list.  If we already know about this pass
420 	 * then there is nothing to do.  If we don't, then insert this
421 	 * driver link into the list.
422 	 */
423 	TAILQ_FOREACH(dl, &passes, passlink) {
424 		if (dl->pass < new->pass)
425 			continue;
426 		if (dl->pass == new->pass)
427 			return;
428 		TAILQ_INSERT_BEFORE(dl, new, passlink);
429 		return;
430 	}
431 	TAILQ_INSERT_TAIL(&passes, new, passlink);
432 }
433 
434 /**
435  * @brief Raise the current bus pass
436  *
437  * Raise the current bus pass level to @p pass.  Call the BUS_NEW_PASS()
438  * method on the root bus to kick off a new device tree scan for each
439  * new pass level that has at least one driver.
440  */
441 void
442 bus_set_pass(int pass)
443 {
444 	struct driverlink *dl;
445 
446 	if (bus_current_pass > pass)
447 		panic("Attempt to lower bus pass level");
448 
449 	TAILQ_FOREACH(dl, &passes, passlink) {
450 		/* Skip pass values below the current pass level. */
451 		if (dl->pass <= bus_current_pass)
452 			continue;
453 
454 		/*
455 		 * Bail once we hit a driver with a pass level that is
456 		 * too high.
457 		 */
458 		if (dl->pass > pass)
459 			break;
460 
461 		/*
462 		 * Raise the pass level to the next level and rescan
463 		 * the tree.
464 		 */
465 		bus_current_pass = dl->pass;
466 		BUS_NEW_PASS(root_bus);
467 	}
468 
469 	/*
470 	 * If there isn't a driver registered for the requested pass,
471 	 * then bus_current_pass might still be less than 'pass'.  Set
472 	 * it to 'pass' in that case.
473 	 */
474 	if (bus_current_pass < pass)
475 		bus_current_pass = pass;
476 	KASSERT(bus_current_pass == pass, ("Failed to update bus pass level"));
477 }
478 
479 /*
480  * Devclass implementation
481  */
482 
483 static devclass_list_t devclasses = TAILQ_HEAD_INITIALIZER(devclasses);
484 
485 /**
486  * @internal
487  * @brief Find or create a device class
488  *
489  * If a device class with the name @p classname exists, return it,
490  * otherwise if @p create is non-zero create and return a new device
491  * class.
492  *
493  * If @p parentname is non-NULL, the parent of the devclass is set to
494  * the devclass of that name.
495  *
496  * @param classname	the devclass name to find or create
497  * @param parentname	the parent devclass name or @c NULL
498  * @param create	non-zero to create a devclass
499  */
500 static devclass_t
501 devclass_find_internal(const char *classname, const char *parentname,
502 		       int create)
503 {
504 	devclass_t dc;
505 
506 	PDEBUG(("looking for %s", classname));
507 	if (!classname)
508 		return (NULL);
509 
510 	TAILQ_FOREACH(dc, &devclasses, link) {
511 		if (!strcmp(dc->name, classname))
512 			break;
513 	}
514 
515 	if (create && !dc) {
516 		PDEBUG(("creating %s", classname));
517 		dc = malloc(sizeof(struct devclass) + strlen(classname) + 1,
518 		    M_BUS, M_NOWAIT | M_ZERO);
519 		if (!dc)
520 			return (NULL);
521 		dc->parent = NULL;
522 		dc->name = (char*) (dc + 1);
523 		strcpy(dc->name, classname);
524 		TAILQ_INIT(&dc->drivers);
525 		TAILQ_INSERT_TAIL(&devclasses, dc, link);
526 
527 		bus_data_generation_update();
528 	}
529 
530 	/*
531 	 * If a parent class is specified, then set that as our parent so
532 	 * that this devclass will support drivers for the parent class as
533 	 * well.  If the parent class has the same name don't do this though
534 	 * as it creates a cycle that can trigger an infinite loop in
535 	 * device_probe_child() if a device exists for which there is no
536 	 * suitable driver.
537 	 */
538 	if (parentname && dc && !dc->parent &&
539 	    strcmp(classname, parentname) != 0) {
540 		dc->parent = devclass_find_internal(parentname, NULL, TRUE);
541 		dc->parent->flags |= DC_HAS_CHILDREN;
542 	}
543 
544 	return (dc);
545 }
546 
547 /**
548  * @brief Create a device class
549  *
550  * If a device class with the name @p classname exists, return it,
551  * otherwise create and return a new device class.
552  *
553  * @param classname	the devclass name to find or create
554  */
555 devclass_t
556 devclass_create(const char *classname)
557 {
558 	return (devclass_find_internal(classname, NULL, TRUE));
559 }
560 
561 /**
562  * @brief Find a device class
563  *
564  * If a device class with the name @p classname exists, return it,
565  * otherwise return @c NULL.
566  *
567  * @param classname	the devclass name to find
568  */
569 devclass_t
570 devclass_find(const char *classname)
571 {
572 	return (devclass_find_internal(classname, NULL, FALSE));
573 }
574 
575 /**
576  * @brief Register that a device driver has been added to a devclass
577  *
578  * Register that a device driver has been added to a devclass.  This
579  * is called by devclass_add_driver to accomplish the recursive
580  * notification of all the children classes of dc, as well as dc.
581  * Each layer will have BUS_DRIVER_ADDED() called for all instances of
582  * the devclass.
583  *
584  * We do a full search here of the devclass list at each iteration
585  * level to save storing children-lists in the devclass structure.  If
586  * we ever move beyond a few dozen devices doing this, we may need to
587  * reevaluate...
588  *
589  * @param dc		the devclass to edit
590  * @param driver	the driver that was just added
591  */
592 static void
593 devclass_driver_added(devclass_t dc, driver_t *driver)
594 {
595 	devclass_t parent;
596 	int i;
597 
598 	/*
599 	 * Call BUS_DRIVER_ADDED for any existing buses in this class.
600 	 */
601 	for (i = 0; i < dc->maxunit; i++)
602 		if (dc->devices[i] && device_is_attached(dc->devices[i]))
603 			BUS_DRIVER_ADDED(dc->devices[i], driver);
604 
605 	/*
606 	 * Walk through the children classes.  Since we only keep a
607 	 * single parent pointer around, we walk the entire list of
608 	 * devclasses looking for children.  We set the
609 	 * DC_HAS_CHILDREN flag when a child devclass is created on
610 	 * the parent, so we only walk the list for those devclasses
611 	 * that have children.
612 	 */
613 	if (!(dc->flags & DC_HAS_CHILDREN))
614 		return;
615 	parent = dc;
616 	TAILQ_FOREACH(dc, &devclasses, link) {
617 		if (dc->parent == parent)
618 			devclass_driver_added(dc, driver);
619 	}
620 }
621 
622 static void
623 device_handle_nomatch(device_t dev)
624 {
625 	BUS_PROBE_NOMATCH(dev->parent, dev);
626 	EVENTHANDLER_DIRECT_INVOKE(device_nomatch, dev);
627 	dev->flags |= DF_DONENOMATCH;
628 }
629 
630 /**
631  * @brief Add a device driver to a device class
632  *
633  * Add a device driver to a devclass. This is normally called
634  * automatically by DRIVER_MODULE(). The BUS_DRIVER_ADDED() method of
635  * all devices in the devclass will be called to allow them to attempt
636  * to re-probe any unmatched children.
637  *
638  * @param dc		the devclass to edit
639  * @param driver	the driver to register
640  */
641 int
642 devclass_add_driver(devclass_t dc, driver_t *driver, int pass, devclass_t *dcp)
643 {
644 	driverlink_t dl;
645 	devclass_t child_dc;
646 	const char *parentname;
647 
648 	PDEBUG(("%s", DRIVERNAME(driver)));
649 
650 	/* Don't allow invalid pass values. */
651 	if (pass <= BUS_PASS_ROOT)
652 		return (EINVAL);
653 
654 	dl = malloc(sizeof *dl, M_BUS, M_NOWAIT|M_ZERO);
655 	if (!dl)
656 		return (ENOMEM);
657 
658 	/*
659 	 * Compile the driver's methods. Also increase the reference count
660 	 * so that the class doesn't get freed when the last instance
661 	 * goes. This means we can safely use static methods and avoids a
662 	 * double-free in devclass_delete_driver.
663 	 */
664 	kobj_class_compile((kobj_class_t) driver);
665 
666 	/*
667 	 * If the driver has any base classes, make the
668 	 * devclass inherit from the devclass of the driver's
669 	 * first base class. This will allow the system to
670 	 * search for drivers in both devclasses for children
671 	 * of a device using this driver.
672 	 */
673 	if (driver->baseclasses)
674 		parentname = driver->baseclasses[0]->name;
675 	else
676 		parentname = NULL;
677 	child_dc = devclass_find_internal(driver->name, parentname, TRUE);
678 	if (dcp != NULL)
679 		*dcp = child_dc;
680 
681 	dl->driver = driver;
682 	TAILQ_INSERT_TAIL(&dc->drivers, dl, link);
683 	driver->refs++;		/* XXX: kobj_mtx */
684 	dl->pass = pass;
685 	driver_register_pass(dl);
686 
687 	if (device_frozen) {
688 		dl->flags |= DL_DEFERRED_PROBE;
689 	} else {
690 		devclass_driver_added(dc, driver);
691 	}
692 	bus_data_generation_update();
693 	return (0);
694 }
695 
696 /**
697  * @brief Register that a device driver has been deleted from a devclass
698  *
699  * Register that a device driver has been removed from a devclass.
700  * This is called by devclass_delete_driver to accomplish the
701  * recursive notification of all the children classes of busclass, as
702  * well as busclass.  Each layer will attempt to detach the driver
703  * from any devices that are children of the bus's devclass.  The function
704  * will return an error if a device fails to detach.
705  *
706  * We do a full search here of the devclass list at each iteration
707  * level to save storing children-lists in the devclass structure.  If
708  * we ever move beyond a few dozen devices doing this, we may need to
709  * reevaluate...
710  *
711  * @param busclass	the devclass of the parent bus
712  * @param dc		the devclass of the driver being deleted
713  * @param driver	the driver being deleted
714  */
715 static int
716 devclass_driver_deleted(devclass_t busclass, devclass_t dc, driver_t *driver)
717 {
718 	devclass_t parent;
719 	device_t dev;
720 	int error, i;
721 
722 	/*
723 	 * Disassociate from any devices.  We iterate through all the
724 	 * devices in the devclass of the driver and detach any which are
725 	 * using the driver and which have a parent in the devclass which
726 	 * we are deleting from.
727 	 *
728 	 * Note that since a driver can be in multiple devclasses, we
729 	 * should not detach devices which are not children of devices in
730 	 * the affected devclass.
731 	 *
732 	 * If we're frozen, we don't generate NOMATCH events. Mark to
733 	 * generate later.
734 	 */
735 	for (i = 0; i < dc->maxunit; i++) {
736 		if (dc->devices[i]) {
737 			dev = dc->devices[i];
738 			if (dev->driver == driver && dev->parent &&
739 			    dev->parent->devclass == busclass) {
740 				if ((error = device_detach(dev)) != 0)
741 					return (error);
742 				if (device_frozen) {
743 					dev->flags &= ~DF_DONENOMATCH;
744 					dev->flags |= DF_NEEDNOMATCH;
745 				} else {
746 					device_handle_nomatch(dev);
747 				}
748 			}
749 		}
750 	}
751 
752 	/*
753 	 * Walk through the children classes.  Since we only keep a
754 	 * single parent pointer around, we walk the entire list of
755 	 * devclasses looking for children.  We set the
756 	 * DC_HAS_CHILDREN flag when a child devclass is created on
757 	 * the parent, so we only walk the list for those devclasses
758 	 * that have children.
759 	 */
760 	if (!(busclass->flags & DC_HAS_CHILDREN))
761 		return (0);
762 	parent = busclass;
763 	TAILQ_FOREACH(busclass, &devclasses, link) {
764 		if (busclass->parent == parent) {
765 			error = devclass_driver_deleted(busclass, dc, driver);
766 			if (error)
767 				return (error);
768 		}
769 	}
770 	return (0);
771 }
772 
773 /**
774  * @brief Delete a device driver from a device class
775  *
776  * Delete a device driver from a devclass. This is normally called
777  * automatically by DRIVER_MODULE().
778  *
779  * If the driver is currently attached to any devices,
780  * devclass_delete_driver() will first attempt to detach from each
781  * device. If one of the detach calls fails, the driver will not be
782  * deleted.
783  *
784  * @param dc		the devclass to edit
785  * @param driver	the driver to unregister
786  */
787 int
788 devclass_delete_driver(devclass_t busclass, driver_t *driver)
789 {
790 	devclass_t dc = devclass_find(driver->name);
791 	driverlink_t dl;
792 	int error;
793 
794 	PDEBUG(("%s from devclass %s", driver->name, DEVCLANAME(busclass)));
795 
796 	if (!dc)
797 		return (0);
798 
799 	/*
800 	 * Find the link structure in the bus' list of drivers.
801 	 */
802 	TAILQ_FOREACH(dl, &busclass->drivers, link) {
803 		if (dl->driver == driver)
804 			break;
805 	}
806 
807 	if (!dl) {
808 		PDEBUG(("%s not found in %s list", driver->name,
809 		    busclass->name));
810 		return (ENOENT);
811 	}
812 
813 	error = devclass_driver_deleted(busclass, dc, driver);
814 	if (error != 0)
815 		return (error);
816 
817 	TAILQ_REMOVE(&busclass->drivers, dl, link);
818 	free(dl, M_BUS);
819 
820 	/* XXX: kobj_mtx */
821 	driver->refs--;
822 	if (driver->refs == 0)
823 		kobj_class_free((kobj_class_t) driver);
824 
825 	bus_data_generation_update();
826 	return (0);
827 }
828 
829 /**
830  * @brief Quiesces a set of device drivers from a device class
831  *
832  * Quiesce a device driver from a devclass. This is normally called
833  * automatically by DRIVER_MODULE().
834  *
835  * If the driver is currently attached to any devices,
836  * devclass_quiesece_driver() will first attempt to quiesce each
837  * device.
838  *
839  * @param dc		the devclass to edit
840  * @param driver	the driver to unregister
841  */
842 static int
843 devclass_quiesce_driver(devclass_t busclass, driver_t *driver)
844 {
845 	devclass_t dc = devclass_find(driver->name);
846 	driverlink_t dl;
847 	device_t dev;
848 	int i;
849 	int error;
850 
851 	PDEBUG(("%s from devclass %s", driver->name, DEVCLANAME(busclass)));
852 
853 	if (!dc)
854 		return (0);
855 
856 	/*
857 	 * Find the link structure in the bus' list of drivers.
858 	 */
859 	TAILQ_FOREACH(dl, &busclass->drivers, link) {
860 		if (dl->driver == driver)
861 			break;
862 	}
863 
864 	if (!dl) {
865 		PDEBUG(("%s not found in %s list", driver->name,
866 		    busclass->name));
867 		return (ENOENT);
868 	}
869 
870 	/*
871 	 * Quiesce all devices.  We iterate through all the devices in
872 	 * the devclass of the driver and quiesce any which are using
873 	 * the driver and which have a parent in the devclass which we
874 	 * are quiescing.
875 	 *
876 	 * Note that since a driver can be in multiple devclasses, we
877 	 * should not quiesce devices which are not children of
878 	 * devices in the affected devclass.
879 	 */
880 	for (i = 0; i < dc->maxunit; i++) {
881 		if (dc->devices[i]) {
882 			dev = dc->devices[i];
883 			if (dev->driver == driver && dev->parent &&
884 			    dev->parent->devclass == busclass) {
885 				if ((error = device_quiesce(dev)) != 0)
886 					return (error);
887 			}
888 		}
889 	}
890 
891 	return (0);
892 }
893 
894 /**
895  * @internal
896  */
897 static driverlink_t
898 devclass_find_driver_internal(devclass_t dc, const char *classname)
899 {
900 	driverlink_t dl;
901 
902 	PDEBUG(("%s in devclass %s", classname, DEVCLANAME(dc)));
903 
904 	TAILQ_FOREACH(dl, &dc->drivers, link) {
905 		if (!strcmp(dl->driver->name, classname))
906 			return (dl);
907 	}
908 
909 	PDEBUG(("not found"));
910 	return (NULL);
911 }
912 
913 /**
914  * @brief Return the name of the devclass
915  */
916 const char *
917 devclass_get_name(devclass_t dc)
918 {
919 	return (dc->name);
920 }
921 
922 /**
923  * @brief Find a device given a unit number
924  *
925  * @param dc		the devclass to search
926  * @param unit		the unit number to search for
927  *
928  * @returns		the device with the given unit number or @c
929  *			NULL if there is no such device
930  */
931 device_t
932 devclass_get_device(devclass_t dc, int unit)
933 {
934 	if (dc == NULL || unit < 0 || unit >= dc->maxunit)
935 		return (NULL);
936 	return (dc->devices[unit]);
937 }
938 
939 /**
940  * @brief Find the softc field of a device given a unit number
941  *
942  * @param dc		the devclass to search
943  * @param unit		the unit number to search for
944  *
945  * @returns		the softc field of the device with the given
946  *			unit number or @c NULL if there is no such
947  *			device
948  */
949 void *
950 devclass_get_softc(devclass_t dc, int unit)
951 {
952 	device_t dev;
953 
954 	dev = devclass_get_device(dc, unit);
955 	if (!dev)
956 		return (NULL);
957 
958 	return (device_get_softc(dev));
959 }
960 
961 /**
962  * @brief Get a list of devices in the devclass
963  *
964  * An array containing a list of all the devices in the given devclass
965  * is allocated and returned in @p *devlistp. The number of devices
966  * in the array is returned in @p *devcountp. The caller should free
967  * the array using @c free(p, M_TEMP), even if @p *devcountp is 0.
968  *
969  * @param dc		the devclass to examine
970  * @param devlistp	points at location for array pointer return
971  *			value
972  * @param devcountp	points at location for array size return value
973  *
974  * @retval 0		success
975  * @retval ENOMEM	the array allocation failed
976  */
977 int
978 devclass_get_devices(devclass_t dc, device_t **devlistp, int *devcountp)
979 {
980 	int count, i;
981 	device_t *list;
982 
983 	count = devclass_get_count(dc);
984 	list = malloc(count * sizeof(device_t), M_TEMP, M_NOWAIT|M_ZERO);
985 	if (!list)
986 		return (ENOMEM);
987 
988 	count = 0;
989 	for (i = 0; i < dc->maxunit; i++) {
990 		if (dc->devices[i]) {
991 			list[count] = dc->devices[i];
992 			count++;
993 		}
994 	}
995 
996 	*devlistp = list;
997 	*devcountp = count;
998 
999 	return (0);
1000 }
1001 
1002 /**
1003  * @brief Get a list of drivers in the devclass
1004  *
1005  * An array containing a list of pointers to all the drivers in the
1006  * given devclass is allocated and returned in @p *listp.  The number
1007  * of drivers in the array is returned in @p *countp. The caller should
1008  * free the array using @c free(p, M_TEMP).
1009  *
1010  * @param dc		the devclass to examine
1011  * @param listp		gives location for array pointer return value
1012  * @param countp	gives location for number of array elements
1013  *			return value
1014  *
1015  * @retval 0		success
1016  * @retval ENOMEM	the array allocation failed
1017  */
1018 int
1019 devclass_get_drivers(devclass_t dc, driver_t ***listp, int *countp)
1020 {
1021 	driverlink_t dl;
1022 	driver_t **list;
1023 	int count;
1024 
1025 	count = 0;
1026 	TAILQ_FOREACH(dl, &dc->drivers, link)
1027 		count++;
1028 	list = malloc(count * sizeof(driver_t *), M_TEMP, M_NOWAIT);
1029 	if (list == NULL)
1030 		return (ENOMEM);
1031 
1032 	count = 0;
1033 	TAILQ_FOREACH(dl, &dc->drivers, link) {
1034 		list[count] = dl->driver;
1035 		count++;
1036 	}
1037 	*listp = list;
1038 	*countp = count;
1039 
1040 	return (0);
1041 }
1042 
1043 /**
1044  * @brief Get the number of devices in a devclass
1045  *
1046  * @param dc		the devclass to examine
1047  */
1048 int
1049 devclass_get_count(devclass_t dc)
1050 {
1051 	int count, i;
1052 
1053 	count = 0;
1054 	for (i = 0; i < dc->maxunit; i++)
1055 		if (dc->devices[i])
1056 			count++;
1057 	return (count);
1058 }
1059 
1060 /**
1061  * @brief Get the maximum unit number used in a devclass
1062  *
1063  * Note that this is one greater than the highest currently-allocated
1064  * unit.  If a null devclass_t is passed in, -1 is returned to indicate
1065  * that not even the devclass has been allocated yet.
1066  *
1067  * @param dc		the devclass to examine
1068  */
1069 int
1070 devclass_get_maxunit(devclass_t dc)
1071 {
1072 	if (dc == NULL)
1073 		return (-1);
1074 	return (dc->maxunit);
1075 }
1076 
1077 /**
1078  * @brief Find a free unit number in a devclass
1079  *
1080  * This function searches for the first unused unit number greater
1081  * that or equal to @p unit.
1082  *
1083  * @param dc		the devclass to examine
1084  * @param unit		the first unit number to check
1085  */
1086 int
1087 devclass_find_free_unit(devclass_t dc, int unit)
1088 {
1089 	if (dc == NULL)
1090 		return (unit);
1091 	while (unit < dc->maxunit && dc->devices[unit] != NULL)
1092 		unit++;
1093 	return (unit);
1094 }
1095 
1096 /**
1097  * @brief Set the parent of a devclass
1098  *
1099  * The parent class is normally initialised automatically by
1100  * DRIVER_MODULE().
1101  *
1102  * @param dc		the devclass to edit
1103  * @param pdc		the new parent devclass
1104  */
1105 void
1106 devclass_set_parent(devclass_t dc, devclass_t pdc)
1107 {
1108 	dc->parent = pdc;
1109 }
1110 
1111 /**
1112  * @brief Get the parent of a devclass
1113  *
1114  * @param dc		the devclass to examine
1115  */
1116 devclass_t
1117 devclass_get_parent(devclass_t dc)
1118 {
1119 	return (dc->parent);
1120 }
1121 
1122 struct sysctl_ctx_list *
1123 devclass_get_sysctl_ctx(devclass_t dc)
1124 {
1125 	return (&dc->sysctl_ctx);
1126 }
1127 
1128 struct sysctl_oid *
1129 devclass_get_sysctl_tree(devclass_t dc)
1130 {
1131 	return (dc->sysctl_tree);
1132 }
1133 
1134 /**
1135  * @internal
1136  * @brief Allocate a unit number
1137  *
1138  * On entry, @p *unitp is the desired unit number (or @c -1 if any
1139  * will do). The allocated unit number is returned in @p *unitp.
1140 
1141  * @param dc		the devclass to allocate from
1142  * @param unitp		points at the location for the allocated unit
1143  *			number
1144  *
1145  * @retval 0		success
1146  * @retval EEXIST	the requested unit number is already allocated
1147  * @retval ENOMEM	memory allocation failure
1148  */
1149 static int
1150 devclass_alloc_unit(devclass_t dc, device_t dev, int *unitp)
1151 {
1152 	const char *s;
1153 	int unit = *unitp;
1154 
1155 	PDEBUG(("unit %d in devclass %s", unit, DEVCLANAME(dc)));
1156 
1157 	/* Ask the parent bus if it wants to wire this device. */
1158 	if (unit == -1)
1159 		BUS_HINT_DEVICE_UNIT(device_get_parent(dev), dev, dc->name,
1160 		    &unit);
1161 
1162 	/* If we were given a wired unit number, check for existing device */
1163 	/* XXX imp XXX */
1164 	if (unit != -1) {
1165 		if (unit >= 0 && unit < dc->maxunit &&
1166 		    dc->devices[unit] != NULL) {
1167 			if (bootverbose)
1168 				printf("%s: %s%d already exists; skipping it\n",
1169 				    dc->name, dc->name, *unitp);
1170 			return (EEXIST);
1171 		}
1172 	} else {
1173 		/* Unwired device, find the next available slot for it */
1174 		unit = 0;
1175 		for (unit = 0;; unit++) {
1176 			/* If this device slot is already in use, skip it. */
1177 			if (unit < dc->maxunit && dc->devices[unit] != NULL)
1178 				continue;
1179 
1180 			/* If there is an "at" hint for a unit then skip it. */
1181 			if (resource_string_value(dc->name, unit, "at", &s) ==
1182 			    0)
1183 				continue;
1184 
1185 			break;
1186 		}
1187 	}
1188 
1189 	/*
1190 	 * We've selected a unit beyond the length of the table, so let's
1191 	 * extend the table to make room for all units up to and including
1192 	 * this one.
1193 	 */
1194 	if (unit >= dc->maxunit) {
1195 		device_t *newlist, *oldlist;
1196 		int newsize;
1197 
1198 		oldlist = dc->devices;
1199 		newsize = roundup((unit + 1),
1200 		    MAX(1, MINALLOCSIZE / sizeof(device_t)));
1201 		newlist = malloc(sizeof(device_t) * newsize, M_BUS, M_NOWAIT);
1202 		if (!newlist)
1203 			return (ENOMEM);
1204 		if (oldlist != NULL)
1205 			bcopy(oldlist, newlist, sizeof(device_t) * dc->maxunit);
1206 		bzero(newlist + dc->maxunit,
1207 		    sizeof(device_t) * (newsize - dc->maxunit));
1208 		dc->devices = newlist;
1209 		dc->maxunit = newsize;
1210 		if (oldlist != NULL)
1211 			free(oldlist, M_BUS);
1212 	}
1213 	PDEBUG(("now: unit %d in devclass %s", unit, DEVCLANAME(dc)));
1214 
1215 	*unitp = unit;
1216 	return (0);
1217 }
1218 
1219 /**
1220  * @internal
1221  * @brief Add a device to a devclass
1222  *
1223  * A unit number is allocated for the device (using the device's
1224  * preferred unit number if any) and the device is registered in the
1225  * devclass. This allows the device to be looked up by its unit
1226  * number, e.g. by decoding a dev_t minor number.
1227  *
1228  * @param dc		the devclass to add to
1229  * @param dev		the device to add
1230  *
1231  * @retval 0		success
1232  * @retval EEXIST	the requested unit number is already allocated
1233  * @retval ENOMEM	memory allocation failure
1234  */
1235 static int
1236 devclass_add_device(devclass_t dc, device_t dev)
1237 {
1238 	int buflen, error;
1239 
1240 	PDEBUG(("%s in devclass %s", DEVICENAME(dev), DEVCLANAME(dc)));
1241 
1242 	buflen = snprintf(NULL, 0, "%s%d$", dc->name, INT_MAX);
1243 	if (buflen < 0)
1244 		return (ENOMEM);
1245 	dev->nameunit = malloc(buflen, M_BUS, M_NOWAIT|M_ZERO);
1246 	if (!dev->nameunit)
1247 		return (ENOMEM);
1248 
1249 	if ((error = devclass_alloc_unit(dc, dev, &dev->unit)) != 0) {
1250 		free(dev->nameunit, M_BUS);
1251 		dev->nameunit = NULL;
1252 		return (error);
1253 	}
1254 	dc->devices[dev->unit] = dev;
1255 	dev->devclass = dc;
1256 	snprintf(dev->nameunit, buflen, "%s%d", dc->name, dev->unit);
1257 
1258 	return (0);
1259 }
1260 
1261 /**
1262  * @internal
1263  * @brief Delete a device from a devclass
1264  *
1265  * The device is removed from the devclass's device list and its unit
1266  * number is freed.
1267 
1268  * @param dc		the devclass to delete from
1269  * @param dev		the device to delete
1270  *
1271  * @retval 0		success
1272  */
1273 static int
1274 devclass_delete_device(devclass_t dc, device_t dev)
1275 {
1276 	if (!dc || !dev)
1277 		return (0);
1278 
1279 	PDEBUG(("%s in devclass %s", DEVICENAME(dev), DEVCLANAME(dc)));
1280 
1281 	if (dev->devclass != dc || dc->devices[dev->unit] != dev)
1282 		panic("devclass_delete_device: inconsistent device class");
1283 	dc->devices[dev->unit] = NULL;
1284 	if (dev->flags & DF_WILDCARD)
1285 		dev->unit = -1;
1286 	dev->devclass = NULL;
1287 	free(dev->nameunit, M_BUS);
1288 	dev->nameunit = NULL;
1289 
1290 	return (0);
1291 }
1292 
1293 /**
1294  * @internal
1295  * @brief Make a new device and add it as a child of @p parent
1296  *
1297  * @param parent	the parent of the new device
1298  * @param name		the devclass name of the new device or @c NULL
1299  *			to leave the devclass unspecified
1300  * @parem unit		the unit number of the new device of @c -1 to
1301  *			leave the unit number unspecified
1302  *
1303  * @returns the new device
1304  */
1305 static device_t
1306 make_device(device_t parent, const char *name, int unit)
1307 {
1308 	device_t dev;
1309 	devclass_t dc;
1310 
1311 	PDEBUG(("%s at %s as unit %d", name, DEVICENAME(parent), unit));
1312 
1313 	if (name) {
1314 		dc = devclass_find_internal(name, NULL, TRUE);
1315 		if (!dc) {
1316 			printf("make_device: can't find device class %s\n",
1317 			    name);
1318 			return (NULL);
1319 		}
1320 	} else {
1321 		dc = NULL;
1322 	}
1323 
1324 	dev = malloc(sizeof(*dev), M_BUS, M_NOWAIT|M_ZERO);
1325 	if (!dev)
1326 		return (NULL);
1327 
1328 	dev->parent = parent;
1329 	TAILQ_INIT(&dev->children);
1330 	kobj_init((kobj_t) dev, &null_class);
1331 	dev->driver = NULL;
1332 	dev->devclass = NULL;
1333 	dev->unit = unit;
1334 	dev->nameunit = NULL;
1335 	dev->desc = NULL;
1336 	dev->busy = 0;
1337 	dev->devflags = 0;
1338 	dev->flags = DF_ENABLED;
1339 	dev->order = 0;
1340 	if (unit == -1)
1341 		dev->flags |= DF_WILDCARD;
1342 	if (name) {
1343 		dev->flags |= DF_FIXEDCLASS;
1344 		if (devclass_add_device(dc, dev)) {
1345 			kobj_delete((kobj_t) dev, M_BUS);
1346 			return (NULL);
1347 		}
1348 	}
1349 	if (parent != NULL && device_has_quiet_children(parent))
1350 		dev->flags |= DF_QUIET | DF_QUIET_CHILDREN;
1351 	dev->ivars = NULL;
1352 	dev->softc = NULL;
1353 
1354 	dev->state = DS_NOTPRESENT;
1355 
1356 	TAILQ_INSERT_TAIL(&bus_data_devices, dev, devlink);
1357 	bus_data_generation_update();
1358 
1359 	return (dev);
1360 }
1361 
1362 /**
1363  * @internal
1364  * @brief Print a description of a device.
1365  */
1366 static int
1367 device_print_child(device_t dev, device_t child)
1368 {
1369 	int retval = 0;
1370 
1371 	if (device_is_alive(child))
1372 		retval += BUS_PRINT_CHILD(dev, child);
1373 	else
1374 		retval += device_printf(child, " not found\n");
1375 
1376 	return (retval);
1377 }
1378 
1379 /**
1380  * @brief Create a new device
1381  *
1382  * This creates a new device and adds it as a child of an existing
1383  * parent device. The new device will be added after the last existing
1384  * child with order zero.
1385  *
1386  * @param dev		the device which will be the parent of the
1387  *			new child device
1388  * @param name		devclass name for new device or @c NULL if not
1389  *			specified
1390  * @param unit		unit number for new device or @c -1 if not
1391  *			specified
1392  *
1393  * @returns		the new device
1394  */
1395 device_t
1396 device_add_child(device_t dev, const char *name, int unit)
1397 {
1398 	return (device_add_child_ordered(dev, 0, name, unit));
1399 }
1400 
1401 /**
1402  * @brief Create a new device
1403  *
1404  * This creates a new device and adds it as a child of an existing
1405  * parent device. The new device will be added after the last existing
1406  * child with the same order.
1407  *
1408  * @param dev		the device which will be the parent of the
1409  *			new child device
1410  * @param order		a value which is used to partially sort the
1411  *			children of @p dev - devices created using
1412  *			lower values of @p order appear first in @p
1413  *			dev's list of children
1414  * @param name		devclass name for new device or @c NULL if not
1415  *			specified
1416  * @param unit		unit number for new device or @c -1 if not
1417  *			specified
1418  *
1419  * @returns		the new device
1420  */
1421 device_t
1422 device_add_child_ordered(device_t dev, u_int order, const char *name, int unit)
1423 {
1424 	device_t child;
1425 	device_t place;
1426 
1427 	PDEBUG(("%s at %s with order %u as unit %d",
1428 	    name, DEVICENAME(dev), order, unit));
1429 	KASSERT(name != NULL || unit == -1,
1430 	    ("child device with wildcard name and specific unit number"));
1431 
1432 	child = make_device(dev, name, unit);
1433 	if (child == NULL)
1434 		return (child);
1435 	child->order = order;
1436 
1437 	TAILQ_FOREACH(place, &dev->children, link) {
1438 		if (place->order > order)
1439 			break;
1440 	}
1441 
1442 	if (place) {
1443 		/*
1444 		 * The device 'place' is the first device whose order is
1445 		 * greater than the new child.
1446 		 */
1447 		TAILQ_INSERT_BEFORE(place, child, link);
1448 	} else {
1449 		/*
1450 		 * The new child's order is greater or equal to the order of
1451 		 * any existing device. Add the child to the tail of the list.
1452 		 */
1453 		TAILQ_INSERT_TAIL(&dev->children, child, link);
1454 	}
1455 
1456 	bus_data_generation_update();
1457 	return (child);
1458 }
1459 
1460 /**
1461  * @brief Delete a device
1462  *
1463  * This function deletes a device along with all of its children. If
1464  * the device currently has a driver attached to it, the device is
1465  * detached first using device_detach().
1466  *
1467  * @param dev		the parent device
1468  * @param child		the device to delete
1469  *
1470  * @retval 0		success
1471  * @retval non-zero	a unit error code describing the error
1472  */
1473 int
1474 device_delete_child(device_t dev, device_t child)
1475 {
1476 	int error;
1477 	device_t grandchild;
1478 
1479 	PDEBUG(("%s from %s", DEVICENAME(child), DEVICENAME(dev)));
1480 
1481 	/* detach parent before deleting children, if any */
1482 	if ((error = device_detach(child)) != 0)
1483 		return (error);
1484 
1485 	/* remove children second */
1486 	while ((grandchild = TAILQ_FIRST(&child->children)) != NULL) {
1487 		error = device_delete_child(child, grandchild);
1488 		if (error)
1489 			return (error);
1490 	}
1491 
1492 	if (child->devclass)
1493 		devclass_delete_device(child->devclass, child);
1494 	if (child->parent)
1495 		BUS_CHILD_DELETED(dev, child);
1496 	TAILQ_REMOVE(&dev->children, child, link);
1497 	TAILQ_REMOVE(&bus_data_devices, child, devlink);
1498 	kobj_delete((kobj_t) child, M_BUS);
1499 
1500 	bus_data_generation_update();
1501 	return (0);
1502 }
1503 
1504 /**
1505  * @brief Delete all children devices of the given device, if any.
1506  *
1507  * This function deletes all children devices of the given device, if
1508  * any, using the device_delete_child() function for each device it
1509  * finds. If a child device cannot be deleted, this function will
1510  * return an error code.
1511  *
1512  * @param dev		the parent device
1513  *
1514  * @retval 0		success
1515  * @retval non-zero	a device would not detach
1516  */
1517 int
1518 device_delete_children(device_t dev)
1519 {
1520 	device_t child;
1521 	int error;
1522 
1523 	PDEBUG(("Deleting all children of %s", DEVICENAME(dev)));
1524 
1525 	error = 0;
1526 
1527 	while ((child = TAILQ_FIRST(&dev->children)) != NULL) {
1528 		error = device_delete_child(dev, child);
1529 		if (error) {
1530 			PDEBUG(("Failed deleting %s", DEVICENAME(child)));
1531 			break;
1532 		}
1533 	}
1534 	return (error);
1535 }
1536 
1537 /**
1538  * @brief Find a device given a unit number
1539  *
1540  * This is similar to devclass_get_devices() but only searches for
1541  * devices which have @p dev as a parent.
1542  *
1543  * @param dev		the parent device to search
1544  * @param unit		the unit number to search for.  If the unit is -1,
1545  *			return the first child of @p dev which has name
1546  *			@p classname (that is, the one with the lowest unit.)
1547  *
1548  * @returns		the device with the given unit number or @c
1549  *			NULL if there is no such device
1550  */
1551 device_t
1552 device_find_child(device_t dev, const char *classname, int unit)
1553 {
1554 	devclass_t dc;
1555 	device_t child;
1556 
1557 	dc = devclass_find(classname);
1558 	if (!dc)
1559 		return (NULL);
1560 
1561 	if (unit != -1) {
1562 		child = devclass_get_device(dc, unit);
1563 		if (child && child->parent == dev)
1564 			return (child);
1565 	} else {
1566 		for (unit = 0; unit < devclass_get_maxunit(dc); unit++) {
1567 			child = devclass_get_device(dc, unit);
1568 			if (child && child->parent == dev)
1569 				return (child);
1570 		}
1571 	}
1572 	return (NULL);
1573 }
1574 
1575 /**
1576  * @internal
1577  */
1578 static driverlink_t
1579 first_matching_driver(devclass_t dc, device_t dev)
1580 {
1581 	if (dev->devclass)
1582 		return (devclass_find_driver_internal(dc, dev->devclass->name));
1583 	return (TAILQ_FIRST(&dc->drivers));
1584 }
1585 
1586 /**
1587  * @internal
1588  */
1589 static driverlink_t
1590 next_matching_driver(devclass_t dc, device_t dev, driverlink_t last)
1591 {
1592 	if (dev->devclass) {
1593 		driverlink_t dl;
1594 		for (dl = TAILQ_NEXT(last, link); dl; dl = TAILQ_NEXT(dl, link))
1595 			if (!strcmp(dev->devclass->name, dl->driver->name))
1596 				return (dl);
1597 		return (NULL);
1598 	}
1599 	return (TAILQ_NEXT(last, link));
1600 }
1601 
1602 /**
1603  * @internal
1604  */
1605 int
1606 device_probe_child(device_t dev, device_t child)
1607 {
1608 	devclass_t dc;
1609 	driverlink_t best = NULL;
1610 	driverlink_t dl;
1611 	int result, pri = 0;
1612 	/* We should preserve the devclass (or lack of) set by the bus. */
1613 	int hasclass = (child->devclass != NULL);
1614 
1615 	bus_topo_assert();
1616 
1617 	dc = dev->devclass;
1618 	if (!dc)
1619 		panic("device_probe_child: parent device has no devclass");
1620 
1621 	/*
1622 	 * If the state is already probed, then return.
1623 	 */
1624 	if (child->state == DS_ALIVE)
1625 		return (0);
1626 
1627 	for (; dc; dc = dc->parent) {
1628 		for (dl = first_matching_driver(dc, child);
1629 		     dl;
1630 		     dl = next_matching_driver(dc, child, dl)) {
1631 			/* If this driver's pass is too high, then ignore it. */
1632 			if (dl->pass > bus_current_pass)
1633 				continue;
1634 
1635 			PDEBUG(("Trying %s", DRIVERNAME(dl->driver)));
1636 			result = device_set_driver(child, dl->driver);
1637 			if (result == ENOMEM)
1638 				return (result);
1639 			else if (result != 0)
1640 				continue;
1641 			if (!hasclass) {
1642 				if (device_set_devclass(child,
1643 				    dl->driver->name) != 0) {
1644 					char const * devname =
1645 					    device_get_name(child);
1646 					if (devname == NULL)
1647 						devname = "(unknown)";
1648 					printf("driver bug: Unable to set "
1649 					    "devclass (class: %s "
1650 					    "devname: %s)\n",
1651 					    dl->driver->name,
1652 					    devname);
1653 					(void)device_set_driver(child, NULL);
1654 					continue;
1655 				}
1656 			}
1657 
1658 			/* Fetch any flags for the device before probing. */
1659 			resource_int_value(dl->driver->name, child->unit,
1660 			    "flags", &child->devflags);
1661 
1662 			result = DEVICE_PROBE(child);
1663 
1664 			/*
1665 			 * If the driver returns SUCCESS, there can be
1666 			 * no higher match for this device.
1667 			 */
1668 			if (result == 0) {
1669 				best = dl;
1670 				pri = 0;
1671 				break;
1672 			}
1673 
1674 			/* Reset flags and devclass before the next probe. */
1675 			child->devflags = 0;
1676 			if (!hasclass)
1677 				(void)device_set_devclass(child, NULL);
1678 
1679 			/*
1680 			 * Reset DF_QUIET in case this driver doesn't
1681 			 * end up as the best driver.
1682 			 */
1683 			device_verbose(child);
1684 
1685 			/*
1686 			 * Probes that return BUS_PROBE_NOWILDCARD or lower
1687 			 * only match on devices whose driver was explicitly
1688 			 * specified.
1689 			 */
1690 			if (result <= BUS_PROBE_NOWILDCARD &&
1691 			    !(child->flags & DF_FIXEDCLASS)) {
1692 				result = ENXIO;
1693 			}
1694 
1695 			/*
1696 			 * The driver returned an error so it
1697 			 * certainly doesn't match.
1698 			 */
1699 			if (result > 0) {
1700 				(void)device_set_driver(child, NULL);
1701 				continue;
1702 			}
1703 
1704 			/*
1705 			 * A priority lower than SUCCESS, remember the
1706 			 * best matching driver. Initialise the value
1707 			 * of pri for the first match.
1708 			 */
1709 			if (best == NULL || result > pri) {
1710 				best = dl;
1711 				pri = result;
1712 				continue;
1713 			}
1714 		}
1715 		/*
1716 		 * If we have an unambiguous match in this devclass,
1717 		 * don't look in the parent.
1718 		 */
1719 		if (best && pri == 0)
1720 			break;
1721 	}
1722 
1723 	if (best == NULL)
1724 		return (ENXIO);
1725 
1726 	/*
1727 	 * If we found a driver, change state and initialise the devclass.
1728 	 */
1729 	if (pri < 0) {
1730 		/* Set the winning driver, devclass, and flags. */
1731 		result = device_set_driver(child, best->driver);
1732 		if (result != 0)
1733 			return (result);
1734 		if (!child->devclass) {
1735 			result = device_set_devclass(child, best->driver->name);
1736 			if (result != 0) {
1737 				(void)device_set_driver(child, NULL);
1738 				return (result);
1739 			}
1740 		}
1741 		resource_int_value(best->driver->name, child->unit,
1742 		    "flags", &child->devflags);
1743 
1744 		/*
1745 		 * A bit bogus. Call the probe method again to make sure
1746 		 * that we have the right description.
1747 		 */
1748 		result = DEVICE_PROBE(child);
1749 		if (result > 0) {
1750 			if (!hasclass)
1751 				(void)device_set_devclass(child, NULL);
1752 			(void)device_set_driver(child, NULL);
1753 			return (result);
1754 		}
1755 	}
1756 
1757 	child->state = DS_ALIVE;
1758 	bus_data_generation_update();
1759 	return (0);
1760 }
1761 
1762 /**
1763  * @brief Return the parent of a device
1764  */
1765 device_t
1766 device_get_parent(device_t dev)
1767 {
1768 	return (dev->parent);
1769 }
1770 
1771 /**
1772  * @brief Get a list of children of a device
1773  *
1774  * An array containing a list of all the children of the given device
1775  * is allocated and returned in @p *devlistp. The number of devices
1776  * in the array is returned in @p *devcountp. The caller should free
1777  * the array using @c free(p, M_TEMP).
1778  *
1779  * @param dev		the device to examine
1780  * @param devlistp	points at location for array pointer return
1781  *			value
1782  * @param devcountp	points at location for array size return value
1783  *
1784  * @retval 0		success
1785  * @retval ENOMEM	the array allocation failed
1786  */
1787 int
1788 device_get_children(device_t dev, device_t **devlistp, int *devcountp)
1789 {
1790 	int count;
1791 	device_t child;
1792 	device_t *list;
1793 
1794 	count = 0;
1795 	TAILQ_FOREACH(child, &dev->children, link) {
1796 		count++;
1797 	}
1798 	if (count == 0) {
1799 		*devlistp = NULL;
1800 		*devcountp = 0;
1801 		return (0);
1802 	}
1803 
1804 	list = malloc(count * sizeof(device_t), M_TEMP, M_NOWAIT|M_ZERO);
1805 	if (!list)
1806 		return (ENOMEM);
1807 
1808 	count = 0;
1809 	TAILQ_FOREACH(child, &dev->children, link) {
1810 		list[count] = child;
1811 		count++;
1812 	}
1813 
1814 	*devlistp = list;
1815 	*devcountp = count;
1816 
1817 	return (0);
1818 }
1819 
1820 /**
1821  * @brief Return the current driver for the device or @c NULL if there
1822  * is no driver currently attached
1823  */
1824 driver_t *
1825 device_get_driver(device_t dev)
1826 {
1827 	return (dev->driver);
1828 }
1829 
1830 /**
1831  * @brief Return the current devclass for the device or @c NULL if
1832  * there is none.
1833  */
1834 devclass_t
1835 device_get_devclass(device_t dev)
1836 {
1837 	return (dev->devclass);
1838 }
1839 
1840 /**
1841  * @brief Return the name of the device's devclass or @c NULL if there
1842  * is none.
1843  */
1844 const char *
1845 device_get_name(device_t dev)
1846 {
1847 	if (dev != NULL && dev->devclass)
1848 		return (devclass_get_name(dev->devclass));
1849 	return (NULL);
1850 }
1851 
1852 /**
1853  * @brief Return a string containing the device's devclass name
1854  * followed by an ascii representation of the device's unit number
1855  * (e.g. @c "foo2").
1856  */
1857 const char *
1858 device_get_nameunit(device_t dev)
1859 {
1860 	return (dev->nameunit);
1861 }
1862 
1863 /**
1864  * @brief Return the device's unit number.
1865  */
1866 int
1867 device_get_unit(device_t dev)
1868 {
1869 	return (dev->unit);
1870 }
1871 
1872 /**
1873  * @brief Return the device's description string
1874  */
1875 const char *
1876 device_get_desc(device_t dev)
1877 {
1878 	return (dev->desc);
1879 }
1880 
1881 /**
1882  * @brief Return the device's flags
1883  */
1884 uint32_t
1885 device_get_flags(device_t dev)
1886 {
1887 	return (dev->devflags);
1888 }
1889 
1890 struct sysctl_ctx_list *
1891 device_get_sysctl_ctx(device_t dev)
1892 {
1893 	return (&dev->sysctl_ctx);
1894 }
1895 
1896 struct sysctl_oid *
1897 device_get_sysctl_tree(device_t dev)
1898 {
1899 	return (dev->sysctl_tree);
1900 }
1901 
1902 /**
1903  * @brief Print the name of the device followed by a colon and a space
1904  *
1905  * @returns the number of characters printed
1906  */
1907 int
1908 device_print_prettyname(device_t dev)
1909 {
1910 	const char *name = device_get_name(dev);
1911 
1912 	if (name == NULL)
1913 		return (printf("unknown: "));
1914 	return (printf("%s%d: ", name, device_get_unit(dev)));
1915 }
1916 
1917 /**
1918  * @brief Print the name of the device followed by a colon, a space
1919  * and the result of calling vprintf() with the value of @p fmt and
1920  * the following arguments.
1921  *
1922  * @returns the number of characters printed
1923  */
1924 int
1925 device_printf(device_t dev, const char * fmt, ...)
1926 {
1927 	char buf[128];
1928 	struct sbuf sb;
1929 	const char *name;
1930 	va_list ap;
1931 	size_t retval;
1932 
1933 	retval = 0;
1934 
1935 	sbuf_new(&sb, buf, sizeof(buf), SBUF_FIXEDLEN);
1936 	sbuf_set_drain(&sb, sbuf_printf_drain, &retval);
1937 
1938 	name = device_get_name(dev);
1939 
1940 	if (name == NULL)
1941 		sbuf_cat(&sb, "unknown: ");
1942 	else
1943 		sbuf_printf(&sb, "%s%d: ", name, device_get_unit(dev));
1944 
1945 	va_start(ap, fmt);
1946 	sbuf_vprintf(&sb, fmt, ap);
1947 	va_end(ap);
1948 
1949 	sbuf_finish(&sb);
1950 	sbuf_delete(&sb);
1951 
1952 	return (retval);
1953 }
1954 
1955 /**
1956  * @brief Print the name of the device followed by a colon, a space
1957  * and the result of calling log() with the value of @p fmt and
1958  * the following arguments.
1959  *
1960  * @returns the number of characters printed
1961  */
1962 int
1963 device_log(device_t dev, int pri, const char * fmt, ...)
1964 {
1965 	char buf[128];
1966 	struct sbuf sb;
1967 	const char *name;
1968 	va_list ap;
1969 	size_t retval;
1970 
1971 	retval = 0;
1972 
1973 	sbuf_new(&sb, buf, sizeof(buf), SBUF_FIXEDLEN);
1974 
1975 	name = device_get_name(dev);
1976 
1977 	if (name == NULL)
1978 		sbuf_cat(&sb, "unknown: ");
1979 	else
1980 		sbuf_printf(&sb, "%s%d: ", name, device_get_unit(dev));
1981 
1982 	va_start(ap, fmt);
1983 	sbuf_vprintf(&sb, fmt, ap);
1984 	va_end(ap);
1985 
1986 	sbuf_finish(&sb);
1987 
1988 	log(pri, "%.*s", (int) sbuf_len(&sb), sbuf_data(&sb));
1989 	retval = sbuf_len(&sb);
1990 
1991 	sbuf_delete(&sb);
1992 
1993 	return (retval);
1994 }
1995 
1996 /**
1997  * @internal
1998  */
1999 static void
2000 device_set_desc_internal(device_t dev, const char* desc, int copy)
2001 {
2002 	if (dev->desc && (dev->flags & DF_DESCMALLOCED)) {
2003 		free(dev->desc, M_BUS);
2004 		dev->flags &= ~DF_DESCMALLOCED;
2005 		dev->desc = NULL;
2006 	}
2007 
2008 	if (copy && desc) {
2009 		dev->desc = malloc(strlen(desc) + 1, M_BUS, M_NOWAIT);
2010 		if (dev->desc) {
2011 			strcpy(dev->desc, desc);
2012 			dev->flags |= DF_DESCMALLOCED;
2013 		}
2014 	} else {
2015 		/* Avoid a -Wcast-qual warning */
2016 		dev->desc = (char *)(uintptr_t) desc;
2017 	}
2018 
2019 	bus_data_generation_update();
2020 }
2021 
2022 /**
2023  * @brief Set the device's description
2024  *
2025  * The value of @c desc should be a string constant that will not
2026  * change (at least until the description is changed in a subsequent
2027  * call to device_set_desc() or device_set_desc_copy()).
2028  */
2029 void
2030 device_set_desc(device_t dev, const char* desc)
2031 {
2032 	device_set_desc_internal(dev, desc, FALSE);
2033 }
2034 
2035 /**
2036  * @brief Set the device's description
2037  *
2038  * The string pointed to by @c desc is copied. Use this function if
2039  * the device description is generated, (e.g. with sprintf()).
2040  */
2041 void
2042 device_set_desc_copy(device_t dev, const char* desc)
2043 {
2044 	device_set_desc_internal(dev, desc, TRUE);
2045 }
2046 
2047 /**
2048  * @brief Set the device's flags
2049  */
2050 void
2051 device_set_flags(device_t dev, uint32_t flags)
2052 {
2053 	dev->devflags = flags;
2054 }
2055 
2056 /**
2057  * @brief Return the device's softc field
2058  *
2059  * The softc is allocated and zeroed when a driver is attached, based
2060  * on the size field of the driver.
2061  */
2062 void *
2063 device_get_softc(device_t dev)
2064 {
2065 	return (dev->softc);
2066 }
2067 
2068 /**
2069  * @brief Set the device's softc field
2070  *
2071  * Most drivers do not need to use this since the softc is allocated
2072  * automatically when the driver is attached.
2073  */
2074 void
2075 device_set_softc(device_t dev, void *softc)
2076 {
2077 	if (dev->softc && !(dev->flags & DF_EXTERNALSOFTC))
2078 		free(dev->softc, M_BUS_SC);
2079 	dev->softc = softc;
2080 	if (dev->softc)
2081 		dev->flags |= DF_EXTERNALSOFTC;
2082 	else
2083 		dev->flags &= ~DF_EXTERNALSOFTC;
2084 }
2085 
2086 /**
2087  * @brief Free claimed softc
2088  *
2089  * Most drivers do not need to use this since the softc is freed
2090  * automatically when the driver is detached.
2091  */
2092 void
2093 device_free_softc(void *softc)
2094 {
2095 	free(softc, M_BUS_SC);
2096 }
2097 
2098 /**
2099  * @brief Claim softc
2100  *
2101  * This function can be used to let the driver free the automatically
2102  * allocated softc using "device_free_softc()". This function is
2103  * useful when the driver is refcounting the softc and the softc
2104  * cannot be freed when the "device_detach" method is called.
2105  */
2106 void
2107 device_claim_softc(device_t dev)
2108 {
2109 	if (dev->softc)
2110 		dev->flags |= DF_EXTERNALSOFTC;
2111 	else
2112 		dev->flags &= ~DF_EXTERNALSOFTC;
2113 }
2114 
2115 /**
2116  * @brief Get the device's ivars field
2117  *
2118  * The ivars field is used by the parent device to store per-device
2119  * state (e.g. the physical location of the device or a list of
2120  * resources).
2121  */
2122 void *
2123 device_get_ivars(device_t dev)
2124 {
2125 	KASSERT(dev != NULL, ("device_get_ivars(NULL, ...)"));
2126 	return (dev->ivars);
2127 }
2128 
2129 /**
2130  * @brief Set the device's ivars field
2131  */
2132 void
2133 device_set_ivars(device_t dev, void * ivars)
2134 {
2135 	KASSERT(dev != NULL, ("device_set_ivars(NULL, ...)"));
2136 	dev->ivars = ivars;
2137 }
2138 
2139 /**
2140  * @brief Return the device's state
2141  */
2142 device_state_t
2143 device_get_state(device_t dev)
2144 {
2145 	return (dev->state);
2146 }
2147 
2148 /**
2149  * @brief Set the DF_ENABLED flag for the device
2150  */
2151 void
2152 device_enable(device_t dev)
2153 {
2154 	dev->flags |= DF_ENABLED;
2155 }
2156 
2157 /**
2158  * @brief Clear the DF_ENABLED flag for the device
2159  */
2160 void
2161 device_disable(device_t dev)
2162 {
2163 	dev->flags &= ~DF_ENABLED;
2164 }
2165 
2166 /**
2167  * @brief Increment the busy counter for the device
2168  */
2169 void
2170 device_busy(device_t dev)
2171 {
2172 
2173 	/*
2174 	 * Mark the device as busy, recursively up the tree if this busy count
2175 	 * goes 0->1.
2176 	 */
2177 	if (refcount_acquire(&dev->busy) == 0 && dev->parent != NULL)
2178 		device_busy(dev->parent);
2179 }
2180 
2181 /**
2182  * @brief Decrement the busy counter for the device
2183  */
2184 void
2185 device_unbusy(device_t dev)
2186 {
2187 
2188 	/*
2189 	 * Mark the device as unbsy, recursively if this is the last busy count.
2190 	 */
2191 	if (refcount_release(&dev->busy) && dev->parent != NULL)
2192 		device_unbusy(dev->parent);
2193 }
2194 
2195 /**
2196  * @brief Set the DF_QUIET flag for the device
2197  */
2198 void
2199 device_quiet(device_t dev)
2200 {
2201 	dev->flags |= DF_QUIET;
2202 }
2203 
2204 /**
2205  * @brief Set the DF_QUIET_CHILDREN flag for the device
2206  */
2207 void
2208 device_quiet_children(device_t dev)
2209 {
2210 	dev->flags |= DF_QUIET_CHILDREN;
2211 }
2212 
2213 /**
2214  * @brief Clear the DF_QUIET flag for the device
2215  */
2216 void
2217 device_verbose(device_t dev)
2218 {
2219 	dev->flags &= ~DF_QUIET;
2220 }
2221 
2222 ssize_t
2223 device_get_property(device_t dev, const char *prop, void *val, size_t sz,
2224     device_property_type_t type)
2225 {
2226 	device_t bus = device_get_parent(dev);
2227 
2228 	switch (type) {
2229 	case DEVICE_PROP_ANY:
2230 	case DEVICE_PROP_BUFFER:
2231 	case DEVICE_PROP_HANDLE:	/* Size checks done in implementation. */
2232 		break;
2233 	case DEVICE_PROP_UINT32:
2234 		if (sz % 4 != 0)
2235 			return (-1);
2236 		break;
2237 	case DEVICE_PROP_UINT64:
2238 		if (sz % 8 != 0)
2239 			return (-1);
2240 		break;
2241 	default:
2242 		return (-1);
2243 	}
2244 
2245 	return (BUS_GET_PROPERTY(bus, dev, prop, val, sz, type));
2246 }
2247 
2248 bool
2249 device_has_property(device_t dev, const char *prop)
2250 {
2251 	return (device_get_property(dev, prop, NULL, 0, DEVICE_PROP_ANY) >= 0);
2252 }
2253 
2254 /**
2255  * @brief Return non-zero if the DF_QUIET_CHIDLREN flag is set on the device
2256  */
2257 int
2258 device_has_quiet_children(device_t dev)
2259 {
2260 	return ((dev->flags & DF_QUIET_CHILDREN) != 0);
2261 }
2262 
2263 /**
2264  * @brief Return non-zero if the DF_QUIET flag is set on the device
2265  */
2266 int
2267 device_is_quiet(device_t dev)
2268 {
2269 	return ((dev->flags & DF_QUIET) != 0);
2270 }
2271 
2272 /**
2273  * @brief Return non-zero if the DF_ENABLED flag is set on the device
2274  */
2275 int
2276 device_is_enabled(device_t dev)
2277 {
2278 	return ((dev->flags & DF_ENABLED) != 0);
2279 }
2280 
2281 /**
2282  * @brief Return non-zero if the device was successfully probed
2283  */
2284 int
2285 device_is_alive(device_t dev)
2286 {
2287 	return (dev->state >= DS_ALIVE);
2288 }
2289 
2290 /**
2291  * @brief Return non-zero if the device currently has a driver
2292  * attached to it
2293  */
2294 int
2295 device_is_attached(device_t dev)
2296 {
2297 	return (dev->state >= DS_ATTACHED);
2298 }
2299 
2300 /**
2301  * @brief Return non-zero if the device is currently suspended.
2302  */
2303 int
2304 device_is_suspended(device_t dev)
2305 {
2306 	return ((dev->flags & DF_SUSPENDED) != 0);
2307 }
2308 
2309 /**
2310  * @brief Set the devclass of a device
2311  * @see devclass_add_device().
2312  */
2313 int
2314 device_set_devclass(device_t dev, const char *classname)
2315 {
2316 	devclass_t dc;
2317 	int error;
2318 
2319 	if (!classname) {
2320 		if (dev->devclass)
2321 			devclass_delete_device(dev->devclass, dev);
2322 		return (0);
2323 	}
2324 
2325 	if (dev->devclass) {
2326 		printf("device_set_devclass: device class already set\n");
2327 		return (EINVAL);
2328 	}
2329 
2330 	dc = devclass_find_internal(classname, NULL, TRUE);
2331 	if (!dc)
2332 		return (ENOMEM);
2333 
2334 	error = devclass_add_device(dc, dev);
2335 
2336 	bus_data_generation_update();
2337 	return (error);
2338 }
2339 
2340 /**
2341  * @brief Set the devclass of a device and mark the devclass fixed.
2342  * @see device_set_devclass()
2343  */
2344 int
2345 device_set_devclass_fixed(device_t dev, const char *classname)
2346 {
2347 	int error;
2348 
2349 	if (classname == NULL)
2350 		return (EINVAL);
2351 
2352 	error = device_set_devclass(dev, classname);
2353 	if (error)
2354 		return (error);
2355 	dev->flags |= DF_FIXEDCLASS;
2356 	return (0);
2357 }
2358 
2359 /**
2360  * @brief Query the device to determine if it's of a fixed devclass
2361  * @see device_set_devclass_fixed()
2362  */
2363 bool
2364 device_is_devclass_fixed(device_t dev)
2365 {
2366 	return ((dev->flags & DF_FIXEDCLASS) != 0);
2367 }
2368 
2369 /**
2370  * @brief Set the driver of a device
2371  *
2372  * @retval 0		success
2373  * @retval EBUSY	the device already has a driver attached
2374  * @retval ENOMEM	a memory allocation failure occurred
2375  */
2376 int
2377 device_set_driver(device_t dev, driver_t *driver)
2378 {
2379 	int domain;
2380 	struct domainset *policy;
2381 
2382 	if (dev->state >= DS_ATTACHED)
2383 		return (EBUSY);
2384 
2385 	if (dev->driver == driver)
2386 		return (0);
2387 
2388 	if (dev->softc && !(dev->flags & DF_EXTERNALSOFTC)) {
2389 		free(dev->softc, M_BUS_SC);
2390 		dev->softc = NULL;
2391 	}
2392 	device_set_desc(dev, NULL);
2393 	kobj_delete((kobj_t) dev, NULL);
2394 	dev->driver = driver;
2395 	if (driver) {
2396 		kobj_init((kobj_t) dev, (kobj_class_t) driver);
2397 		if (!(dev->flags & DF_EXTERNALSOFTC) && driver->size > 0) {
2398 			if (bus_get_domain(dev, &domain) == 0)
2399 				policy = DOMAINSET_PREF(domain);
2400 			else
2401 				policy = DOMAINSET_RR();
2402 			dev->softc = malloc_domainset(driver->size, M_BUS_SC,
2403 			    policy, M_NOWAIT | M_ZERO);
2404 			if (!dev->softc) {
2405 				kobj_delete((kobj_t) dev, NULL);
2406 				kobj_init((kobj_t) dev, &null_class);
2407 				dev->driver = NULL;
2408 				return (ENOMEM);
2409 			}
2410 		}
2411 	} else {
2412 		kobj_init((kobj_t) dev, &null_class);
2413 	}
2414 
2415 	bus_data_generation_update();
2416 	return (0);
2417 }
2418 
2419 /**
2420  * @brief Probe a device, and return this status.
2421  *
2422  * This function is the core of the device autoconfiguration
2423  * system. Its purpose is to select a suitable driver for a device and
2424  * then call that driver to initialise the hardware appropriately. The
2425  * driver is selected by calling the DEVICE_PROBE() method of a set of
2426  * candidate drivers and then choosing the driver which returned the
2427  * best value. This driver is then attached to the device using
2428  * device_attach().
2429  *
2430  * The set of suitable drivers is taken from the list of drivers in
2431  * the parent device's devclass. If the device was originally created
2432  * with a specific class name (see device_add_child()), only drivers
2433  * with that name are probed, otherwise all drivers in the devclass
2434  * are probed. If no drivers return successful probe values in the
2435  * parent devclass, the search continues in the parent of that
2436  * devclass (see devclass_get_parent()) if any.
2437  *
2438  * @param dev		the device to initialise
2439  *
2440  * @retval 0		success
2441  * @retval ENXIO	no driver was found
2442  * @retval ENOMEM	memory allocation failure
2443  * @retval non-zero	some other unix error code
2444  * @retval -1		Device already attached
2445  */
2446 int
2447 device_probe(device_t dev)
2448 {
2449 	int error;
2450 
2451 	bus_topo_assert();
2452 
2453 	if (dev->state >= DS_ALIVE)
2454 		return (-1);
2455 
2456 	if (!(dev->flags & DF_ENABLED)) {
2457 		if (bootverbose && device_get_name(dev) != NULL) {
2458 			device_print_prettyname(dev);
2459 			printf("not probed (disabled)\n");
2460 		}
2461 		return (-1);
2462 	}
2463 	if ((error = device_probe_child(dev->parent, dev)) != 0) {
2464 		if (bus_current_pass == BUS_PASS_DEFAULT &&
2465 		    !(dev->flags & DF_DONENOMATCH)) {
2466 			device_handle_nomatch(dev);
2467 		}
2468 		return (error);
2469 	}
2470 	return (0);
2471 }
2472 
2473 /**
2474  * @brief Probe a device and attach a driver if possible
2475  *
2476  * calls device_probe() and attaches if that was successful.
2477  */
2478 int
2479 device_probe_and_attach(device_t dev)
2480 {
2481 	int error;
2482 
2483 	bus_topo_assert();
2484 
2485 	error = device_probe(dev);
2486 	if (error == -1)
2487 		return (0);
2488 	else if (error != 0)
2489 		return (error);
2490 
2491 	CURVNET_SET_QUIET(vnet0);
2492 	error = device_attach(dev);
2493 	CURVNET_RESTORE();
2494 	return error;
2495 }
2496 
2497 /**
2498  * @brief Attach a device driver to a device
2499  *
2500  * This function is a wrapper around the DEVICE_ATTACH() driver
2501  * method. In addition to calling DEVICE_ATTACH(), it initialises the
2502  * device's sysctl tree, optionally prints a description of the device
2503  * and queues a notification event for user-based device management
2504  * services.
2505  *
2506  * Normally this function is only called internally from
2507  * device_probe_and_attach().
2508  *
2509  * @param dev		the device to initialise
2510  *
2511  * @retval 0		success
2512  * @retval ENXIO	no driver was found
2513  * @retval ENOMEM	memory allocation failure
2514  * @retval non-zero	some other unix error code
2515  */
2516 int
2517 device_attach(device_t dev)
2518 {
2519 	uint64_t attachtime;
2520 	uint16_t attachentropy;
2521 	int error;
2522 
2523 	if (resource_disabled(dev->driver->name, dev->unit)) {
2524 		device_disable(dev);
2525 		if (bootverbose)
2526 			 device_printf(dev, "disabled via hints entry\n");
2527 		return (ENXIO);
2528 	}
2529 
2530 	device_sysctl_init(dev);
2531 	if (!device_is_quiet(dev))
2532 		device_print_child(dev->parent, dev);
2533 	attachtime = get_cyclecount();
2534 	dev->state = DS_ATTACHING;
2535 	if ((error = DEVICE_ATTACH(dev)) != 0) {
2536 		printf("device_attach: %s%d attach returned %d\n",
2537 		    dev->driver->name, dev->unit, error);
2538 		if (disable_failed_devs) {
2539 			/*
2540 			 * When the user has asked to disable failed devices, we
2541 			 * directly disable the device, but leave it in the
2542 			 * attaching state. It will not try to probe/attach the
2543 			 * device further. This leaves the device numbering
2544 			 * intact for other similar devices in the system. It
2545 			 * can be removed from this state with devctl.
2546 			 */
2547 			device_disable(dev);
2548 		} else {
2549 			/*
2550 			 * Otherwise, when attach fails, tear down the state
2551 			 * around that so we can retry when, for example, new
2552 			 * drivers are loaded.
2553 			 */
2554 			if (!(dev->flags & DF_FIXEDCLASS))
2555 				devclass_delete_device(dev->devclass, dev);
2556 			(void)device_set_driver(dev, NULL);
2557 			device_sysctl_fini(dev);
2558 			KASSERT(dev->busy == 0, ("attach failed but busy"));
2559 			dev->state = DS_NOTPRESENT;
2560 		}
2561 		return (error);
2562 	}
2563 	dev->flags |= DF_ATTACHED_ONCE;
2564 	/*
2565 	 * We only need the low bits of this time, but ranges from tens to thousands
2566 	 * have been seen, so keep 2 bytes' worth.
2567 	 */
2568 	attachentropy = (uint16_t)(get_cyclecount() - attachtime);
2569 	random_harvest_direct(&attachentropy, sizeof(attachentropy), RANDOM_ATTACH);
2570 	device_sysctl_update(dev);
2571 	dev->state = DS_ATTACHED;
2572 	dev->flags &= ~DF_DONENOMATCH;
2573 	EVENTHANDLER_DIRECT_INVOKE(device_attach, dev);
2574 	return (0);
2575 }
2576 
2577 /**
2578  * @brief Detach a driver from a device
2579  *
2580  * This function is a wrapper around the DEVICE_DETACH() driver
2581  * method. If the call to DEVICE_DETACH() succeeds, it calls
2582  * BUS_CHILD_DETACHED() for the parent of @p dev, queues a
2583  * notification event for user-based device management services and
2584  * cleans up the device's sysctl tree.
2585  *
2586  * @param dev		the device to un-initialise
2587  *
2588  * @retval 0		success
2589  * @retval ENXIO	no driver was found
2590  * @retval ENOMEM	memory allocation failure
2591  * @retval non-zero	some other unix error code
2592  */
2593 int
2594 device_detach(device_t dev)
2595 {
2596 	int error;
2597 
2598 	bus_topo_assert();
2599 
2600 	PDEBUG(("%s", DEVICENAME(dev)));
2601 	if (dev->busy > 0)
2602 		return (EBUSY);
2603 	if (dev->state == DS_ATTACHING) {
2604 		device_printf(dev, "device in attaching state! Deferring detach.\n");
2605 		return (EBUSY);
2606 	}
2607 	if (dev->state != DS_ATTACHED)
2608 		return (0);
2609 
2610 	EVENTHANDLER_DIRECT_INVOKE(device_detach, dev, EVHDEV_DETACH_BEGIN);
2611 	if ((error = DEVICE_DETACH(dev)) != 0) {
2612 		EVENTHANDLER_DIRECT_INVOKE(device_detach, dev,
2613 		    EVHDEV_DETACH_FAILED);
2614 		return (error);
2615 	} else {
2616 		EVENTHANDLER_DIRECT_INVOKE(device_detach, dev,
2617 		    EVHDEV_DETACH_COMPLETE);
2618 	}
2619 	if (!device_is_quiet(dev))
2620 		device_printf(dev, "detached\n");
2621 	if (dev->parent)
2622 		BUS_CHILD_DETACHED(dev->parent, dev);
2623 
2624 	if (!(dev->flags & DF_FIXEDCLASS))
2625 		devclass_delete_device(dev->devclass, dev);
2626 
2627 	device_verbose(dev);
2628 	dev->state = DS_NOTPRESENT;
2629 	(void)device_set_driver(dev, NULL);
2630 	device_sysctl_fini(dev);
2631 
2632 	return (0);
2633 }
2634 
2635 /**
2636  * @brief Tells a driver to quiesce itself.
2637  *
2638  * This function is a wrapper around the DEVICE_QUIESCE() driver
2639  * method. If the call to DEVICE_QUIESCE() succeeds.
2640  *
2641  * @param dev		the device to quiesce
2642  *
2643  * @retval 0		success
2644  * @retval ENXIO	no driver was found
2645  * @retval ENOMEM	memory allocation failure
2646  * @retval non-zero	some other unix error code
2647  */
2648 int
2649 device_quiesce(device_t dev)
2650 {
2651 	PDEBUG(("%s", DEVICENAME(dev)));
2652 	if (dev->busy > 0)
2653 		return (EBUSY);
2654 	if (dev->state != DS_ATTACHED)
2655 		return (0);
2656 
2657 	return (DEVICE_QUIESCE(dev));
2658 }
2659 
2660 /**
2661  * @brief Notify a device of system shutdown
2662  *
2663  * This function calls the DEVICE_SHUTDOWN() driver method if the
2664  * device currently has an attached driver.
2665  *
2666  * @returns the value returned by DEVICE_SHUTDOWN()
2667  */
2668 int
2669 device_shutdown(device_t dev)
2670 {
2671 	if (dev->state < DS_ATTACHED)
2672 		return (0);
2673 	return (DEVICE_SHUTDOWN(dev));
2674 }
2675 
2676 /**
2677  * @brief Set the unit number of a device
2678  *
2679  * This function can be used to override the unit number used for a
2680  * device (e.g. to wire a device to a pre-configured unit number).
2681  */
2682 int
2683 device_set_unit(device_t dev, int unit)
2684 {
2685 	devclass_t dc;
2686 	int err;
2687 
2688 	if (unit == dev->unit)
2689 		return (0);
2690 	dc = device_get_devclass(dev);
2691 	if (unit < dc->maxunit && dc->devices[unit])
2692 		return (EBUSY);
2693 	err = devclass_delete_device(dc, dev);
2694 	if (err)
2695 		return (err);
2696 	dev->unit = unit;
2697 	err = devclass_add_device(dc, dev);
2698 	if (err)
2699 		return (err);
2700 
2701 	bus_data_generation_update();
2702 	return (0);
2703 }
2704 
2705 /*======================================*/
2706 /*
2707  * Some useful method implementations to make life easier for bus drivers.
2708  */
2709 
2710 /**
2711  * @brief Initialize a resource mapping request
2712  *
2713  * This is the internal implementation of the public API
2714  * resource_init_map_request.  Callers may be using a different layout
2715  * of struct resource_map_request than the kernel, so callers pass in
2716  * the size of the structure they are using to identify the structure
2717  * layout.
2718  */
2719 void
2720 resource_init_map_request_impl(struct resource_map_request *args, size_t sz)
2721 {
2722 	bzero(args, sz);
2723 	args->size = sz;
2724 	args->memattr = VM_MEMATTR_DEVICE;
2725 }
2726 
2727 /**
2728  * @brief Validate a resource mapping request
2729  *
2730  * Translate a device driver's mapping request (@p in) to a struct
2731  * resource_map_request using the current structure layout (@p out).
2732  * In addition, validate the offset and length from the mapping
2733  * request against the bounds of the resource @p r.  If the offset or
2734  * length are invalid, fail with EINVAL.  If the offset and length are
2735  * valid, the absolute starting address of the requested mapping is
2736  * returned in @p startp and the length of the requested mapping is
2737  * returned in @p lengthp.
2738  */
2739 int
2740 resource_validate_map_request(struct resource *r,
2741     struct resource_map_request *in, struct resource_map_request *out,
2742     rman_res_t *startp, rman_res_t *lengthp)
2743 {
2744 	rman_res_t end, length, start;
2745 
2746 	/*
2747 	 * This assumes that any callers of this function are compiled
2748 	 * into the kernel and use the same version of the structure
2749 	 * as this file.
2750 	 */
2751 	MPASS(out->size == sizeof(struct resource_map_request));
2752 
2753 	if (in != NULL)
2754 		bcopy(in, out, imin(in->size, out->size));
2755 	start = rman_get_start(r) + out->offset;
2756 	if (out->length == 0)
2757 		length = rman_get_size(r);
2758 	else
2759 		length = out->length;
2760 	end = start + length - 1;
2761 	if (start > rman_get_end(r) || start < rman_get_start(r))
2762 		return (EINVAL);
2763 	if (end > rman_get_end(r) || end < start)
2764 		return (EINVAL);
2765 	*lengthp = length;
2766 	*startp = start;
2767 	return (0);
2768 }
2769 
2770 /**
2771  * @brief Initialise a resource list.
2772  *
2773  * @param rl		the resource list to initialise
2774  */
2775 void
2776 resource_list_init(struct resource_list *rl)
2777 {
2778 	STAILQ_INIT(rl);
2779 }
2780 
2781 /**
2782  * @brief Reclaim memory used by a resource list.
2783  *
2784  * This function frees the memory for all resource entries on the list
2785  * (if any).
2786  *
2787  * @param rl		the resource list to free
2788  */
2789 void
2790 resource_list_free(struct resource_list *rl)
2791 {
2792 	struct resource_list_entry *rle;
2793 
2794 	while ((rle = STAILQ_FIRST(rl)) != NULL) {
2795 		if (rle->res)
2796 			panic("resource_list_free: resource entry is busy");
2797 		STAILQ_REMOVE_HEAD(rl, link);
2798 		free(rle, M_BUS);
2799 	}
2800 }
2801 
2802 /**
2803  * @brief Add a resource entry.
2804  *
2805  * This function adds a resource entry using the given @p type, @p
2806  * start, @p end and @p count values. A rid value is chosen by
2807  * searching sequentially for the first unused rid starting at zero.
2808  *
2809  * @param rl		the resource list to edit
2810  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2811  * @param start		the start address of the resource
2812  * @param end		the end address of the resource
2813  * @param count		XXX end-start+1
2814  */
2815 int
2816 resource_list_add_next(struct resource_list *rl, int type, rman_res_t start,
2817     rman_res_t end, rman_res_t count)
2818 {
2819 	int rid;
2820 
2821 	rid = 0;
2822 	while (resource_list_find(rl, type, rid) != NULL)
2823 		rid++;
2824 	resource_list_add(rl, type, rid, start, end, count);
2825 	return (rid);
2826 }
2827 
2828 /**
2829  * @brief Add or modify a resource entry.
2830  *
2831  * If an existing entry exists with the same type and rid, it will be
2832  * modified using the given values of @p start, @p end and @p
2833  * count. If no entry exists, a new one will be created using the
2834  * given values.  The resource list entry that matches is then returned.
2835  *
2836  * @param rl		the resource list to edit
2837  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2838  * @param rid		the resource identifier
2839  * @param start		the start address of the resource
2840  * @param end		the end address of the resource
2841  * @param count		XXX end-start+1
2842  */
2843 struct resource_list_entry *
2844 resource_list_add(struct resource_list *rl, int type, int rid,
2845     rman_res_t start, rman_res_t end, rman_res_t count)
2846 {
2847 	struct resource_list_entry *rle;
2848 
2849 	rle = resource_list_find(rl, type, rid);
2850 	if (!rle) {
2851 		rle = malloc(sizeof(struct resource_list_entry), M_BUS,
2852 		    M_NOWAIT);
2853 		if (!rle)
2854 			panic("resource_list_add: can't record entry");
2855 		STAILQ_INSERT_TAIL(rl, rle, link);
2856 		rle->type = type;
2857 		rle->rid = rid;
2858 		rle->res = NULL;
2859 		rle->flags = 0;
2860 	}
2861 
2862 	if (rle->res)
2863 		panic("resource_list_add: resource entry is busy");
2864 
2865 	rle->start = start;
2866 	rle->end = end;
2867 	rle->count = count;
2868 	return (rle);
2869 }
2870 
2871 /**
2872  * @brief Determine if a resource entry is busy.
2873  *
2874  * Returns true if a resource entry is busy meaning that it has an
2875  * associated resource that is not an unallocated "reserved" resource.
2876  *
2877  * @param rl		the resource list to search
2878  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2879  * @param rid		the resource identifier
2880  *
2881  * @returns Non-zero if the entry is busy, zero otherwise.
2882  */
2883 int
2884 resource_list_busy(struct resource_list *rl, int type, int rid)
2885 {
2886 	struct resource_list_entry *rle;
2887 
2888 	rle = resource_list_find(rl, type, rid);
2889 	if (rle == NULL || rle->res == NULL)
2890 		return (0);
2891 	if ((rle->flags & (RLE_RESERVED | RLE_ALLOCATED)) == RLE_RESERVED) {
2892 		KASSERT(!(rman_get_flags(rle->res) & RF_ACTIVE),
2893 		    ("reserved resource is active"));
2894 		return (0);
2895 	}
2896 	return (1);
2897 }
2898 
2899 /**
2900  * @brief Determine if a resource entry is reserved.
2901  *
2902  * Returns true if a resource entry is reserved meaning that it has an
2903  * associated "reserved" resource.  The resource can either be
2904  * allocated or unallocated.
2905  *
2906  * @param rl		the resource list to search
2907  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2908  * @param rid		the resource identifier
2909  *
2910  * @returns Non-zero if the entry is reserved, zero otherwise.
2911  */
2912 int
2913 resource_list_reserved(struct resource_list *rl, int type, int rid)
2914 {
2915 	struct resource_list_entry *rle;
2916 
2917 	rle = resource_list_find(rl, type, rid);
2918 	if (rle != NULL && rle->flags & RLE_RESERVED)
2919 		return (1);
2920 	return (0);
2921 }
2922 
2923 /**
2924  * @brief Find a resource entry by type and rid.
2925  *
2926  * @param rl		the resource list to search
2927  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2928  * @param rid		the resource identifier
2929  *
2930  * @returns the resource entry pointer or NULL if there is no such
2931  * entry.
2932  */
2933 struct resource_list_entry *
2934 resource_list_find(struct resource_list *rl, int type, int rid)
2935 {
2936 	struct resource_list_entry *rle;
2937 
2938 	STAILQ_FOREACH(rle, rl, link) {
2939 		if (rle->type == type && rle->rid == rid)
2940 			return (rle);
2941 	}
2942 	return (NULL);
2943 }
2944 
2945 /**
2946  * @brief Delete a resource entry.
2947  *
2948  * @param rl		the resource list to edit
2949  * @param type		the resource entry type (e.g. SYS_RES_MEMORY)
2950  * @param rid		the resource identifier
2951  */
2952 void
2953 resource_list_delete(struct resource_list *rl, int type, int rid)
2954 {
2955 	struct resource_list_entry *rle = resource_list_find(rl, type, rid);
2956 
2957 	if (rle) {
2958 		if (rle->res != NULL)
2959 			panic("resource_list_delete: resource has not been released");
2960 		STAILQ_REMOVE(rl, rle, resource_list_entry, link);
2961 		free(rle, M_BUS);
2962 	}
2963 }
2964 
2965 /**
2966  * @brief Allocate a reserved resource
2967  *
2968  * This can be used by buses to force the allocation of resources
2969  * that are always active in the system even if they are not allocated
2970  * by a driver (e.g. PCI BARs).  This function is usually called when
2971  * adding a new child to the bus.  The resource is allocated from the
2972  * parent bus when it is reserved.  The resource list entry is marked
2973  * with RLE_RESERVED to note that it is a reserved resource.
2974  *
2975  * Subsequent attempts to allocate the resource with
2976  * resource_list_alloc() will succeed the first time and will set
2977  * RLE_ALLOCATED to note that it has been allocated.  When a reserved
2978  * resource that has been allocated is released with
2979  * resource_list_release() the resource RLE_ALLOCATED is cleared, but
2980  * the actual resource remains allocated.  The resource can be released to
2981  * the parent bus by calling resource_list_unreserve().
2982  *
2983  * @param rl		the resource list to allocate from
2984  * @param bus		the parent device of @p child
2985  * @param child		the device for which the resource is being reserved
2986  * @param type		the type of resource to allocate
2987  * @param rid		a pointer to the resource identifier
2988  * @param start		hint at the start of the resource range - pass
2989  *			@c 0 for any start address
2990  * @param end		hint at the end of the resource range - pass
2991  *			@c ~0 for any end address
2992  * @param count		hint at the size of range required - pass @c 1
2993  *			for any size
2994  * @param flags		any extra flags to control the resource
2995  *			allocation - see @c RF_XXX flags in
2996  *			<sys/rman.h> for details
2997  *
2998  * @returns		the resource which was allocated or @c NULL if no
2999  *			resource could be allocated
3000  */
3001 struct resource *
3002 resource_list_reserve(struct resource_list *rl, device_t bus, device_t child,
3003     int type, int *rid, rman_res_t start, rman_res_t end, rman_res_t count, u_int flags)
3004 {
3005 	struct resource_list_entry *rle = NULL;
3006 	int passthrough = (device_get_parent(child) != bus);
3007 	struct resource *r;
3008 
3009 	if (passthrough)
3010 		panic(
3011     "resource_list_reserve() should only be called for direct children");
3012 	if (flags & RF_ACTIVE)
3013 		panic(
3014     "resource_list_reserve() should only reserve inactive resources");
3015 
3016 	r = resource_list_alloc(rl, bus, child, type, rid, start, end, count,
3017 	    flags);
3018 	if (r != NULL) {
3019 		rle = resource_list_find(rl, type, *rid);
3020 		rle->flags |= RLE_RESERVED;
3021 	}
3022 	return (r);
3023 }
3024 
3025 /**
3026  * @brief Helper function for implementing BUS_ALLOC_RESOURCE()
3027  *
3028  * Implement BUS_ALLOC_RESOURCE() by looking up a resource from the list
3029  * and passing the allocation up to the parent of @p bus. This assumes
3030  * that the first entry of @c device_get_ivars(child) is a struct
3031  * resource_list. This also handles 'passthrough' allocations where a
3032  * child is a remote descendant of bus by passing the allocation up to
3033  * the parent of bus.
3034  *
3035  * Typically, a bus driver would store a list of child resources
3036  * somewhere in the child device's ivars (see device_get_ivars()) and
3037  * its implementation of BUS_ALLOC_RESOURCE() would find that list and
3038  * then call resource_list_alloc() to perform the allocation.
3039  *
3040  * @param rl		the resource list to allocate from
3041  * @param bus		the parent device of @p child
3042  * @param child		the device which is requesting an allocation
3043  * @param type		the type of resource to allocate
3044  * @param rid		a pointer to the resource identifier
3045  * @param start		hint at the start of the resource range - pass
3046  *			@c 0 for any start address
3047  * @param end		hint at the end of the resource range - pass
3048  *			@c ~0 for any end address
3049  * @param count		hint at the size of range required - pass @c 1
3050  *			for any size
3051  * @param flags		any extra flags to control the resource
3052  *			allocation - see @c RF_XXX flags in
3053  *			<sys/rman.h> for details
3054  *
3055  * @returns		the resource which was allocated or @c NULL if no
3056  *			resource could be allocated
3057  */
3058 struct resource *
3059 resource_list_alloc(struct resource_list *rl, device_t bus, device_t child,
3060     int type, int *rid, rman_res_t start, rman_res_t end, rman_res_t count, u_int flags)
3061 {
3062 	struct resource_list_entry *rle = NULL;
3063 	int passthrough = (device_get_parent(child) != bus);
3064 	int isdefault = RMAN_IS_DEFAULT_RANGE(start, end);
3065 
3066 	if (passthrough) {
3067 		return (BUS_ALLOC_RESOURCE(device_get_parent(bus), child,
3068 		    type, rid, start, end, count, flags));
3069 	}
3070 
3071 	rle = resource_list_find(rl, type, *rid);
3072 
3073 	if (!rle)
3074 		return (NULL);		/* no resource of that type/rid */
3075 
3076 	if (rle->res) {
3077 		if (rle->flags & RLE_RESERVED) {
3078 			if (rle->flags & RLE_ALLOCATED)
3079 				return (NULL);
3080 			if ((flags & RF_ACTIVE) &&
3081 			    bus_activate_resource(child, type, *rid,
3082 			    rle->res) != 0)
3083 				return (NULL);
3084 			rle->flags |= RLE_ALLOCATED;
3085 			return (rle->res);
3086 		}
3087 		device_printf(bus,
3088 		    "resource entry %#x type %d for child %s is busy\n", *rid,
3089 		    type, device_get_nameunit(child));
3090 		return (NULL);
3091 	}
3092 
3093 	if (isdefault) {
3094 		start = rle->start;
3095 		count = ulmax(count, rle->count);
3096 		end = ulmax(rle->end, start + count - 1);
3097 	}
3098 
3099 	rle->res = BUS_ALLOC_RESOURCE(device_get_parent(bus), child,
3100 	    type, rid, start, end, count, flags);
3101 
3102 	/*
3103 	 * Record the new range.
3104 	 */
3105 	if (rle->res) {
3106 		rle->start = rman_get_start(rle->res);
3107 		rle->end = rman_get_end(rle->res);
3108 		rle->count = count;
3109 	}
3110 
3111 	return (rle->res);
3112 }
3113 
3114 /**
3115  * @brief Helper function for implementing BUS_RELEASE_RESOURCE()
3116  *
3117  * Implement BUS_RELEASE_RESOURCE() using a resource list. Normally
3118  * used with resource_list_alloc().
3119  *
3120  * @param rl		the resource list which was allocated from
3121  * @param bus		the parent device of @p child
3122  * @param child		the device which is requesting a release
3123  * @param type		the type of resource to release
3124  * @param rid		the resource identifier
3125  * @param res		the resource to release
3126  *
3127  * @retval 0		success
3128  * @retval non-zero	a standard unix error code indicating what
3129  *			error condition prevented the operation
3130  */
3131 int
3132 resource_list_release(struct resource_list *rl, device_t bus, device_t child,
3133     int type, int rid, struct resource *res)
3134 {
3135 	struct resource_list_entry *rle = NULL;
3136 	int passthrough = (device_get_parent(child) != bus);
3137 	int error;
3138 
3139 	if (passthrough) {
3140 		return (BUS_RELEASE_RESOURCE(device_get_parent(bus), child,
3141 		    type, rid, res));
3142 	}
3143 
3144 	rle = resource_list_find(rl, type, rid);
3145 
3146 	if (!rle)
3147 		panic("resource_list_release: can't find resource");
3148 	if (!rle->res)
3149 		panic("resource_list_release: resource entry is not busy");
3150 	if (rle->flags & RLE_RESERVED) {
3151 		if (rle->flags & RLE_ALLOCATED) {
3152 			if (rman_get_flags(res) & RF_ACTIVE) {
3153 				error = bus_deactivate_resource(child, type,
3154 				    rid, res);
3155 				if (error)
3156 					return (error);
3157 			}
3158 			rle->flags &= ~RLE_ALLOCATED;
3159 			return (0);
3160 		}
3161 		return (EINVAL);
3162 	}
3163 
3164 	error = BUS_RELEASE_RESOURCE(device_get_parent(bus), child,
3165 	    type, rid, res);
3166 	if (error)
3167 		return (error);
3168 
3169 	rle->res = NULL;
3170 	return (0);
3171 }
3172 
3173 /**
3174  * @brief Release all active resources of a given type
3175  *
3176  * Release all active resources of a specified type.  This is intended
3177  * to be used to cleanup resources leaked by a driver after detach or
3178  * a failed attach.
3179  *
3180  * @param rl		the resource list which was allocated from
3181  * @param bus		the parent device of @p child
3182  * @param child		the device whose active resources are being released
3183  * @param type		the type of resources to release
3184  *
3185  * @retval 0		success
3186  * @retval EBUSY	at least one resource was active
3187  */
3188 int
3189 resource_list_release_active(struct resource_list *rl, device_t bus,
3190     device_t child, int type)
3191 {
3192 	struct resource_list_entry *rle;
3193 	int error, retval;
3194 
3195 	retval = 0;
3196 	STAILQ_FOREACH(rle, rl, link) {
3197 		if (rle->type != type)
3198 			continue;
3199 		if (rle->res == NULL)
3200 			continue;
3201 		if ((rle->flags & (RLE_RESERVED | RLE_ALLOCATED)) ==
3202 		    RLE_RESERVED)
3203 			continue;
3204 		retval = EBUSY;
3205 		error = resource_list_release(rl, bus, child, type,
3206 		    rman_get_rid(rle->res), rle->res);
3207 		if (error != 0)
3208 			device_printf(bus,
3209 			    "Failed to release active resource: %d\n", error);
3210 	}
3211 	return (retval);
3212 }
3213 
3214 /**
3215  * @brief Fully release a reserved resource
3216  *
3217  * Fully releases a resource reserved via resource_list_reserve().
3218  *
3219  * @param rl		the resource list which was allocated from
3220  * @param bus		the parent device of @p child
3221  * @param child		the device whose reserved resource is being released
3222  * @param type		the type of resource to release
3223  * @param rid		the resource identifier
3224  * @param res		the resource to release
3225  *
3226  * @retval 0		success
3227  * @retval non-zero	a standard unix error code indicating what
3228  *			error condition prevented the operation
3229  */
3230 int
3231 resource_list_unreserve(struct resource_list *rl, device_t bus, device_t child,
3232     int type, int rid)
3233 {
3234 	struct resource_list_entry *rle = NULL;
3235 	int passthrough = (device_get_parent(child) != bus);
3236 
3237 	if (passthrough)
3238 		panic(
3239     "resource_list_unreserve() should only be called for direct children");
3240 
3241 	rle = resource_list_find(rl, type, rid);
3242 
3243 	if (!rle)
3244 		panic("resource_list_unreserve: can't find resource");
3245 	if (!(rle->flags & RLE_RESERVED))
3246 		return (EINVAL);
3247 	if (rle->flags & RLE_ALLOCATED)
3248 		return (EBUSY);
3249 	rle->flags &= ~RLE_RESERVED;
3250 	return (resource_list_release(rl, bus, child, type, rid, rle->res));
3251 }
3252 
3253 /**
3254  * @brief Print a description of resources in a resource list
3255  *
3256  * Print all resources of a specified type, for use in BUS_PRINT_CHILD().
3257  * The name is printed if at least one resource of the given type is available.
3258  * The format is used to print resource start and end.
3259  *
3260  * @param rl		the resource list to print
3261  * @param name		the name of @p type, e.g. @c "memory"
3262  * @param type		type type of resource entry to print
3263  * @param format	printf(9) format string to print resource
3264  *			start and end values
3265  *
3266  * @returns		the number of characters printed
3267  */
3268 int
3269 resource_list_print_type(struct resource_list *rl, const char *name, int type,
3270     const char *format)
3271 {
3272 	struct resource_list_entry *rle;
3273 	int printed, retval;
3274 
3275 	printed = 0;
3276 	retval = 0;
3277 	/* Yes, this is kinda cheating */
3278 	STAILQ_FOREACH(rle, rl, link) {
3279 		if (rle->type == type) {
3280 			if (printed == 0)
3281 				retval += printf(" %s ", name);
3282 			else
3283 				retval += printf(",");
3284 			printed++;
3285 			retval += printf(format, rle->start);
3286 			if (rle->count > 1) {
3287 				retval += printf("-");
3288 				retval += printf(format, rle->start +
3289 						 rle->count - 1);
3290 			}
3291 		}
3292 	}
3293 	return (retval);
3294 }
3295 
3296 /**
3297  * @brief Releases all the resources in a list.
3298  *
3299  * @param rl		The resource list to purge.
3300  *
3301  * @returns		nothing
3302  */
3303 void
3304 resource_list_purge(struct resource_list *rl)
3305 {
3306 	struct resource_list_entry *rle;
3307 
3308 	while ((rle = STAILQ_FIRST(rl)) != NULL) {
3309 		if (rle->res)
3310 			bus_release_resource(rman_get_device(rle->res),
3311 			    rle->type, rle->rid, rle->res);
3312 		STAILQ_REMOVE_HEAD(rl, link);
3313 		free(rle, M_BUS);
3314 	}
3315 }
3316 
3317 device_t
3318 bus_generic_add_child(device_t dev, u_int order, const char *name, int unit)
3319 {
3320 	return (device_add_child_ordered(dev, order, name, unit));
3321 }
3322 
3323 /**
3324  * @brief Helper function for implementing DEVICE_PROBE()
3325  *
3326  * This function can be used to help implement the DEVICE_PROBE() for
3327  * a bus (i.e. a device which has other devices attached to it). It
3328  * calls the DEVICE_IDENTIFY() method of each driver in the device's
3329  * devclass.
3330  */
3331 int
3332 bus_generic_probe(device_t dev)
3333 {
3334 	devclass_t dc = dev->devclass;
3335 	driverlink_t dl;
3336 
3337 	TAILQ_FOREACH(dl, &dc->drivers, link) {
3338 		/*
3339 		 * If this driver's pass is too high, then ignore it.
3340 		 * For most drivers in the default pass, this will
3341 		 * never be true.  For early-pass drivers they will
3342 		 * only call the identify routines of eligible drivers
3343 		 * when this routine is called.  Drivers for later
3344 		 * passes should have their identify routines called
3345 		 * on early-pass buses during BUS_NEW_PASS().
3346 		 */
3347 		if (dl->pass > bus_current_pass)
3348 			continue;
3349 		DEVICE_IDENTIFY(dl->driver, dev);
3350 	}
3351 
3352 	return (0);
3353 }
3354 
3355 /**
3356  * @brief Helper function for implementing DEVICE_ATTACH()
3357  *
3358  * This function can be used to help implement the DEVICE_ATTACH() for
3359  * a bus. It calls device_probe_and_attach() for each of the device's
3360  * children.
3361  */
3362 int
3363 bus_generic_attach(device_t dev)
3364 {
3365 	device_t child;
3366 
3367 	TAILQ_FOREACH(child, &dev->children, link) {
3368 		device_probe_and_attach(child);
3369 	}
3370 
3371 	return (0);
3372 }
3373 
3374 /**
3375  * @brief Helper function for delaying attaching children
3376  *
3377  * Many buses can't run transactions on the bus which children need to probe and
3378  * attach until after interrupts and/or timers are running.  This function
3379  * delays their attach until interrupts and timers are enabled.
3380  */
3381 int
3382 bus_delayed_attach_children(device_t dev)
3383 {
3384 	/* Probe and attach the bus children when interrupts are available */
3385 	config_intrhook_oneshot((ich_func_t)bus_generic_attach, dev);
3386 
3387 	return (0);
3388 }
3389 
3390 /**
3391  * @brief Helper function for implementing DEVICE_DETACH()
3392  *
3393  * This function can be used to help implement the DEVICE_DETACH() for
3394  * a bus. It calls device_detach() for each of the device's
3395  * children.
3396  */
3397 int
3398 bus_generic_detach(device_t dev)
3399 {
3400 	device_t child;
3401 	int error;
3402 
3403 	if (dev->state != DS_ATTACHED)
3404 		return (EBUSY);
3405 
3406 	/*
3407 	 * Detach children in the reverse order.
3408 	 * See bus_generic_suspend for details.
3409 	 */
3410 	TAILQ_FOREACH_REVERSE(child, &dev->children, device_list, link) {
3411 		if ((error = device_detach(child)) != 0)
3412 			return (error);
3413 	}
3414 
3415 	return (0);
3416 }
3417 
3418 /**
3419  * @brief Helper function for implementing DEVICE_SHUTDOWN()
3420  *
3421  * This function can be used to help implement the DEVICE_SHUTDOWN()
3422  * for a bus. It calls device_shutdown() for each of the device's
3423  * children.
3424  */
3425 int
3426 bus_generic_shutdown(device_t dev)
3427 {
3428 	device_t child;
3429 
3430 	/*
3431 	 * Shut down children in the reverse order.
3432 	 * See bus_generic_suspend for details.
3433 	 */
3434 	TAILQ_FOREACH_REVERSE(child, &dev->children, device_list, link) {
3435 		device_shutdown(child);
3436 	}
3437 
3438 	return (0);
3439 }
3440 
3441 /**
3442  * @brief Default function for suspending a child device.
3443  *
3444  * This function is to be used by a bus's DEVICE_SUSPEND_CHILD().
3445  */
3446 int
3447 bus_generic_suspend_child(device_t dev, device_t child)
3448 {
3449 	int	error;
3450 
3451 	error = DEVICE_SUSPEND(child);
3452 
3453 	if (error == 0)
3454 		child->flags |= DF_SUSPENDED;
3455 
3456 	return (error);
3457 }
3458 
3459 /**
3460  * @brief Default function for resuming a child device.
3461  *
3462  * This function is to be used by a bus's DEVICE_RESUME_CHILD().
3463  */
3464 int
3465 bus_generic_resume_child(device_t dev, device_t child)
3466 {
3467 	DEVICE_RESUME(child);
3468 	child->flags &= ~DF_SUSPENDED;
3469 
3470 	return (0);
3471 }
3472 
3473 /**
3474  * @brief Helper function for implementing DEVICE_SUSPEND()
3475  *
3476  * This function can be used to help implement the DEVICE_SUSPEND()
3477  * for a bus. It calls DEVICE_SUSPEND() for each of the device's
3478  * children. If any call to DEVICE_SUSPEND() fails, the suspend
3479  * operation is aborted and any devices which were suspended are
3480  * resumed immediately by calling their DEVICE_RESUME() methods.
3481  */
3482 int
3483 bus_generic_suspend(device_t dev)
3484 {
3485 	int		error;
3486 	device_t	child;
3487 
3488 	/*
3489 	 * Suspend children in the reverse order.
3490 	 * For most buses all children are equal, so the order does not matter.
3491 	 * Other buses, such as acpi, carefully order their child devices to
3492 	 * express implicit dependencies between them.  For such buses it is
3493 	 * safer to bring down devices in the reverse order.
3494 	 */
3495 	TAILQ_FOREACH_REVERSE(child, &dev->children, device_list, link) {
3496 		error = BUS_SUSPEND_CHILD(dev, child);
3497 		if (error != 0) {
3498 			child = TAILQ_NEXT(child, link);
3499 			if (child != NULL) {
3500 				TAILQ_FOREACH_FROM(child, &dev->children, link)
3501 					BUS_RESUME_CHILD(dev, child);
3502 			}
3503 			return (error);
3504 		}
3505 	}
3506 	return (0);
3507 }
3508 
3509 /**
3510  * @brief Helper function for implementing DEVICE_RESUME()
3511  *
3512  * This function can be used to help implement the DEVICE_RESUME() for
3513  * a bus. It calls DEVICE_RESUME() on each of the device's children.
3514  */
3515 int
3516 bus_generic_resume(device_t dev)
3517 {
3518 	device_t	child;
3519 
3520 	TAILQ_FOREACH(child, &dev->children, link) {
3521 		BUS_RESUME_CHILD(dev, child);
3522 		/* if resume fails, there's nothing we can usefully do... */
3523 	}
3524 	return (0);
3525 }
3526 
3527 /**
3528  * @brief Helper function for implementing BUS_RESET_POST
3529  *
3530  * Bus can use this function to implement common operations of
3531  * re-attaching or resuming the children after the bus itself was
3532  * reset, and after restoring bus-unique state of children.
3533  *
3534  * @param dev	The bus
3535  * #param flags	DEVF_RESET_*
3536  */
3537 int
3538 bus_helper_reset_post(device_t dev, int flags)
3539 {
3540 	device_t child;
3541 	int error, error1;
3542 
3543 	error = 0;
3544 	TAILQ_FOREACH(child, &dev->children,link) {
3545 		BUS_RESET_POST(dev, child);
3546 		error1 = (flags & DEVF_RESET_DETACH) != 0 ?
3547 		    device_probe_and_attach(child) :
3548 		    BUS_RESUME_CHILD(dev, child);
3549 		if (error == 0 && error1 != 0)
3550 			error = error1;
3551 	}
3552 	return (error);
3553 }
3554 
3555 static void
3556 bus_helper_reset_prepare_rollback(device_t dev, device_t child, int flags)
3557 {
3558 	child = TAILQ_NEXT(child, link);
3559 	if (child == NULL)
3560 		return;
3561 	TAILQ_FOREACH_FROM(child, &dev->children,link) {
3562 		BUS_RESET_POST(dev, child);
3563 		if ((flags & DEVF_RESET_DETACH) != 0)
3564 			device_probe_and_attach(child);
3565 		else
3566 			BUS_RESUME_CHILD(dev, child);
3567 	}
3568 }
3569 
3570 /**
3571  * @brief Helper function for implementing BUS_RESET_PREPARE
3572  *
3573  * Bus can use this function to implement common operations of
3574  * detaching or suspending the children before the bus itself is
3575  * reset, and then save bus-unique state of children that must
3576  * persists around reset.
3577  *
3578  * @param dev	The bus
3579  * #param flags	DEVF_RESET_*
3580  */
3581 int
3582 bus_helper_reset_prepare(device_t dev, int flags)
3583 {
3584 	device_t child;
3585 	int error;
3586 
3587 	if (dev->state != DS_ATTACHED)
3588 		return (EBUSY);
3589 
3590 	TAILQ_FOREACH_REVERSE(child, &dev->children, device_list, link) {
3591 		if ((flags & DEVF_RESET_DETACH) != 0) {
3592 			error = device_get_state(child) == DS_ATTACHED ?
3593 			    device_detach(child) : 0;
3594 		} else {
3595 			error = BUS_SUSPEND_CHILD(dev, child);
3596 		}
3597 		if (error == 0) {
3598 			error = BUS_RESET_PREPARE(dev, child);
3599 			if (error != 0) {
3600 				if ((flags & DEVF_RESET_DETACH) != 0)
3601 					device_probe_and_attach(child);
3602 				else
3603 					BUS_RESUME_CHILD(dev, child);
3604 			}
3605 		}
3606 		if (error != 0) {
3607 			bus_helper_reset_prepare_rollback(dev, child, flags);
3608 			return (error);
3609 		}
3610 	}
3611 	return (0);
3612 }
3613 
3614 /**
3615  * @brief Helper function for implementing BUS_PRINT_CHILD().
3616  *
3617  * This function prints the first part of the ascii representation of
3618  * @p child, including its name, unit and description (if any - see
3619  * device_set_desc()).
3620  *
3621  * @returns the number of characters printed
3622  */
3623 int
3624 bus_print_child_header(device_t dev, device_t child)
3625 {
3626 	int	retval = 0;
3627 
3628 	if (device_get_desc(child)) {
3629 		retval += device_printf(child, "<%s>", device_get_desc(child));
3630 	} else {
3631 		retval += printf("%s", device_get_nameunit(child));
3632 	}
3633 
3634 	return (retval);
3635 }
3636 
3637 /**
3638  * @brief Helper function for implementing BUS_PRINT_CHILD().
3639  *
3640  * This function prints the last part of the ascii representation of
3641  * @p child, which consists of the string @c " on " followed by the
3642  * name and unit of the @p dev.
3643  *
3644  * @returns the number of characters printed
3645  */
3646 int
3647 bus_print_child_footer(device_t dev, device_t child)
3648 {
3649 	return (printf(" on %s\n", device_get_nameunit(dev)));
3650 }
3651 
3652 /**
3653  * @brief Helper function for implementing BUS_PRINT_CHILD().
3654  *
3655  * This function prints out the VM domain for the given device.
3656  *
3657  * @returns the number of characters printed
3658  */
3659 int
3660 bus_print_child_domain(device_t dev, device_t child)
3661 {
3662 	int domain;
3663 
3664 	/* No domain? Don't print anything */
3665 	if (BUS_GET_DOMAIN(dev, child, &domain) != 0)
3666 		return (0);
3667 
3668 	return (printf(" numa-domain %d", domain));
3669 }
3670 
3671 /**
3672  * @brief Helper function for implementing BUS_PRINT_CHILD().
3673  *
3674  * This function simply calls bus_print_child_header() followed by
3675  * bus_print_child_footer().
3676  *
3677  * @returns the number of characters printed
3678  */
3679 int
3680 bus_generic_print_child(device_t dev, device_t child)
3681 {
3682 	int	retval = 0;
3683 
3684 	retval += bus_print_child_header(dev, child);
3685 	retval += bus_print_child_domain(dev, child);
3686 	retval += bus_print_child_footer(dev, child);
3687 
3688 	return (retval);
3689 }
3690 
3691 /**
3692  * @brief Stub function for implementing BUS_READ_IVAR().
3693  *
3694  * @returns ENOENT
3695  */
3696 int
3697 bus_generic_read_ivar(device_t dev, device_t child, int index,
3698     uintptr_t * result)
3699 {
3700 	return (ENOENT);
3701 }
3702 
3703 /**
3704  * @brief Stub function for implementing BUS_WRITE_IVAR().
3705  *
3706  * @returns ENOENT
3707  */
3708 int
3709 bus_generic_write_ivar(device_t dev, device_t child, int index,
3710     uintptr_t value)
3711 {
3712 	return (ENOENT);
3713 }
3714 
3715 /**
3716  * @brief Helper function for implementing BUS_GET_PROPERTY().
3717  *
3718  * This simply calls the BUS_GET_PROPERTY of the parent of dev,
3719  * until a non-default implementation is found.
3720  */
3721 ssize_t
3722 bus_generic_get_property(device_t dev, device_t child, const char *propname,
3723     void *propvalue, size_t size, device_property_type_t type)
3724 {
3725 	if (device_get_parent(dev) != NULL)
3726 		return (BUS_GET_PROPERTY(device_get_parent(dev), child,
3727 		    propname, propvalue, size, type));
3728 
3729 	return (-1);
3730 }
3731 
3732 /**
3733  * @brief Stub function for implementing BUS_GET_RESOURCE_LIST().
3734  *
3735  * @returns NULL
3736  */
3737 struct resource_list *
3738 bus_generic_get_resource_list(device_t dev, device_t child)
3739 {
3740 	return (NULL);
3741 }
3742 
3743 /**
3744  * @brief Helper function for implementing BUS_DRIVER_ADDED().
3745  *
3746  * This implementation of BUS_DRIVER_ADDED() simply calls the driver's
3747  * DEVICE_IDENTIFY() method to allow it to add new children to the bus
3748  * and then calls device_probe_and_attach() for each unattached child.
3749  */
3750 void
3751 bus_generic_driver_added(device_t dev, driver_t *driver)
3752 {
3753 	device_t child;
3754 
3755 	DEVICE_IDENTIFY(driver, dev);
3756 	TAILQ_FOREACH(child, &dev->children, link) {
3757 		if (child->state == DS_NOTPRESENT)
3758 			device_probe_and_attach(child);
3759 	}
3760 }
3761 
3762 /**
3763  * @brief Helper function for implementing BUS_NEW_PASS().
3764  *
3765  * This implementing of BUS_NEW_PASS() first calls the identify
3766  * routines for any drivers that probe at the current pass.  Then it
3767  * walks the list of devices for this bus.  If a device is already
3768  * attached, then it calls BUS_NEW_PASS() on that device.  If the
3769  * device is not already attached, it attempts to attach a driver to
3770  * it.
3771  */
3772 void
3773 bus_generic_new_pass(device_t dev)
3774 {
3775 	driverlink_t dl;
3776 	devclass_t dc;
3777 	device_t child;
3778 
3779 	dc = dev->devclass;
3780 	TAILQ_FOREACH(dl, &dc->drivers, link) {
3781 		if (dl->pass == bus_current_pass)
3782 			DEVICE_IDENTIFY(dl->driver, dev);
3783 	}
3784 	TAILQ_FOREACH(child, &dev->children, link) {
3785 		if (child->state >= DS_ATTACHED)
3786 			BUS_NEW_PASS(child);
3787 		else if (child->state == DS_NOTPRESENT)
3788 			device_probe_and_attach(child);
3789 	}
3790 }
3791 
3792 /**
3793  * @brief Helper function for implementing BUS_SETUP_INTR().
3794  *
3795  * This simple implementation of BUS_SETUP_INTR() simply calls the
3796  * BUS_SETUP_INTR() method of the parent of @p dev.
3797  */
3798 int
3799 bus_generic_setup_intr(device_t dev, device_t child, struct resource *irq,
3800     int flags, driver_filter_t *filter, driver_intr_t *intr, void *arg,
3801     void **cookiep)
3802 {
3803 	/* Propagate up the bus hierarchy until someone handles it. */
3804 	if (dev->parent)
3805 		return (BUS_SETUP_INTR(dev->parent, child, irq, flags,
3806 		    filter, intr, arg, cookiep));
3807 	return (EINVAL);
3808 }
3809 
3810 /**
3811  * @brief Helper function for implementing BUS_TEARDOWN_INTR().
3812  *
3813  * This simple implementation of BUS_TEARDOWN_INTR() simply calls the
3814  * BUS_TEARDOWN_INTR() method of the parent of @p dev.
3815  */
3816 int
3817 bus_generic_teardown_intr(device_t dev, device_t child, struct resource *irq,
3818     void *cookie)
3819 {
3820 	/* Propagate up the bus hierarchy until someone handles it. */
3821 	if (dev->parent)
3822 		return (BUS_TEARDOWN_INTR(dev->parent, child, irq, cookie));
3823 	return (EINVAL);
3824 }
3825 
3826 /**
3827  * @brief Helper function for implementing BUS_SUSPEND_INTR().
3828  *
3829  * This simple implementation of BUS_SUSPEND_INTR() simply calls the
3830  * BUS_SUSPEND_INTR() method of the parent of @p dev.
3831  */
3832 int
3833 bus_generic_suspend_intr(device_t dev, device_t child, struct resource *irq)
3834 {
3835 	/* Propagate up the bus hierarchy until someone handles it. */
3836 	if (dev->parent)
3837 		return (BUS_SUSPEND_INTR(dev->parent, child, irq));
3838 	return (EINVAL);
3839 }
3840 
3841 /**
3842  * @brief Helper function for implementing BUS_RESUME_INTR().
3843  *
3844  * This simple implementation of BUS_RESUME_INTR() simply calls the
3845  * BUS_RESUME_INTR() method of the parent of @p dev.
3846  */
3847 int
3848 bus_generic_resume_intr(device_t dev, device_t child, struct resource *irq)
3849 {
3850 	/* Propagate up the bus hierarchy until someone handles it. */
3851 	if (dev->parent)
3852 		return (BUS_RESUME_INTR(dev->parent, child, irq));
3853 	return (EINVAL);
3854 }
3855 
3856 /**
3857  * @brief Helper function for implementing BUS_ADJUST_RESOURCE().
3858  *
3859  * This simple implementation of BUS_ADJUST_RESOURCE() simply calls the
3860  * BUS_ADJUST_RESOURCE() method of the parent of @p dev.
3861  */
3862 int
3863 bus_generic_adjust_resource(device_t dev, device_t child, int type,
3864     struct resource *r, rman_res_t start, rman_res_t end)
3865 {
3866 	/* Propagate up the bus hierarchy until someone handles it. */
3867 	if (dev->parent)
3868 		return (BUS_ADJUST_RESOURCE(dev->parent, child, type, r, start,
3869 		    end));
3870 	return (EINVAL);
3871 }
3872 
3873 /*
3874  * @brief Helper function for implementing BUS_TRANSLATE_RESOURCE().
3875  *
3876  * This simple implementation of BUS_TRANSLATE_RESOURCE() simply calls the
3877  * BUS_TRANSLATE_RESOURCE() method of the parent of @p dev.  If there is no
3878  * parent, no translation happens.
3879  */
3880 int
3881 bus_generic_translate_resource(device_t dev, int type, rman_res_t start,
3882     rman_res_t *newstart)
3883 {
3884 	if (dev->parent)
3885 		return (BUS_TRANSLATE_RESOURCE(dev->parent, type, start,
3886 		    newstart));
3887 	*newstart = start;
3888 	return (0);
3889 }
3890 
3891 /**
3892  * @brief Helper function for implementing BUS_ALLOC_RESOURCE().
3893  *
3894  * This simple implementation of BUS_ALLOC_RESOURCE() simply calls the
3895  * BUS_ALLOC_RESOURCE() method of the parent of @p dev.
3896  */
3897 struct resource *
3898 bus_generic_alloc_resource(device_t dev, device_t child, int type, int *rid,
3899     rman_res_t start, rman_res_t end, rman_res_t count, u_int flags)
3900 {
3901 	/* Propagate up the bus hierarchy until someone handles it. */
3902 	if (dev->parent)
3903 		return (BUS_ALLOC_RESOURCE(dev->parent, child, type, rid,
3904 		    start, end, count, flags));
3905 	return (NULL);
3906 }
3907 
3908 /**
3909  * @brief Helper function for implementing BUS_RELEASE_RESOURCE().
3910  *
3911  * This simple implementation of BUS_RELEASE_RESOURCE() simply calls the
3912  * BUS_RELEASE_RESOURCE() method of the parent of @p dev.
3913  */
3914 int
3915 bus_generic_release_resource(device_t dev, device_t child, int type, int rid,
3916     struct resource *r)
3917 {
3918 	/* Propagate up the bus hierarchy until someone handles it. */
3919 	if (dev->parent)
3920 		return (BUS_RELEASE_RESOURCE(dev->parent, child, type, rid,
3921 		    r));
3922 	return (EINVAL);
3923 }
3924 
3925 /**
3926  * @brief Helper function for implementing BUS_ACTIVATE_RESOURCE().
3927  *
3928  * This simple implementation of BUS_ACTIVATE_RESOURCE() simply calls the
3929  * BUS_ACTIVATE_RESOURCE() method of the parent of @p dev.
3930  */
3931 int
3932 bus_generic_activate_resource(device_t dev, device_t child, int type, int rid,
3933     struct resource *r)
3934 {
3935 	/* Propagate up the bus hierarchy until someone handles it. */
3936 	if (dev->parent)
3937 		return (BUS_ACTIVATE_RESOURCE(dev->parent, child, type, rid,
3938 		    r));
3939 	return (EINVAL);
3940 }
3941 
3942 /**
3943  * @brief Helper function for implementing BUS_DEACTIVATE_RESOURCE().
3944  *
3945  * This simple implementation of BUS_DEACTIVATE_RESOURCE() simply calls the
3946  * BUS_DEACTIVATE_RESOURCE() method of the parent of @p dev.
3947  */
3948 int
3949 bus_generic_deactivate_resource(device_t dev, device_t child, int type,
3950     int rid, struct resource *r)
3951 {
3952 	/* Propagate up the bus hierarchy until someone handles it. */
3953 	if (dev->parent)
3954 		return (BUS_DEACTIVATE_RESOURCE(dev->parent, child, type, rid,
3955 		    r));
3956 	return (EINVAL);
3957 }
3958 
3959 /**
3960  * @brief Helper function for implementing BUS_MAP_RESOURCE().
3961  *
3962  * This simple implementation of BUS_MAP_RESOURCE() simply calls the
3963  * BUS_MAP_RESOURCE() method of the parent of @p dev.
3964  */
3965 int
3966 bus_generic_map_resource(device_t dev, device_t child, int type,
3967     struct resource *r, struct resource_map_request *args,
3968     struct resource_map *map)
3969 {
3970 	/* Propagate up the bus hierarchy until someone handles it. */
3971 	if (dev->parent)
3972 		return (BUS_MAP_RESOURCE(dev->parent, child, type, r, args,
3973 		    map));
3974 	return (EINVAL);
3975 }
3976 
3977 /**
3978  * @brief Helper function for implementing BUS_UNMAP_RESOURCE().
3979  *
3980  * This simple implementation of BUS_UNMAP_RESOURCE() simply calls the
3981  * BUS_UNMAP_RESOURCE() method of the parent of @p dev.
3982  */
3983 int
3984 bus_generic_unmap_resource(device_t dev, device_t child, int type,
3985     struct resource *r, struct resource_map *map)
3986 {
3987 	/* Propagate up the bus hierarchy until someone handles it. */
3988 	if (dev->parent)
3989 		return (BUS_UNMAP_RESOURCE(dev->parent, child, type, r, map));
3990 	return (EINVAL);
3991 }
3992 
3993 /**
3994  * @brief Helper function for implementing BUS_BIND_INTR().
3995  *
3996  * This simple implementation of BUS_BIND_INTR() simply calls the
3997  * BUS_BIND_INTR() method of the parent of @p dev.
3998  */
3999 int
4000 bus_generic_bind_intr(device_t dev, device_t child, struct resource *irq,
4001     int cpu)
4002 {
4003 	/* Propagate up the bus hierarchy until someone handles it. */
4004 	if (dev->parent)
4005 		return (BUS_BIND_INTR(dev->parent, child, irq, cpu));
4006 	return (EINVAL);
4007 }
4008 
4009 /**
4010  * @brief Helper function for implementing BUS_CONFIG_INTR().
4011  *
4012  * This simple implementation of BUS_CONFIG_INTR() simply calls the
4013  * BUS_CONFIG_INTR() method of the parent of @p dev.
4014  */
4015 int
4016 bus_generic_config_intr(device_t dev, int irq, enum intr_trigger trig,
4017     enum intr_polarity pol)
4018 {
4019 	/* Propagate up the bus hierarchy until someone handles it. */
4020 	if (dev->parent)
4021 		return (BUS_CONFIG_INTR(dev->parent, irq, trig, pol));
4022 	return (EINVAL);
4023 }
4024 
4025 /**
4026  * @brief Helper function for implementing BUS_DESCRIBE_INTR().
4027  *
4028  * This simple implementation of BUS_DESCRIBE_INTR() simply calls the
4029  * BUS_DESCRIBE_INTR() method of the parent of @p dev.
4030  */
4031 int
4032 bus_generic_describe_intr(device_t dev, device_t child, struct resource *irq,
4033     void *cookie, const char *descr)
4034 {
4035 	/* Propagate up the bus hierarchy until someone handles it. */
4036 	if (dev->parent)
4037 		return (BUS_DESCRIBE_INTR(dev->parent, child, irq, cookie,
4038 		    descr));
4039 	return (EINVAL);
4040 }
4041 
4042 /**
4043  * @brief Helper function for implementing BUS_GET_CPUS().
4044  *
4045  * This simple implementation of BUS_GET_CPUS() simply calls the
4046  * BUS_GET_CPUS() method of the parent of @p dev.
4047  */
4048 int
4049 bus_generic_get_cpus(device_t dev, device_t child, enum cpu_sets op,
4050     size_t setsize, cpuset_t *cpuset)
4051 {
4052 	/* Propagate up the bus hierarchy until someone handles it. */
4053 	if (dev->parent != NULL)
4054 		return (BUS_GET_CPUS(dev->parent, child, op, setsize, cpuset));
4055 	return (EINVAL);
4056 }
4057 
4058 /**
4059  * @brief Helper function for implementing BUS_GET_DMA_TAG().
4060  *
4061  * This simple implementation of BUS_GET_DMA_TAG() simply calls the
4062  * BUS_GET_DMA_TAG() method of the parent of @p dev.
4063  */
4064 bus_dma_tag_t
4065 bus_generic_get_dma_tag(device_t dev, device_t child)
4066 {
4067 	/* Propagate up the bus hierarchy until someone handles it. */
4068 	if (dev->parent != NULL)
4069 		return (BUS_GET_DMA_TAG(dev->parent, child));
4070 	return (NULL);
4071 }
4072 
4073 /**
4074  * @brief Helper function for implementing BUS_GET_BUS_TAG().
4075  *
4076  * This simple implementation of BUS_GET_BUS_TAG() simply calls the
4077  * BUS_GET_BUS_TAG() method of the parent of @p dev.
4078  */
4079 bus_space_tag_t
4080 bus_generic_get_bus_tag(device_t dev, device_t child)
4081 {
4082 	/* Propagate up the bus hierarchy until someone handles it. */
4083 	if (dev->parent != NULL)
4084 		return (BUS_GET_BUS_TAG(dev->parent, child));
4085 	return ((bus_space_tag_t)0);
4086 }
4087 
4088 /**
4089  * @brief Helper function for implementing BUS_GET_RESOURCE().
4090  *
4091  * This implementation of BUS_GET_RESOURCE() uses the
4092  * resource_list_find() function to do most of the work. It calls
4093  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
4094  * search.
4095  */
4096 int
4097 bus_generic_rl_get_resource(device_t dev, device_t child, int type, int rid,
4098     rman_res_t *startp, rman_res_t *countp)
4099 {
4100 	struct resource_list *		rl = NULL;
4101 	struct resource_list_entry *	rle = NULL;
4102 
4103 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4104 	if (!rl)
4105 		return (EINVAL);
4106 
4107 	rle = resource_list_find(rl, type, rid);
4108 	if (!rle)
4109 		return (ENOENT);
4110 
4111 	if (startp)
4112 		*startp = rle->start;
4113 	if (countp)
4114 		*countp = rle->count;
4115 
4116 	return (0);
4117 }
4118 
4119 /**
4120  * @brief Helper function for implementing BUS_SET_RESOURCE().
4121  *
4122  * This implementation of BUS_SET_RESOURCE() uses the
4123  * resource_list_add() function to do most of the work. It calls
4124  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
4125  * edit.
4126  */
4127 int
4128 bus_generic_rl_set_resource(device_t dev, device_t child, int type, int rid,
4129     rman_res_t start, rman_res_t count)
4130 {
4131 	struct resource_list *		rl = NULL;
4132 
4133 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4134 	if (!rl)
4135 		return (EINVAL);
4136 
4137 	resource_list_add(rl, type, rid, start, (start + count - 1), count);
4138 
4139 	return (0);
4140 }
4141 
4142 /**
4143  * @brief Helper function for implementing BUS_DELETE_RESOURCE().
4144  *
4145  * This implementation of BUS_DELETE_RESOURCE() uses the
4146  * resource_list_delete() function to do most of the work. It calls
4147  * BUS_GET_RESOURCE_LIST() to find a suitable resource list to
4148  * edit.
4149  */
4150 void
4151 bus_generic_rl_delete_resource(device_t dev, device_t child, int type, int rid)
4152 {
4153 	struct resource_list *		rl = NULL;
4154 
4155 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4156 	if (!rl)
4157 		return;
4158 
4159 	resource_list_delete(rl, type, rid);
4160 
4161 	return;
4162 }
4163 
4164 /**
4165  * @brief Helper function for implementing BUS_RELEASE_RESOURCE().
4166  *
4167  * This implementation of BUS_RELEASE_RESOURCE() uses the
4168  * resource_list_release() function to do most of the work. It calls
4169  * BUS_GET_RESOURCE_LIST() to find a suitable resource list.
4170  */
4171 int
4172 bus_generic_rl_release_resource(device_t dev, device_t child, int type,
4173     int rid, struct resource *r)
4174 {
4175 	struct resource_list *		rl = NULL;
4176 
4177 	if (device_get_parent(child) != dev)
4178 		return (BUS_RELEASE_RESOURCE(device_get_parent(dev), child,
4179 		    type, rid, r));
4180 
4181 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4182 	if (!rl)
4183 		return (EINVAL);
4184 
4185 	return (resource_list_release(rl, dev, child, type, rid, r));
4186 }
4187 
4188 /**
4189  * @brief Helper function for implementing BUS_ALLOC_RESOURCE().
4190  *
4191  * This implementation of BUS_ALLOC_RESOURCE() uses the
4192  * resource_list_alloc() function to do most of the work. It calls
4193  * BUS_GET_RESOURCE_LIST() to find a suitable resource list.
4194  */
4195 struct resource *
4196 bus_generic_rl_alloc_resource(device_t dev, device_t child, int type,
4197     int *rid, rman_res_t start, rman_res_t end, rman_res_t count, u_int flags)
4198 {
4199 	struct resource_list *		rl = NULL;
4200 
4201 	if (device_get_parent(child) != dev)
4202 		return (BUS_ALLOC_RESOURCE(device_get_parent(dev), child,
4203 		    type, rid, start, end, count, flags));
4204 
4205 	rl = BUS_GET_RESOURCE_LIST(dev, child);
4206 	if (!rl)
4207 		return (NULL);
4208 
4209 	return (resource_list_alloc(rl, dev, child, type, rid,
4210 	    start, end, count, flags));
4211 }
4212 
4213 /**
4214  * @brief Helper function for implementing BUS_ALLOC_RESOURCE().
4215  *
4216  * This implementation of BUS_ALLOC_RESOURCE() allocates a
4217  * resource from a resource manager.  It uses BUS_GET_RMAN()
4218  * to obtain the resource manager.
4219  */
4220 struct resource *
4221 bus_generic_rman_alloc_resource(device_t dev, device_t child, int type,
4222     int *rid, rman_res_t start, rman_res_t end, rman_res_t count, u_int flags)
4223 {
4224 	struct resource *r;
4225 	struct rman *rm;
4226 
4227 	rm = BUS_GET_RMAN(dev, type, flags);
4228 	if (rm == NULL)
4229 		return (NULL);
4230 
4231 	r = rman_reserve_resource(rm, start, end, count, flags & ~RF_ACTIVE,
4232 	    child);
4233 	if (r == NULL)
4234 		return (NULL);
4235 	rman_set_rid(r, *rid);
4236 
4237 	if (flags & RF_ACTIVE) {
4238 		if (bus_activate_resource(child, type, *rid, r) != 0) {
4239 			rman_release_resource(r);
4240 			return (NULL);
4241 		}
4242 	}
4243 
4244 	return (r);
4245 }
4246 
4247 /**
4248  * @brief Helper function for implementing BUS_ADJUST_RESOURCE().
4249  *
4250  * This implementation of BUS_ADJUST_RESOURCE() adjusts resources only
4251  * if they were allocated from the resource manager returned by
4252  * BUS_GET_RMAN().
4253  */
4254 int
4255 bus_generic_rman_adjust_resource(device_t dev, device_t child, int type,
4256     struct resource *r, rman_res_t start, rman_res_t end)
4257 {
4258 	struct rman *rm;
4259 
4260 	rm = BUS_GET_RMAN(dev, type, rman_get_flags(r));
4261 	if (rm == NULL)
4262 		return (ENXIO);
4263 	if (!rman_is_region_manager(r, rm))
4264 		return (EINVAL);
4265 	return (rman_adjust_resource(r, start, end));
4266 }
4267 
4268 /**
4269  * @brief Helper function for implementing BUS_RELEASE_RESOURCE().
4270  *
4271  * This implementation of BUS_RELEASE_RESOURCE() releases resources
4272  * allocated by bus_generic_rman_alloc_resource.
4273  */
4274 int
4275 bus_generic_rman_release_resource(device_t dev, device_t child, int type,
4276     int rid, struct resource *r)
4277 {
4278 #ifdef INVARIANTS
4279 	struct rman *rm;
4280 #endif
4281 	int error;
4282 
4283 #ifdef INVARIANTS
4284 	rm = BUS_GET_RMAN(dev, type, rman_get_flags(r));
4285 	KASSERT(rman_is_region_manager(r, rm),
4286 	    ("%s: rman %p doesn't match for resource %p", __func__, rm, r));
4287 #endif
4288 
4289 	if (rman_get_flags(r) & RF_ACTIVE) {
4290 		error = bus_deactivate_resource(child, type, rid, r);
4291 		if (error != 0)
4292 			return (error);
4293 	}
4294 	return (rman_release_resource(r));
4295 }
4296 
4297 /**
4298  * @brief Helper function for implementing BUS_ACTIVATE_RESOURCE().
4299  *
4300  * This implementation of BUS_ACTIVATE_RESOURCE() activates resources
4301  * allocated by bus_generic_rman_alloc_resource.
4302  */
4303 int
4304 bus_generic_rman_activate_resource(device_t dev, device_t child, int type,
4305     int rid, struct resource *r)
4306 {
4307 	struct resource_map map;
4308 #ifdef INVARIANTS_XXX
4309 	struct rman *rm;
4310 #endif
4311 	int error;
4312 
4313 #ifdef INVARIANTS_XXX
4314 	rm = BUS_GET_RMAN(dev, type, rman_get_flags(r));
4315 	KASSERT(rman_is_region_manager(r, rm),
4316 	    ("%s: rman %p doesn't match for resource %p", __func__, rm, r));
4317 #endif
4318 
4319 	error = rman_activate_resource(r);
4320 	if (error != 0)
4321 		return (error);
4322 
4323 	if ((rman_get_flags(r) & RF_UNMAPPED) == 0 &&
4324 	    (type == SYS_RES_MEMORY || type == SYS_RES_IOPORT)) {
4325 		error = BUS_MAP_RESOURCE(dev, child, type, r, NULL, &map);
4326 		if (error != 0) {
4327 			rman_deactivate_resource(r);
4328 			return (error);
4329 		}
4330 
4331 		rman_set_mapping(r, &map);
4332 	}
4333 	return (0);
4334 }
4335 
4336 /**
4337  * @brief Helper function for implementing BUS_DEACTIVATE_RESOURCE().
4338  *
4339  * This implementation of BUS_DEACTIVATE_RESOURCE() deactivates
4340  * resources allocated by bus_generic_rman_alloc_resource.
4341  */
4342 int
4343 bus_generic_rman_deactivate_resource(device_t dev, device_t child, int type,
4344     int rid, struct resource *r)
4345 {
4346 	struct resource_map map;
4347 #ifdef INVARIANTS_XXX
4348 	struct rman *rm;
4349 #endif
4350 	int error;
4351 
4352 #ifdef INVARIANTS_XXX
4353 	rm = BUS_GET_RMAN(dev, type, rman_get_flags(r));
4354 	KASSERT(rman_is_region_manager(r, rm),
4355 	    ("%s: rman %p doesn't match for resource %p", __func__, rm, r));
4356 #endif
4357 
4358 	error = rman_deactivate_resource(r);
4359 	if (error != 0)
4360 		return (error);
4361 
4362 	if ((rman_get_flags(r) & RF_UNMAPPED) == 0 &&
4363 	    (type == SYS_RES_MEMORY || type == SYS_RES_IOPORT)) {
4364 		rman_get_mapping(r, &map);
4365 		BUS_UNMAP_RESOURCE(dev, child, type, r, &map);
4366 	}
4367 	return (0);
4368 }
4369 
4370 /**
4371  * @brief Helper function for implementing BUS_CHILD_PRESENT().
4372  *
4373  * This simple implementation of BUS_CHILD_PRESENT() simply calls the
4374  * BUS_CHILD_PRESENT() method of the parent of @p dev.
4375  */
4376 int
4377 bus_generic_child_present(device_t dev, device_t child)
4378 {
4379 	return (BUS_CHILD_PRESENT(device_get_parent(dev), dev));
4380 }
4381 
4382 /**
4383  * @brief Helper function for implementing BUS_GET_DOMAIN().
4384  *
4385  * This simple implementation of BUS_GET_DOMAIN() calls the
4386  * BUS_GET_DOMAIN() method of the parent of @p dev.  If @p dev
4387  * does not have a parent, the function fails with ENOENT.
4388  */
4389 int
4390 bus_generic_get_domain(device_t dev, device_t child, int *domain)
4391 {
4392 	if (dev->parent)
4393 		return (BUS_GET_DOMAIN(dev->parent, dev, domain));
4394 
4395 	return (ENOENT);
4396 }
4397 
4398 /**
4399  * @brief Helper function to implement normal BUS_GET_DEVICE_PATH()
4400  *
4401  * This function knows how to (a) pass the request up the tree if there's
4402  * a parent and (b) Knows how to supply a FreeBSD locator.
4403  *
4404  * @param bus		bus in the walk up the tree
4405  * @param child		leaf node to print information about
4406  * @param locator	BUS_LOCATOR_xxx string for locator
4407  * @param sb		Buffer to print information into
4408  */
4409 int
4410 bus_generic_get_device_path(device_t bus, device_t child, const char *locator,
4411     struct sbuf *sb)
4412 {
4413 	int rv = 0;
4414 	device_t parent;
4415 
4416 	/*
4417 	 * We don't recurse on ACPI since either we know the handle for the
4418 	 * device or we don't. And if we're in the generic routine, we don't
4419 	 * have a ACPI override. All other locators build up a path by having
4420 	 * their parents create a path and then adding the path element for this
4421 	 * node. That's why we recurse with parent, bus rather than the typical
4422 	 * parent, child: each spot in the tree is independent of what our child
4423 	 * will do with this path.
4424 	 */
4425 	parent = device_get_parent(bus);
4426 	if (parent != NULL && strcmp(locator, BUS_LOCATOR_ACPI) != 0) {
4427 		rv = BUS_GET_DEVICE_PATH(parent, bus, locator, sb);
4428 	}
4429 	if (strcmp(locator, BUS_LOCATOR_FREEBSD) == 0) {
4430 		if (rv == 0) {
4431 			sbuf_printf(sb, "/%s", device_get_nameunit(child));
4432 		}
4433 		return (rv);
4434 	}
4435 	/*
4436 	 * Don't know what to do. So assume we do nothing. Not sure that's
4437 	 * the right thing, but keeps us from having a big list here.
4438 	 */
4439 	return (0);
4440 }
4441 
4442 
4443 /**
4444  * @brief Helper function for implementing BUS_RESCAN().
4445  *
4446  * This null implementation of BUS_RESCAN() always fails to indicate
4447  * the bus does not support rescanning.
4448  */
4449 int
4450 bus_null_rescan(device_t dev)
4451 {
4452 	return (ENODEV);
4453 }
4454 
4455 /*
4456  * Some convenience functions to make it easier for drivers to use the
4457  * resource-management functions.  All these really do is hide the
4458  * indirection through the parent's method table, making for slightly
4459  * less-wordy code.  In the future, it might make sense for this code
4460  * to maintain some sort of a list of resources allocated by each device.
4461  */
4462 
4463 int
4464 bus_alloc_resources(device_t dev, struct resource_spec *rs,
4465     struct resource **res)
4466 {
4467 	int i;
4468 
4469 	for (i = 0; rs[i].type != -1; i++)
4470 		res[i] = NULL;
4471 	for (i = 0; rs[i].type != -1; i++) {
4472 		res[i] = bus_alloc_resource_any(dev,
4473 		    rs[i].type, &rs[i].rid, rs[i].flags);
4474 		if (res[i] == NULL && !(rs[i].flags & RF_OPTIONAL)) {
4475 			bus_release_resources(dev, rs, res);
4476 			return (ENXIO);
4477 		}
4478 	}
4479 	return (0);
4480 }
4481 
4482 void
4483 bus_release_resources(device_t dev, const struct resource_spec *rs,
4484     struct resource **res)
4485 {
4486 	int i;
4487 
4488 	for (i = 0; rs[i].type != -1; i++)
4489 		if (res[i] != NULL) {
4490 			bus_release_resource(
4491 			    dev, rs[i].type, rs[i].rid, res[i]);
4492 			res[i] = NULL;
4493 		}
4494 }
4495 
4496 /**
4497  * @brief Wrapper function for BUS_ALLOC_RESOURCE().
4498  *
4499  * This function simply calls the BUS_ALLOC_RESOURCE() method of the
4500  * parent of @p dev.
4501  */
4502 struct resource *
4503 bus_alloc_resource(device_t dev, int type, int *rid, rman_res_t start,
4504     rman_res_t end, rman_res_t count, u_int flags)
4505 {
4506 	struct resource *res;
4507 
4508 	if (dev->parent == NULL)
4509 		return (NULL);
4510 	res = BUS_ALLOC_RESOURCE(dev->parent, dev, type, rid, start, end,
4511 	    count, flags);
4512 	return (res);
4513 }
4514 
4515 /**
4516  * @brief Wrapper function for BUS_ADJUST_RESOURCE().
4517  *
4518  * This function simply calls the BUS_ADJUST_RESOURCE() method of the
4519  * parent of @p dev.
4520  */
4521 int
4522 bus_adjust_resource(device_t dev, int type, struct resource *r, rman_res_t start,
4523     rman_res_t end)
4524 {
4525 	if (dev->parent == NULL)
4526 		return (EINVAL);
4527 	return (BUS_ADJUST_RESOURCE(dev->parent, dev, type, r, start, end));
4528 }
4529 
4530 /**
4531  * @brief Wrapper function for BUS_TRANSLATE_RESOURCE().
4532  *
4533  * This function simply calls the BUS_TRANSLATE_RESOURCE() method of the
4534  * parent of @p dev.
4535  */
4536 int
4537 bus_translate_resource(device_t dev, int type, rman_res_t start,
4538     rman_res_t *newstart)
4539 {
4540 	if (dev->parent == NULL)
4541 		return (EINVAL);
4542 	return (BUS_TRANSLATE_RESOURCE(dev->parent, type, start, newstart));
4543 }
4544 
4545 /**
4546  * @brief Wrapper function for BUS_ACTIVATE_RESOURCE().
4547  *
4548  * This function simply calls the BUS_ACTIVATE_RESOURCE() method of the
4549  * parent of @p dev.
4550  */
4551 int
4552 bus_activate_resource(device_t dev, int type, int rid, struct resource *r)
4553 {
4554 	if (dev->parent == NULL)
4555 		return (EINVAL);
4556 	return (BUS_ACTIVATE_RESOURCE(dev->parent, dev, type, rid, r));
4557 }
4558 
4559 /**
4560  * @brief Wrapper function for BUS_DEACTIVATE_RESOURCE().
4561  *
4562  * This function simply calls the BUS_DEACTIVATE_RESOURCE() method of the
4563  * parent of @p dev.
4564  */
4565 int
4566 bus_deactivate_resource(device_t dev, int type, int rid, struct resource *r)
4567 {
4568 	if (dev->parent == NULL)
4569 		return (EINVAL);
4570 	return (BUS_DEACTIVATE_RESOURCE(dev->parent, dev, type, rid, r));
4571 }
4572 
4573 /**
4574  * @brief Wrapper function for BUS_MAP_RESOURCE().
4575  *
4576  * This function simply calls the BUS_MAP_RESOURCE() method of the
4577  * parent of @p dev.
4578  */
4579 int
4580 bus_map_resource(device_t dev, int type, struct resource *r,
4581     struct resource_map_request *args, struct resource_map *map)
4582 {
4583 	if (dev->parent == NULL)
4584 		return (EINVAL);
4585 	return (BUS_MAP_RESOURCE(dev->parent, dev, type, r, args, map));
4586 }
4587 
4588 /**
4589  * @brief Wrapper function for BUS_UNMAP_RESOURCE().
4590  *
4591  * This function simply calls the BUS_UNMAP_RESOURCE() method of the
4592  * parent of @p dev.
4593  */
4594 int
4595 bus_unmap_resource(device_t dev, int type, struct resource *r,
4596     struct resource_map *map)
4597 {
4598 	if (dev->parent == NULL)
4599 		return (EINVAL);
4600 	return (BUS_UNMAP_RESOURCE(dev->parent, dev, type, r, map));
4601 }
4602 
4603 /**
4604  * @brief Wrapper function for BUS_RELEASE_RESOURCE().
4605  *
4606  * This function simply calls the BUS_RELEASE_RESOURCE() method of the
4607  * parent of @p dev.
4608  */
4609 int
4610 bus_release_resource(device_t dev, int type, int rid, struct resource *r)
4611 {
4612 	int rv;
4613 
4614 	if (dev->parent == NULL)
4615 		return (EINVAL);
4616 	rv = BUS_RELEASE_RESOURCE(dev->parent, dev, type, rid, r);
4617 	return (rv);
4618 }
4619 
4620 /**
4621  * @brief Wrapper function for BUS_SETUP_INTR().
4622  *
4623  * This function simply calls the BUS_SETUP_INTR() method of the
4624  * parent of @p dev.
4625  */
4626 int
4627 bus_setup_intr(device_t dev, struct resource *r, int flags,
4628     driver_filter_t filter, driver_intr_t handler, void *arg, void **cookiep)
4629 {
4630 	int error;
4631 
4632 	if (dev->parent == NULL)
4633 		return (EINVAL);
4634 	error = BUS_SETUP_INTR(dev->parent, dev, r, flags, filter, handler,
4635 	    arg, cookiep);
4636 	if (error != 0)
4637 		return (error);
4638 	if (handler != NULL && !(flags & INTR_MPSAFE))
4639 		device_printf(dev, "[GIANT-LOCKED]\n");
4640 	return (0);
4641 }
4642 
4643 /**
4644  * @brief Wrapper function for BUS_TEARDOWN_INTR().
4645  *
4646  * This function simply calls the BUS_TEARDOWN_INTR() method of the
4647  * parent of @p dev.
4648  */
4649 int
4650 bus_teardown_intr(device_t dev, struct resource *r, void *cookie)
4651 {
4652 	if (dev->parent == NULL)
4653 		return (EINVAL);
4654 	return (BUS_TEARDOWN_INTR(dev->parent, dev, r, cookie));
4655 }
4656 
4657 /**
4658  * @brief Wrapper function for BUS_SUSPEND_INTR().
4659  *
4660  * This function simply calls the BUS_SUSPEND_INTR() method of the
4661  * parent of @p dev.
4662  */
4663 int
4664 bus_suspend_intr(device_t dev, struct resource *r)
4665 {
4666 	if (dev->parent == NULL)
4667 		return (EINVAL);
4668 	return (BUS_SUSPEND_INTR(dev->parent, dev, r));
4669 }
4670 
4671 /**
4672  * @brief Wrapper function for BUS_RESUME_INTR().
4673  *
4674  * This function simply calls the BUS_RESUME_INTR() method of the
4675  * parent of @p dev.
4676  */
4677 int
4678 bus_resume_intr(device_t dev, struct resource *r)
4679 {
4680 	if (dev->parent == NULL)
4681 		return (EINVAL);
4682 	return (BUS_RESUME_INTR(dev->parent, dev, r));
4683 }
4684 
4685 /**
4686  * @brief Wrapper function for BUS_BIND_INTR().
4687  *
4688  * This function simply calls the BUS_BIND_INTR() method of the
4689  * parent of @p dev.
4690  */
4691 int
4692 bus_bind_intr(device_t dev, struct resource *r, int cpu)
4693 {
4694 	if (dev->parent == NULL)
4695 		return (EINVAL);
4696 	return (BUS_BIND_INTR(dev->parent, dev, r, cpu));
4697 }
4698 
4699 /**
4700  * @brief Wrapper function for BUS_DESCRIBE_INTR().
4701  *
4702  * This function first formats the requested description into a
4703  * temporary buffer and then calls the BUS_DESCRIBE_INTR() method of
4704  * the parent of @p dev.
4705  */
4706 int
4707 bus_describe_intr(device_t dev, struct resource *irq, void *cookie,
4708     const char *fmt, ...)
4709 {
4710 	va_list ap;
4711 	char descr[MAXCOMLEN + 1];
4712 
4713 	if (dev->parent == NULL)
4714 		return (EINVAL);
4715 	va_start(ap, fmt);
4716 	vsnprintf(descr, sizeof(descr), fmt, ap);
4717 	va_end(ap);
4718 	return (BUS_DESCRIBE_INTR(dev->parent, dev, irq, cookie, descr));
4719 }
4720 
4721 /**
4722  * @brief Wrapper function for BUS_SET_RESOURCE().
4723  *
4724  * This function simply calls the BUS_SET_RESOURCE() method of the
4725  * parent of @p dev.
4726  */
4727 int
4728 bus_set_resource(device_t dev, int type, int rid,
4729     rman_res_t start, rman_res_t count)
4730 {
4731 	return (BUS_SET_RESOURCE(device_get_parent(dev), dev, type, rid,
4732 	    start, count));
4733 }
4734 
4735 /**
4736  * @brief Wrapper function for BUS_GET_RESOURCE().
4737  *
4738  * This function simply calls the BUS_GET_RESOURCE() method of the
4739  * parent of @p dev.
4740  */
4741 int
4742 bus_get_resource(device_t dev, int type, int rid,
4743     rman_res_t *startp, rman_res_t *countp)
4744 {
4745 	return (BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4746 	    startp, countp));
4747 }
4748 
4749 /**
4750  * @brief Wrapper function for BUS_GET_RESOURCE().
4751  *
4752  * This function simply calls the BUS_GET_RESOURCE() method of the
4753  * parent of @p dev and returns the start value.
4754  */
4755 rman_res_t
4756 bus_get_resource_start(device_t dev, int type, int rid)
4757 {
4758 	rman_res_t start;
4759 	rman_res_t count;
4760 	int error;
4761 
4762 	error = BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4763 	    &start, &count);
4764 	if (error)
4765 		return (0);
4766 	return (start);
4767 }
4768 
4769 /**
4770  * @brief Wrapper function for BUS_GET_RESOURCE().
4771  *
4772  * This function simply calls the BUS_GET_RESOURCE() method of the
4773  * parent of @p dev and returns the count value.
4774  */
4775 rman_res_t
4776 bus_get_resource_count(device_t dev, int type, int rid)
4777 {
4778 	rman_res_t start;
4779 	rman_res_t count;
4780 	int error;
4781 
4782 	error = BUS_GET_RESOURCE(device_get_parent(dev), dev, type, rid,
4783 	    &start, &count);
4784 	if (error)
4785 		return (0);
4786 	return (count);
4787 }
4788 
4789 /**
4790  * @brief Wrapper function for BUS_DELETE_RESOURCE().
4791  *
4792  * This function simply calls the BUS_DELETE_RESOURCE() method of the
4793  * parent of @p dev.
4794  */
4795 void
4796 bus_delete_resource(device_t dev, int type, int rid)
4797 {
4798 	BUS_DELETE_RESOURCE(device_get_parent(dev), dev, type, rid);
4799 }
4800 
4801 /**
4802  * @brief Wrapper function for BUS_CHILD_PRESENT().
4803  *
4804  * This function simply calls the BUS_CHILD_PRESENT() method of the
4805  * parent of @p dev.
4806  */
4807 int
4808 bus_child_present(device_t child)
4809 {
4810 	return (BUS_CHILD_PRESENT(device_get_parent(child), child));
4811 }
4812 
4813 /**
4814  * @brief Wrapper function for BUS_CHILD_PNPINFO().
4815  *
4816  * This function simply calls the BUS_CHILD_PNPINFO() method of the parent of @p
4817  * dev.
4818  */
4819 int
4820 bus_child_pnpinfo(device_t child, struct sbuf *sb)
4821 {
4822 	device_t parent;
4823 
4824 	parent = device_get_parent(child);
4825 	if (parent == NULL)
4826 		return (0);
4827 	return (BUS_CHILD_PNPINFO(parent, child, sb));
4828 }
4829 
4830 /**
4831  * @brief Generic implementation that does nothing for bus_child_pnpinfo
4832  *
4833  * This function has the right signature and returns 0 since the sbuf is passed
4834  * to us to append to.
4835  */
4836 int
4837 bus_generic_child_pnpinfo(device_t dev, device_t child, struct sbuf *sb)
4838 {
4839 	return (0);
4840 }
4841 
4842 /**
4843  * @brief Wrapper function for BUS_CHILD_LOCATION().
4844  *
4845  * This function simply calls the BUS_CHILD_LOCATION() method of the parent of
4846  * @p dev.
4847  */
4848 int
4849 bus_child_location(device_t child, struct sbuf *sb)
4850 {
4851 	device_t parent;
4852 
4853 	parent = device_get_parent(child);
4854 	if (parent == NULL)
4855 		return (0);
4856 	return (BUS_CHILD_LOCATION(parent, child, sb));
4857 }
4858 
4859 /**
4860  * @brief Generic implementation that does nothing for bus_child_location
4861  *
4862  * This function has the right signature and returns 0 since the sbuf is passed
4863  * to us to append to.
4864  */
4865 int
4866 bus_generic_child_location(device_t dev, device_t child, struct sbuf *sb)
4867 {
4868 	return (0);
4869 }
4870 
4871 /**
4872  * @brief Wrapper function for BUS_GET_CPUS().
4873  *
4874  * This function simply calls the BUS_GET_CPUS() method of the
4875  * parent of @p dev.
4876  */
4877 int
4878 bus_get_cpus(device_t dev, enum cpu_sets op, size_t setsize, cpuset_t *cpuset)
4879 {
4880 	device_t parent;
4881 
4882 	parent = device_get_parent(dev);
4883 	if (parent == NULL)
4884 		return (EINVAL);
4885 	return (BUS_GET_CPUS(parent, dev, op, setsize, cpuset));
4886 }
4887 
4888 /**
4889  * @brief Wrapper function for BUS_GET_DMA_TAG().
4890  *
4891  * This function simply calls the BUS_GET_DMA_TAG() method of the
4892  * parent of @p dev.
4893  */
4894 bus_dma_tag_t
4895 bus_get_dma_tag(device_t dev)
4896 {
4897 	device_t parent;
4898 
4899 	parent = device_get_parent(dev);
4900 	if (parent == NULL)
4901 		return (NULL);
4902 	return (BUS_GET_DMA_TAG(parent, dev));
4903 }
4904 
4905 /**
4906  * @brief Wrapper function for BUS_GET_BUS_TAG().
4907  *
4908  * This function simply calls the BUS_GET_BUS_TAG() method of the
4909  * parent of @p dev.
4910  */
4911 bus_space_tag_t
4912 bus_get_bus_tag(device_t dev)
4913 {
4914 	device_t parent;
4915 
4916 	parent = device_get_parent(dev);
4917 	if (parent == NULL)
4918 		return ((bus_space_tag_t)0);
4919 	return (BUS_GET_BUS_TAG(parent, dev));
4920 }
4921 
4922 /**
4923  * @brief Wrapper function for BUS_GET_DOMAIN().
4924  *
4925  * This function simply calls the BUS_GET_DOMAIN() method of the
4926  * parent of @p dev.
4927  */
4928 int
4929 bus_get_domain(device_t dev, int *domain)
4930 {
4931 	return (BUS_GET_DOMAIN(device_get_parent(dev), dev, domain));
4932 }
4933 
4934 /* Resume all devices and then notify userland that we're up again. */
4935 static int
4936 root_resume(device_t dev)
4937 {
4938 	int error;
4939 
4940 	error = bus_generic_resume(dev);
4941 	if (error == 0) {
4942 		devctl_notify("kernel", "power", "resume", NULL);
4943 	}
4944 	return (error);
4945 }
4946 
4947 static int
4948 root_print_child(device_t dev, device_t child)
4949 {
4950 	int	retval = 0;
4951 
4952 	retval += bus_print_child_header(dev, child);
4953 	retval += printf("\n");
4954 
4955 	return (retval);
4956 }
4957 
4958 static int
4959 root_setup_intr(device_t dev, device_t child, struct resource *irq, int flags,
4960     driver_filter_t *filter, driver_intr_t *intr, void *arg, void **cookiep)
4961 {
4962 	/*
4963 	 * If an interrupt mapping gets to here something bad has happened.
4964 	 */
4965 	panic("root_setup_intr");
4966 }
4967 
4968 /*
4969  * If we get here, assume that the device is permanent and really is
4970  * present in the system.  Removable bus drivers are expected to intercept
4971  * this call long before it gets here.  We return -1 so that drivers that
4972  * really care can check vs -1 or some ERRNO returned higher in the food
4973  * chain.
4974  */
4975 static int
4976 root_child_present(device_t dev, device_t child)
4977 {
4978 	return (-1);
4979 }
4980 
4981 static int
4982 root_get_cpus(device_t dev, device_t child, enum cpu_sets op, size_t setsize,
4983     cpuset_t *cpuset)
4984 {
4985 	switch (op) {
4986 	case INTR_CPUS:
4987 		/* Default to returning the set of all CPUs. */
4988 		if (setsize != sizeof(cpuset_t))
4989 			return (EINVAL);
4990 		*cpuset = all_cpus;
4991 		return (0);
4992 	default:
4993 		return (EINVAL);
4994 	}
4995 }
4996 
4997 static kobj_method_t root_methods[] = {
4998 	/* Device interface */
4999 	KOBJMETHOD(device_shutdown,	bus_generic_shutdown),
5000 	KOBJMETHOD(device_suspend,	bus_generic_suspend),
5001 	KOBJMETHOD(device_resume,	root_resume),
5002 
5003 	/* Bus interface */
5004 	KOBJMETHOD(bus_print_child,	root_print_child),
5005 	KOBJMETHOD(bus_read_ivar,	bus_generic_read_ivar),
5006 	KOBJMETHOD(bus_write_ivar,	bus_generic_write_ivar),
5007 	KOBJMETHOD(bus_setup_intr,	root_setup_intr),
5008 	KOBJMETHOD(bus_child_present,	root_child_present),
5009 	KOBJMETHOD(bus_get_cpus,	root_get_cpus),
5010 
5011 	KOBJMETHOD_END
5012 };
5013 
5014 static driver_t root_driver = {
5015 	"root",
5016 	root_methods,
5017 	1,			/* no softc */
5018 };
5019 
5020 device_t	root_bus;
5021 devclass_t	root_devclass;
5022 
5023 static int
5024 root_bus_module_handler(module_t mod, int what, void* arg)
5025 {
5026 	switch (what) {
5027 	case MOD_LOAD:
5028 		TAILQ_INIT(&bus_data_devices);
5029 		kobj_class_compile((kobj_class_t) &root_driver);
5030 		root_bus = make_device(NULL, "root", 0);
5031 		root_bus->desc = "System root bus";
5032 		kobj_init((kobj_t) root_bus, (kobj_class_t) &root_driver);
5033 		root_bus->driver = &root_driver;
5034 		root_bus->state = DS_ATTACHED;
5035 		root_devclass = devclass_find_internal("root", NULL, FALSE);
5036 		devctl2_init();
5037 		return (0);
5038 
5039 	case MOD_SHUTDOWN:
5040 		device_shutdown(root_bus);
5041 		return (0);
5042 	default:
5043 		return (EOPNOTSUPP);
5044 	}
5045 
5046 	return (0);
5047 }
5048 
5049 static moduledata_t root_bus_mod = {
5050 	"rootbus",
5051 	root_bus_module_handler,
5052 	NULL
5053 };
5054 DECLARE_MODULE(rootbus, root_bus_mod, SI_SUB_DRIVERS, SI_ORDER_FIRST);
5055 
5056 /**
5057  * @brief Automatically configure devices
5058  *
5059  * This function begins the autoconfiguration process by calling
5060  * device_probe_and_attach() for each child of the @c root0 device.
5061  */
5062 void
5063 root_bus_configure(void)
5064 {
5065 	PDEBUG(("."));
5066 
5067 	/* Eventually this will be split up, but this is sufficient for now. */
5068 	bus_set_pass(BUS_PASS_DEFAULT);
5069 }
5070 
5071 /**
5072  * @brief Module handler for registering device drivers
5073  *
5074  * This module handler is used to automatically register device
5075  * drivers when modules are loaded. If @p what is MOD_LOAD, it calls
5076  * devclass_add_driver() for the driver described by the
5077  * driver_module_data structure pointed to by @p arg
5078  */
5079 int
5080 driver_module_handler(module_t mod, int what, void *arg)
5081 {
5082 	struct driver_module_data *dmd;
5083 	devclass_t bus_devclass;
5084 	kobj_class_t driver;
5085 	int error, pass;
5086 
5087 	dmd = (struct driver_module_data *)arg;
5088 	bus_devclass = devclass_find_internal(dmd->dmd_busname, NULL, TRUE);
5089 	error = 0;
5090 
5091 	switch (what) {
5092 	case MOD_LOAD:
5093 		if (dmd->dmd_chainevh)
5094 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
5095 
5096 		pass = dmd->dmd_pass;
5097 		driver = dmd->dmd_driver;
5098 		PDEBUG(("Loading module: driver %s on bus %s (pass %d)",
5099 		    DRIVERNAME(driver), dmd->dmd_busname, pass));
5100 		error = devclass_add_driver(bus_devclass, driver, pass,
5101 		    dmd->dmd_devclass);
5102 		break;
5103 
5104 	case MOD_UNLOAD:
5105 		PDEBUG(("Unloading module: driver %s from bus %s",
5106 		    DRIVERNAME(dmd->dmd_driver),
5107 		    dmd->dmd_busname));
5108 		error = devclass_delete_driver(bus_devclass,
5109 		    dmd->dmd_driver);
5110 
5111 		if (!error && dmd->dmd_chainevh)
5112 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
5113 		break;
5114 	case MOD_QUIESCE:
5115 		PDEBUG(("Quiesce module: driver %s from bus %s",
5116 		    DRIVERNAME(dmd->dmd_driver),
5117 		    dmd->dmd_busname));
5118 		error = devclass_quiesce_driver(bus_devclass,
5119 		    dmd->dmd_driver);
5120 
5121 		if (!error && dmd->dmd_chainevh)
5122 			error = dmd->dmd_chainevh(mod,what,dmd->dmd_chainarg);
5123 		break;
5124 	default:
5125 		error = EOPNOTSUPP;
5126 		break;
5127 	}
5128 
5129 	return (error);
5130 }
5131 
5132 /**
5133  * @brief Enumerate all hinted devices for this bus.
5134  *
5135  * Walks through the hints for this bus and calls the bus_hinted_child
5136  * routine for each one it fines.  It searches first for the specific
5137  * bus that's being probed for hinted children (eg isa0), and then for
5138  * generic children (eg isa).
5139  *
5140  * @param	dev	bus device to enumerate
5141  */
5142 void
5143 bus_enumerate_hinted_children(device_t bus)
5144 {
5145 	int i;
5146 	const char *dname, *busname;
5147 	int dunit;
5148 
5149 	/*
5150 	 * enumerate all devices on the specific bus
5151 	 */
5152 	busname = device_get_nameunit(bus);
5153 	i = 0;
5154 	while (resource_find_match(&i, &dname, &dunit, "at", busname) == 0)
5155 		BUS_HINTED_CHILD(bus, dname, dunit);
5156 
5157 	/*
5158 	 * and all the generic ones.
5159 	 */
5160 	busname = device_get_name(bus);
5161 	i = 0;
5162 	while (resource_find_match(&i, &dname, &dunit, "at", busname) == 0)
5163 		BUS_HINTED_CHILD(bus, dname, dunit);
5164 }
5165 
5166 #ifdef BUS_DEBUG
5167 
5168 /* the _short versions avoid iteration by not calling anything that prints
5169  * more than oneliners. I love oneliners.
5170  */
5171 
5172 static void
5173 print_device_short(device_t dev, int indent)
5174 {
5175 	if (!dev)
5176 		return;
5177 
5178 	indentprintf(("device %d: <%s> %sparent,%schildren,%s%s%s%s%s,%sivars,%ssoftc,busy=%d\n",
5179 	    dev->unit, dev->desc,
5180 	    (dev->parent? "":"no "),
5181 	    (TAILQ_EMPTY(&dev->children)? "no ":""),
5182 	    (dev->flags&DF_ENABLED? "enabled,":"disabled,"),
5183 	    (dev->flags&DF_FIXEDCLASS? "fixed,":""),
5184 	    (dev->flags&DF_WILDCARD? "wildcard,":""),
5185 	    (dev->flags&DF_DESCMALLOCED? "descmalloced,":""),
5186 	    (dev->flags&DF_SUSPENDED? "suspended,":""),
5187 	    (dev->ivars? "":"no "),
5188 	    (dev->softc? "":"no "),
5189 	    dev->busy));
5190 }
5191 
5192 static void
5193 print_device(device_t dev, int indent)
5194 {
5195 	if (!dev)
5196 		return;
5197 
5198 	print_device_short(dev, indent);
5199 
5200 	indentprintf(("Parent:\n"));
5201 	print_device_short(dev->parent, indent+1);
5202 	indentprintf(("Driver:\n"));
5203 	print_driver_short(dev->driver, indent+1);
5204 	indentprintf(("Devclass:\n"));
5205 	print_devclass_short(dev->devclass, indent+1);
5206 }
5207 
5208 void
5209 print_device_tree_short(device_t dev, int indent)
5210 /* print the device and all its children (indented) */
5211 {
5212 	device_t child;
5213 
5214 	if (!dev)
5215 		return;
5216 
5217 	print_device_short(dev, indent);
5218 
5219 	TAILQ_FOREACH(child, &dev->children, link) {
5220 		print_device_tree_short(child, indent+1);
5221 	}
5222 }
5223 
5224 void
5225 print_device_tree(device_t dev, int indent)
5226 /* print the device and all its children (indented) */
5227 {
5228 	device_t child;
5229 
5230 	if (!dev)
5231 		return;
5232 
5233 	print_device(dev, indent);
5234 
5235 	TAILQ_FOREACH(child, &dev->children, link) {
5236 		print_device_tree(child, indent+1);
5237 	}
5238 }
5239 
5240 static void
5241 print_driver_short(driver_t *driver, int indent)
5242 {
5243 	if (!driver)
5244 		return;
5245 
5246 	indentprintf(("driver %s: softc size = %zd\n",
5247 	    driver->name, driver->size));
5248 }
5249 
5250 static void
5251 print_driver(driver_t *driver, int indent)
5252 {
5253 	if (!driver)
5254 		return;
5255 
5256 	print_driver_short(driver, indent);
5257 }
5258 
5259 static void
5260 print_driver_list(driver_list_t drivers, int indent)
5261 {
5262 	driverlink_t driver;
5263 
5264 	TAILQ_FOREACH(driver, &drivers, link) {
5265 		print_driver(driver->driver, indent);
5266 	}
5267 }
5268 
5269 static void
5270 print_devclass_short(devclass_t dc, int indent)
5271 {
5272 	if ( !dc )
5273 		return;
5274 
5275 	indentprintf(("devclass %s: max units = %d\n", dc->name, dc->maxunit));
5276 }
5277 
5278 static void
5279 print_devclass(devclass_t dc, int indent)
5280 {
5281 	int i;
5282 
5283 	if ( !dc )
5284 		return;
5285 
5286 	print_devclass_short(dc, indent);
5287 	indentprintf(("Drivers:\n"));
5288 	print_driver_list(dc->drivers, indent+1);
5289 
5290 	indentprintf(("Devices:\n"));
5291 	for (i = 0; i < dc->maxunit; i++)
5292 		if (dc->devices[i])
5293 			print_device(dc->devices[i], indent+1);
5294 }
5295 
5296 void
5297 print_devclass_list_short(void)
5298 {
5299 	devclass_t dc;
5300 
5301 	printf("Short listing of devclasses, drivers & devices:\n");
5302 	TAILQ_FOREACH(dc, &devclasses, link) {
5303 		print_devclass_short(dc, 0);
5304 	}
5305 }
5306 
5307 void
5308 print_devclass_list(void)
5309 {
5310 	devclass_t dc;
5311 
5312 	printf("Full listing of devclasses, drivers & devices:\n");
5313 	TAILQ_FOREACH(dc, &devclasses, link) {
5314 		print_devclass(dc, 0);
5315 	}
5316 }
5317 
5318 #endif
5319 
5320 /*
5321  * User-space access to the device tree.
5322  *
5323  * We implement a small set of nodes:
5324  *
5325  * hw.bus			Single integer read method to obtain the
5326  *				current generation count.
5327  * hw.bus.devices		Reads the entire device tree in flat space.
5328  * hw.bus.rman			Resource manager interface
5329  *
5330  * We might like to add the ability to scan devclasses and/or drivers to
5331  * determine what else is currently loaded/available.
5332  */
5333 
5334 static int
5335 sysctl_bus_info(SYSCTL_HANDLER_ARGS)
5336 {
5337 	struct u_businfo	ubus;
5338 
5339 	ubus.ub_version = BUS_USER_VERSION;
5340 	ubus.ub_generation = bus_data_generation;
5341 
5342 	return (SYSCTL_OUT(req, &ubus, sizeof(ubus)));
5343 }
5344 SYSCTL_PROC(_hw_bus, OID_AUTO, info, CTLTYPE_STRUCT | CTLFLAG_RD |
5345     CTLFLAG_MPSAFE, NULL, 0, sysctl_bus_info, "S,u_businfo",
5346     "bus-related data");
5347 
5348 static int
5349 sysctl_devices(SYSCTL_HANDLER_ARGS)
5350 {
5351 	struct sbuf		sb;
5352 	int			*name = (int *)arg1;
5353 	u_int			namelen = arg2;
5354 	int			index;
5355 	device_t		dev;
5356 	struct u_device		*udev;
5357 	int			error;
5358 
5359 	if (namelen != 2)
5360 		return (EINVAL);
5361 
5362 	if (bus_data_generation_check(name[0]))
5363 		return (EINVAL);
5364 
5365 	index = name[1];
5366 
5367 	/*
5368 	 * Scan the list of devices, looking for the requested index.
5369 	 */
5370 	TAILQ_FOREACH(dev, &bus_data_devices, devlink) {
5371 		if (index-- == 0)
5372 			break;
5373 	}
5374 	if (dev == NULL)
5375 		return (ENOENT);
5376 
5377 	/*
5378 	 * Populate the return item, careful not to overflow the buffer.
5379 	 */
5380 	udev = malloc(sizeof(*udev), M_BUS, M_WAITOK | M_ZERO);
5381 	if (udev == NULL)
5382 		return (ENOMEM);
5383 	udev->dv_handle = (uintptr_t)dev;
5384 	udev->dv_parent = (uintptr_t)dev->parent;
5385 	udev->dv_devflags = dev->devflags;
5386 	udev->dv_flags = dev->flags;
5387 	udev->dv_state = dev->state;
5388 	sbuf_new(&sb, udev->dv_fields, sizeof(udev->dv_fields), SBUF_FIXEDLEN);
5389 	if (dev->nameunit != NULL)
5390 		sbuf_cat(&sb, dev->nameunit);
5391 	sbuf_putc(&sb, '\0');
5392 	if (dev->desc != NULL)
5393 		sbuf_cat(&sb, dev->desc);
5394 	sbuf_putc(&sb, '\0');
5395 	if (dev->driver != NULL)
5396 		sbuf_cat(&sb, dev->driver->name);
5397 	sbuf_putc(&sb, '\0');
5398 	bus_child_pnpinfo(dev, &sb);
5399 	sbuf_putc(&sb, '\0');
5400 	bus_child_location(dev, &sb);
5401 	sbuf_putc(&sb, '\0');
5402 	error = sbuf_finish(&sb);
5403 	if (error == 0)
5404 		error = SYSCTL_OUT(req, udev, sizeof(*udev));
5405 	sbuf_delete(&sb);
5406 	free(udev, M_BUS);
5407 	return (error);
5408 }
5409 
5410 SYSCTL_NODE(_hw_bus, OID_AUTO, devices,
5411     CTLFLAG_RD | CTLFLAG_NEEDGIANT, sysctl_devices,
5412     "system device tree");
5413 
5414 int
5415 bus_data_generation_check(int generation)
5416 {
5417 	if (generation != bus_data_generation)
5418 		return (1);
5419 
5420 	/* XXX generate optimised lists here? */
5421 	return (0);
5422 }
5423 
5424 void
5425 bus_data_generation_update(void)
5426 {
5427 	atomic_add_int(&bus_data_generation, 1);
5428 }
5429 
5430 int
5431 bus_free_resource(device_t dev, int type, struct resource *r)
5432 {
5433 	if (r == NULL)
5434 		return (0);
5435 	return (bus_release_resource(dev, type, rman_get_rid(r), r));
5436 }
5437 
5438 device_t
5439 device_lookup_by_name(const char *name)
5440 {
5441 	device_t dev;
5442 
5443 	TAILQ_FOREACH(dev, &bus_data_devices, devlink) {
5444 		if (dev->nameunit != NULL && strcmp(dev->nameunit, name) == 0)
5445 			return (dev);
5446 	}
5447 	return (NULL);
5448 }
5449 
5450 /*
5451  * /dev/devctl2 implementation.  The existing /dev/devctl device has
5452  * implicit semantics on open, so it could not be reused for this.
5453  * Another option would be to call this /dev/bus?
5454  */
5455 static int
5456 find_device(struct devreq *req, device_t *devp)
5457 {
5458 	device_t dev;
5459 
5460 	/*
5461 	 * First, ensure that the name is nul terminated.
5462 	 */
5463 	if (memchr(req->dr_name, '\0', sizeof(req->dr_name)) == NULL)
5464 		return (EINVAL);
5465 
5466 	/*
5467 	 * Second, try to find an attached device whose name matches
5468 	 * 'name'.
5469 	 */
5470 	dev = device_lookup_by_name(req->dr_name);
5471 	if (dev != NULL) {
5472 		*devp = dev;
5473 		return (0);
5474 	}
5475 
5476 	/* Finally, give device enumerators a chance. */
5477 	dev = NULL;
5478 	EVENTHANDLER_DIRECT_INVOKE(dev_lookup, req->dr_name, &dev);
5479 	if (dev == NULL)
5480 		return (ENOENT);
5481 	*devp = dev;
5482 	return (0);
5483 }
5484 
5485 static bool
5486 driver_exists(device_t bus, const char *driver)
5487 {
5488 	devclass_t dc;
5489 
5490 	for (dc = bus->devclass; dc != NULL; dc = dc->parent) {
5491 		if (devclass_find_driver_internal(dc, driver) != NULL)
5492 			return (true);
5493 	}
5494 	return (false);
5495 }
5496 
5497 static void
5498 device_gen_nomatch(device_t dev)
5499 {
5500 	device_t child;
5501 
5502 	if (dev->flags & DF_NEEDNOMATCH &&
5503 	    dev->state == DS_NOTPRESENT) {
5504 		device_handle_nomatch(dev);
5505 	}
5506 	dev->flags &= ~DF_NEEDNOMATCH;
5507 	TAILQ_FOREACH(child, &dev->children, link) {
5508 		device_gen_nomatch(child);
5509 	}
5510 }
5511 
5512 static void
5513 device_do_deferred_actions(void)
5514 {
5515 	devclass_t dc;
5516 	driverlink_t dl;
5517 
5518 	/*
5519 	 * Walk through the devclasses to find all the drivers we've tagged as
5520 	 * deferred during the freeze and call the driver added routines. They
5521 	 * have already been added to the lists in the background, so the driver
5522 	 * added routines that trigger a probe will have all the right bidders
5523 	 * for the probe auction.
5524 	 */
5525 	TAILQ_FOREACH(dc, &devclasses, link) {
5526 		TAILQ_FOREACH(dl, &dc->drivers, link) {
5527 			if (dl->flags & DL_DEFERRED_PROBE) {
5528 				devclass_driver_added(dc, dl->driver);
5529 				dl->flags &= ~DL_DEFERRED_PROBE;
5530 			}
5531 		}
5532 	}
5533 
5534 	/*
5535 	 * We also defer no-match events during a freeze. Walk the tree and
5536 	 * generate all the pent-up events that are still relevant.
5537 	 */
5538 	device_gen_nomatch(root_bus);
5539 	bus_data_generation_update();
5540 }
5541 
5542 static int
5543 device_get_path(device_t dev, const char *locator, struct sbuf *sb)
5544 {
5545 	device_t parent;
5546 	int error;
5547 
5548 	KASSERT(sb != NULL, ("sb is NULL"));
5549 	parent = device_get_parent(dev);
5550 	if (parent == NULL) {
5551 		error = sbuf_putc(sb, '/');
5552 	} else {
5553 		error = BUS_GET_DEVICE_PATH(parent, dev, locator, sb);
5554 		if (error == 0) {
5555 			error = sbuf_error(sb);
5556 			if (error == 0 && sbuf_len(sb) <= 1)
5557 				error = EIO;
5558 		}
5559 	}
5560 	sbuf_finish(sb);
5561 	return (error);
5562 }
5563 
5564 static int
5565 devctl2_ioctl(struct cdev *cdev, u_long cmd, caddr_t data, int fflag,
5566     struct thread *td)
5567 {
5568 	struct devreq *req;
5569 	device_t dev;
5570 	int error, old;
5571 
5572 	/* Locate the device to control. */
5573 	bus_topo_lock();
5574 	req = (struct devreq *)data;
5575 	switch (cmd) {
5576 	case DEV_ATTACH:
5577 	case DEV_DETACH:
5578 	case DEV_ENABLE:
5579 	case DEV_DISABLE:
5580 	case DEV_SUSPEND:
5581 	case DEV_RESUME:
5582 	case DEV_SET_DRIVER:
5583 	case DEV_CLEAR_DRIVER:
5584 	case DEV_RESCAN:
5585 	case DEV_DELETE:
5586 	case DEV_RESET:
5587 		error = priv_check(td, PRIV_DRIVER);
5588 		if (error == 0)
5589 			error = find_device(req, &dev);
5590 		break;
5591 	case DEV_FREEZE:
5592 	case DEV_THAW:
5593 		error = priv_check(td, PRIV_DRIVER);
5594 		break;
5595 	case DEV_GET_PATH:
5596 		error = find_device(req, &dev);
5597 		break;
5598 	default:
5599 		error = ENOTTY;
5600 		break;
5601 	}
5602 	if (error) {
5603 		bus_topo_unlock();
5604 		return (error);
5605 	}
5606 
5607 	/* Perform the requested operation. */
5608 	switch (cmd) {
5609 	case DEV_ATTACH:
5610 		if (device_is_attached(dev))
5611 			error = EBUSY;
5612 		else if (!device_is_enabled(dev))
5613 			error = ENXIO;
5614 		else
5615 			error = device_probe_and_attach(dev);
5616 		break;
5617 	case DEV_DETACH:
5618 		if (!device_is_attached(dev)) {
5619 			error = ENXIO;
5620 			break;
5621 		}
5622 		if (!(req->dr_flags & DEVF_FORCE_DETACH)) {
5623 			error = device_quiesce(dev);
5624 			if (error)
5625 				break;
5626 		}
5627 		error = device_detach(dev);
5628 		break;
5629 	case DEV_ENABLE:
5630 		if (device_is_enabled(dev)) {
5631 			error = EBUSY;
5632 			break;
5633 		}
5634 
5635 		/*
5636 		 * If the device has been probed but not attached (e.g.
5637 		 * when it has been disabled by a loader hint), just
5638 		 * attach the device rather than doing a full probe.
5639 		 */
5640 		device_enable(dev);
5641 		if (device_is_alive(dev)) {
5642 			/*
5643 			 * If the device was disabled via a hint, clear
5644 			 * the hint.
5645 			 */
5646 			if (resource_disabled(dev->driver->name, dev->unit))
5647 				resource_unset_value(dev->driver->name,
5648 				    dev->unit, "disabled");
5649 			error = device_attach(dev);
5650 		} else
5651 			error = device_probe_and_attach(dev);
5652 		break;
5653 	case DEV_DISABLE:
5654 		if (!device_is_enabled(dev)) {
5655 			error = ENXIO;
5656 			break;
5657 		}
5658 
5659 		if (!(req->dr_flags & DEVF_FORCE_DETACH)) {
5660 			error = device_quiesce(dev);
5661 			if (error)
5662 				break;
5663 		}
5664 
5665 		/*
5666 		 * Force DF_FIXEDCLASS on around detach to preserve
5667 		 * the existing name.
5668 		 */
5669 		old = dev->flags;
5670 		dev->flags |= DF_FIXEDCLASS;
5671 		error = device_detach(dev);
5672 		if (!(old & DF_FIXEDCLASS))
5673 			dev->flags &= ~DF_FIXEDCLASS;
5674 		if (error == 0)
5675 			device_disable(dev);
5676 		break;
5677 	case DEV_SUSPEND:
5678 		if (device_is_suspended(dev)) {
5679 			error = EBUSY;
5680 			break;
5681 		}
5682 		if (device_get_parent(dev) == NULL) {
5683 			error = EINVAL;
5684 			break;
5685 		}
5686 		error = BUS_SUSPEND_CHILD(device_get_parent(dev), dev);
5687 		break;
5688 	case DEV_RESUME:
5689 		if (!device_is_suspended(dev)) {
5690 			error = EINVAL;
5691 			break;
5692 		}
5693 		if (device_get_parent(dev) == NULL) {
5694 			error = EINVAL;
5695 			break;
5696 		}
5697 		error = BUS_RESUME_CHILD(device_get_parent(dev), dev);
5698 		break;
5699 	case DEV_SET_DRIVER: {
5700 		devclass_t dc;
5701 		char driver[128];
5702 
5703 		error = copyinstr(req->dr_data, driver, sizeof(driver), NULL);
5704 		if (error)
5705 			break;
5706 		if (driver[0] == '\0') {
5707 			error = EINVAL;
5708 			break;
5709 		}
5710 		if (dev->devclass != NULL &&
5711 		    strcmp(driver, dev->devclass->name) == 0)
5712 			/* XXX: Could possibly force DF_FIXEDCLASS on? */
5713 			break;
5714 
5715 		/*
5716 		 * Scan drivers for this device's bus looking for at
5717 		 * least one matching driver.
5718 		 */
5719 		if (dev->parent == NULL) {
5720 			error = EINVAL;
5721 			break;
5722 		}
5723 		if (!driver_exists(dev->parent, driver)) {
5724 			error = ENOENT;
5725 			break;
5726 		}
5727 		dc = devclass_create(driver);
5728 		if (dc == NULL) {
5729 			error = ENOMEM;
5730 			break;
5731 		}
5732 
5733 		/* Detach device if necessary. */
5734 		if (device_is_attached(dev)) {
5735 			if (req->dr_flags & DEVF_SET_DRIVER_DETACH)
5736 				error = device_detach(dev);
5737 			else
5738 				error = EBUSY;
5739 			if (error)
5740 				break;
5741 		}
5742 
5743 		/* Clear any previously-fixed device class and unit. */
5744 		if (dev->flags & DF_FIXEDCLASS)
5745 			devclass_delete_device(dev->devclass, dev);
5746 		dev->flags |= DF_WILDCARD;
5747 		dev->unit = -1;
5748 
5749 		/* Force the new device class. */
5750 		error = devclass_add_device(dc, dev);
5751 		if (error)
5752 			break;
5753 		dev->flags |= DF_FIXEDCLASS;
5754 		error = device_probe_and_attach(dev);
5755 		break;
5756 	}
5757 	case DEV_CLEAR_DRIVER:
5758 		if (!(dev->flags & DF_FIXEDCLASS)) {
5759 			error = 0;
5760 			break;
5761 		}
5762 		if (device_is_attached(dev)) {
5763 			if (req->dr_flags & DEVF_CLEAR_DRIVER_DETACH)
5764 				error = device_detach(dev);
5765 			else
5766 				error = EBUSY;
5767 			if (error)
5768 				break;
5769 		}
5770 
5771 		dev->flags &= ~DF_FIXEDCLASS;
5772 		dev->flags |= DF_WILDCARD;
5773 		devclass_delete_device(dev->devclass, dev);
5774 		error = device_probe_and_attach(dev);
5775 		break;
5776 	case DEV_RESCAN:
5777 		if (!device_is_attached(dev)) {
5778 			error = ENXIO;
5779 			break;
5780 		}
5781 		error = BUS_RESCAN(dev);
5782 		break;
5783 	case DEV_DELETE: {
5784 		device_t parent;
5785 
5786 		parent = device_get_parent(dev);
5787 		if (parent == NULL) {
5788 			error = EINVAL;
5789 			break;
5790 		}
5791 		if (!(req->dr_flags & DEVF_FORCE_DELETE)) {
5792 			if (bus_child_present(dev) != 0) {
5793 				error = EBUSY;
5794 				break;
5795 			}
5796 		}
5797 
5798 		error = device_delete_child(parent, dev);
5799 		break;
5800 	}
5801 	case DEV_FREEZE:
5802 		if (device_frozen)
5803 			error = EBUSY;
5804 		else
5805 			device_frozen = true;
5806 		break;
5807 	case DEV_THAW:
5808 		if (!device_frozen)
5809 			error = EBUSY;
5810 		else {
5811 			device_do_deferred_actions();
5812 			device_frozen = false;
5813 		}
5814 		break;
5815 	case DEV_RESET:
5816 		if ((req->dr_flags & ~(DEVF_RESET_DETACH)) != 0) {
5817 			error = EINVAL;
5818 			break;
5819 		}
5820 		error = BUS_RESET_CHILD(device_get_parent(dev), dev,
5821 		    req->dr_flags);
5822 		break;
5823 	case DEV_GET_PATH: {
5824 		struct sbuf *sb;
5825 		char locator[64];
5826 		ssize_t len;
5827 
5828 		error = copyinstr(req->dr_buffer.buffer, locator,
5829 		    sizeof(locator), NULL);
5830 		if (error != 0)
5831 			break;
5832 		sb = sbuf_new(NULL, NULL, 0, SBUF_AUTOEXTEND |
5833 		    SBUF_INCLUDENUL /* | SBUF_WAITOK */);
5834 		error = device_get_path(dev, locator, sb);
5835 		if (error == 0) {
5836 			len = sbuf_len(sb);
5837 			if (req->dr_buffer.length < len) {
5838 				error = ENAMETOOLONG;
5839 			} else {
5840 				error = copyout(sbuf_data(sb),
5841 				    req->dr_buffer.buffer, len);
5842 			}
5843 			req->dr_buffer.length = len;
5844 		}
5845 		sbuf_delete(sb);
5846 		break;
5847 	}
5848 	}
5849 	bus_topo_unlock();
5850 	return (error);
5851 }
5852 
5853 static struct cdevsw devctl2_cdevsw = {
5854 	.d_version =	D_VERSION,
5855 	.d_ioctl =	devctl2_ioctl,
5856 	.d_name =	"devctl2",
5857 };
5858 
5859 static void
5860 devctl2_init(void)
5861 {
5862 	make_dev_credf(MAKEDEV_ETERNAL, &devctl2_cdevsw, 0, NULL,
5863 	    UID_ROOT, GID_WHEEL, 0644, "devctl2");
5864 }
5865 
5866 /*
5867  * For maintaining device 'at' location info to avoid recomputing it
5868  */
5869 struct device_location_node {
5870 	const char *dln_locator;
5871 	const char *dln_path;
5872 	TAILQ_ENTRY(device_location_node) dln_link;
5873 };
5874 typedef TAILQ_HEAD(device_location_list, device_location_node) device_location_list_t;
5875 
5876 struct device_location_cache {
5877 	device_location_list_t dlc_list;
5878 };
5879 
5880 
5881 /*
5882  * Location cache for wired devices.
5883  */
5884 device_location_cache_t *
5885 dev_wired_cache_init(void)
5886 {
5887 	device_location_cache_t *dcp;
5888 
5889 	dcp = malloc(sizeof(*dcp), M_BUS, M_WAITOK | M_ZERO);
5890 	TAILQ_INIT(&dcp->dlc_list);
5891 
5892 	return (dcp);
5893 }
5894 
5895 void
5896 dev_wired_cache_fini(device_location_cache_t *dcp)
5897 {
5898 	struct device_location_node *dln, *tdln;
5899 
5900 	TAILQ_FOREACH_SAFE(dln, &dcp->dlc_list, dln_link, tdln) {
5901 		free(dln, M_BUS);
5902 	}
5903 	free(dcp, M_BUS);
5904 }
5905 
5906 static struct device_location_node *
5907 dev_wired_cache_lookup(device_location_cache_t *dcp, const char *locator)
5908 {
5909 	struct device_location_node *dln;
5910 
5911 	TAILQ_FOREACH(dln, &dcp->dlc_list, dln_link) {
5912 		if (strcmp(locator, dln->dln_locator) == 0)
5913 			return (dln);
5914 	}
5915 
5916 	return (NULL);
5917 }
5918 
5919 static struct device_location_node *
5920 dev_wired_cache_add(device_location_cache_t *dcp, const char *locator, const char *path)
5921 {
5922 	struct device_location_node *dln;
5923 	size_t loclen, pathlen;
5924 
5925 	loclen = strlen(locator) + 1;
5926 	pathlen = strlen(path) + 1;
5927 	dln = malloc(sizeof(*dln) + loclen + pathlen, M_BUS, M_WAITOK | M_ZERO);
5928 	dln->dln_locator = (char *)(dln + 1);
5929 	memcpy(__DECONST(char *, dln->dln_locator), locator, loclen);
5930 	dln->dln_path = dln->dln_locator + loclen;
5931 	memcpy(__DECONST(char *, dln->dln_path), path, pathlen);
5932 	TAILQ_INSERT_HEAD(&dcp->dlc_list, dln, dln_link);
5933 
5934 	return (dln);
5935 }
5936 
5937 bool
5938 dev_wired_cache_match(device_location_cache_t *dcp, device_t dev,
5939     const char *at)
5940 {
5941 	struct sbuf *sb;
5942 	const char *cp;
5943 	char locator[32];
5944 	int error, len;
5945 	struct device_location_node *res;
5946 
5947 	cp = strchr(at, ':');
5948 	if (cp == NULL)
5949 		return (false);
5950 	len = cp - at;
5951 	if (len > sizeof(locator) - 1)	/* Skip too long locator */
5952 		return (false);
5953 	memcpy(locator, at, len);
5954 	locator[len] = '\0';
5955 	cp++;
5956 
5957 	error = 0;
5958 	/* maybe cache this inside device_t and look that up, but not yet */
5959 	res = dev_wired_cache_lookup(dcp, locator);
5960 	if (res == NULL) {
5961 		sb = sbuf_new(NULL, NULL, 0, SBUF_AUTOEXTEND |
5962 		    SBUF_INCLUDENUL | SBUF_NOWAIT);
5963 		if (sb != NULL) {
5964 			error = device_get_path(dev, locator, sb);
5965 			if (error == 0) {
5966 				res = dev_wired_cache_add(dcp, locator,
5967 				    sbuf_data(sb));
5968 			}
5969 			sbuf_delete(sb);
5970 		}
5971 	}
5972 	if (error != 0 || res == NULL || res->dln_path == NULL)
5973 		return (false);
5974 
5975 	return (strcmp(res->dln_path, cp) == 0);
5976 }
5977 
5978 /*
5979  * APIs to manage deprecation and obsolescence.
5980  */
5981 static int obsolete_panic = 0;
5982 SYSCTL_INT(_debug, OID_AUTO, obsolete_panic, CTLFLAG_RWTUN, &obsolete_panic, 0,
5983     "Panic when obsolete features are used (0 = never, 1 = if obsolete, "
5984     "2 = if deprecated)");
5985 
5986 static void
5987 gone_panic(int major, int running, const char *msg)
5988 {
5989 	switch (obsolete_panic)
5990 	{
5991 	case 0:
5992 		return;
5993 	case 1:
5994 		if (running < major)
5995 			return;
5996 		/* FALLTHROUGH */
5997 	default:
5998 		panic("%s", msg);
5999 	}
6000 }
6001 
6002 void
6003 _gone_in(int major, const char *msg)
6004 {
6005 	gone_panic(major, P_OSREL_MAJOR(__FreeBSD_version), msg);
6006 	if (P_OSREL_MAJOR(__FreeBSD_version) >= major)
6007 		printf("Obsolete code will be removed soon: %s\n", msg);
6008 	else
6009 		printf("Deprecated code (to be removed in FreeBSD %d): %s\n",
6010 		    major, msg);
6011 }
6012 
6013 void
6014 _gone_in_dev(device_t dev, int major, const char *msg)
6015 {
6016 	gone_panic(major, P_OSREL_MAJOR(__FreeBSD_version), msg);
6017 	if (P_OSREL_MAJOR(__FreeBSD_version) >= major)
6018 		device_printf(dev,
6019 		    "Obsolete code will be removed soon: %s\n", msg);
6020 	else
6021 		device_printf(dev,
6022 		    "Deprecated code (to be removed in FreeBSD %d): %s\n",
6023 		    major, msg);
6024 }
6025 
6026 #ifdef DDB
6027 DB_SHOW_COMMAND(device, db_show_device)
6028 {
6029 	device_t dev;
6030 
6031 	if (!have_addr)
6032 		return;
6033 
6034 	dev = (device_t)addr;
6035 
6036 	db_printf("name:    %s\n", device_get_nameunit(dev));
6037 	db_printf("  driver:  %s\n", DRIVERNAME(dev->driver));
6038 	db_printf("  class:   %s\n", DEVCLANAME(dev->devclass));
6039 	db_printf("  addr:    %p\n", dev);
6040 	db_printf("  parent:  %p\n", dev->parent);
6041 	db_printf("  softc:   %p\n", dev->softc);
6042 	db_printf("  ivars:   %p\n", dev->ivars);
6043 }
6044 
6045 DB_SHOW_ALL_COMMAND(devices, db_show_all_devices)
6046 {
6047 	device_t dev;
6048 
6049 	TAILQ_FOREACH(dev, &bus_data_devices, devlink) {
6050 		db_show_device((db_expr_t)dev, true, count, modif);
6051 	}
6052 }
6053 #endif
6054