xref: /freebsd/sys/dev/usb/usb_hub.c (revision aa0a1e58f0189b0fde359a8bda032887e72057fa)
1 /* $FreeBSD$ */
2 /*-
3  * Copyright (c) 1998 The NetBSD Foundation, Inc. All rights reserved.
4  * Copyright (c) 1998 Lennart Augustsson. All rights reserved.
5  * Copyright (c) 2008-2010 Hans Petter Selasky. 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 /*
30  * USB spec: http://www.usb.org/developers/docs/usbspec.zip
31  */
32 
33 #include <sys/stdint.h>
34 #include <sys/stddef.h>
35 #include <sys/param.h>
36 #include <sys/queue.h>
37 #include <sys/types.h>
38 #include <sys/systm.h>
39 #include <sys/kernel.h>
40 #include <sys/bus.h>
41 #include <sys/module.h>
42 #include <sys/lock.h>
43 #include <sys/mutex.h>
44 #include <sys/condvar.h>
45 #include <sys/sysctl.h>
46 #include <sys/sx.h>
47 #include <sys/unistd.h>
48 #include <sys/callout.h>
49 #include <sys/malloc.h>
50 #include <sys/priv.h>
51 
52 #include <dev/usb/usb.h>
53 #include <dev/usb/usb_ioctl.h>
54 #include <dev/usb/usbdi.h>
55 #include <dev/usb/usbdi_util.h>
56 
57 #define	USB_DEBUG_VAR uhub_debug
58 
59 #include <dev/usb/usb_core.h>
60 #include <dev/usb/usb_process.h>
61 #include <dev/usb/usb_device.h>
62 #include <dev/usb/usb_request.h>
63 #include <dev/usb/usb_debug.h>
64 #include <dev/usb/usb_hub.h>
65 #include <dev/usb/usb_util.h>
66 #include <dev/usb/usb_busdma.h>
67 #include <dev/usb/usb_transfer.h>
68 #include <dev/usb/usb_dynamic.h>
69 
70 #include <dev/usb/usb_controller.h>
71 #include <dev/usb/usb_bus.h>
72 
73 #define	UHUB_INTR_INTERVAL 250		/* ms */
74 #define	UHUB_N_TRANSFER 1
75 
76 #ifdef USB_DEBUG
77 static int uhub_debug = 0;
78 
79 SYSCTL_NODE(_hw_usb, OID_AUTO, uhub, CTLFLAG_RW, 0, "USB HUB");
80 SYSCTL_INT(_hw_usb_uhub, OID_AUTO, debug, CTLFLAG_RW, &uhub_debug, 0,
81     "Debug level");
82 
83 TUNABLE_INT("hw.usb.uhub.debug", &uhub_debug);
84 #endif
85 
86 #if USB_HAVE_POWERD
87 static int usb_power_timeout = 30;	/* seconds */
88 
89 SYSCTL_INT(_hw_usb, OID_AUTO, power_timeout, CTLFLAG_RW,
90     &usb_power_timeout, 0, "USB power timeout");
91 #endif
92 
93 struct uhub_current_state {
94 	uint16_t port_change;
95 	uint16_t port_status;
96 };
97 
98 struct uhub_softc {
99 	struct uhub_current_state sc_st;/* current state */
100 	device_t sc_dev;		/* base device */
101 	struct mtx sc_mtx;		/* our mutex */
102 	struct usb_device *sc_udev;	/* USB device */
103 	struct usb_xfer *sc_xfer[UHUB_N_TRANSFER];	/* interrupt xfer */
104 	uint8_t	sc_flags;
105 #define	UHUB_FLAG_DID_EXPLORE 0x01
106 	char	sc_name[32];
107 };
108 
109 #define	UHUB_PROTO(sc) ((sc)->sc_udev->ddesc.bDeviceProtocol)
110 #define	UHUB_IS_HIGH_SPEED(sc) (UHUB_PROTO(sc) != UDPROTO_FSHUB)
111 #define	UHUB_IS_SINGLE_TT(sc) (UHUB_PROTO(sc) == UDPROTO_HSHUBSTT)
112 #define	UHUB_IS_SUPER_SPEED(sc) (UHUB_PROTO(sc) == UDPROTO_SSHUB)
113 
114 /* prototypes for type checking: */
115 
116 static device_probe_t uhub_probe;
117 static device_attach_t uhub_attach;
118 static device_detach_t uhub_detach;
119 static device_suspend_t uhub_suspend;
120 static device_resume_t uhub_resume;
121 
122 static bus_driver_added_t uhub_driver_added;
123 static bus_child_location_str_t uhub_child_location_string;
124 static bus_child_pnpinfo_str_t uhub_child_pnpinfo_string;
125 
126 static usb_callback_t uhub_intr_callback;
127 
128 static void usb_dev_resume_peer(struct usb_device *udev);
129 static void usb_dev_suspend_peer(struct usb_device *udev);
130 static uint8_t usb_peer_should_wakeup(struct usb_device *udev);
131 
132 static const struct usb_config uhub_config[UHUB_N_TRANSFER] = {
133 
134 	[0] = {
135 		.type = UE_INTERRUPT,
136 		.endpoint = UE_ADDR_ANY,
137 		.direction = UE_DIR_ANY,
138 		.timeout = 0,
139 		.flags = {.pipe_bof = 1,.short_xfer_ok = 1,},
140 		.bufsize = 0,	/* use wMaxPacketSize */
141 		.callback = &uhub_intr_callback,
142 		.interval = UHUB_INTR_INTERVAL,
143 	},
144 };
145 
146 /*
147  * driver instance for "hub" connected to "usb"
148  * and "hub" connected to "hub"
149  */
150 static devclass_t uhub_devclass;
151 
152 static device_method_t uhub_methods[] = {
153 	DEVMETHOD(device_probe, uhub_probe),
154 	DEVMETHOD(device_attach, uhub_attach),
155 	DEVMETHOD(device_detach, uhub_detach),
156 
157 	DEVMETHOD(device_suspend, uhub_suspend),
158 	DEVMETHOD(device_resume, uhub_resume),
159 
160 	DEVMETHOD(bus_child_location_str, uhub_child_location_string),
161 	DEVMETHOD(bus_child_pnpinfo_str, uhub_child_pnpinfo_string),
162 	DEVMETHOD(bus_driver_added, uhub_driver_added),
163 	{0, 0}
164 };
165 
166 static driver_t uhub_driver = {
167 	.name = "uhub",
168 	.methods = uhub_methods,
169 	.size = sizeof(struct uhub_softc)
170 };
171 
172 DRIVER_MODULE(uhub, usbus, uhub_driver, uhub_devclass, 0, 0);
173 DRIVER_MODULE(uhub, uhub, uhub_driver, uhub_devclass, NULL, 0);
174 MODULE_VERSION(uhub, 1);
175 
176 static void
177 uhub_intr_callback(struct usb_xfer *xfer, usb_error_t error)
178 {
179 	struct uhub_softc *sc = usbd_xfer_softc(xfer);
180 
181 	switch (USB_GET_STATE(xfer)) {
182 	case USB_ST_TRANSFERRED:
183 		DPRINTFN(2, "\n");
184 		/*
185 		 * This is an indication that some port
186 		 * has changed status. Notify the bus
187 		 * event handler thread that we need
188 		 * to be explored again:
189 		 */
190 		usb_needs_explore(sc->sc_udev->bus, 0);
191 
192 	case USB_ST_SETUP:
193 		usbd_xfer_set_frame_len(xfer, 0, usbd_xfer_max_len(xfer));
194 		usbd_transfer_submit(xfer);
195 		break;
196 
197 	default:			/* Error */
198 		if (xfer->error != USB_ERR_CANCELLED) {
199 			/*
200 			 * Do a clear-stall. The "stall_pipe" flag
201 			 * will get cleared before next callback by
202 			 * the USB stack.
203 			 */
204 			usbd_xfer_set_stall(xfer);
205 			usbd_xfer_set_frame_len(xfer, 0, usbd_xfer_max_len(xfer));
206 			usbd_transfer_submit(xfer);
207 		}
208 		break;
209 	}
210 }
211 
212 /*------------------------------------------------------------------------*
213  *	uhub_explore_sub - subroutine
214  *
215  * Return values:
216  *    0: Success
217  * Else: A control transaction failed
218  *------------------------------------------------------------------------*/
219 static usb_error_t
220 uhub_explore_sub(struct uhub_softc *sc, struct usb_port *up)
221 {
222 	struct usb_bus *bus;
223 	struct usb_device *child;
224 	uint8_t refcount;
225 	usb_error_t err;
226 
227 	bus = sc->sc_udev->bus;
228 	err = 0;
229 
230 	/* get driver added refcount from USB bus */
231 	refcount = bus->driver_added_refcount;
232 
233 	/* get device assosiated with the given port */
234 	child = usb_bus_port_get_device(bus, up);
235 	if (child == NULL) {
236 		/* nothing to do */
237 		goto done;
238 	}
239 
240 	/* check if device should be re-enumerated */
241 
242 	if (child->flags.usb_mode == USB_MODE_HOST) {
243 		usbd_enum_lock(child);
244 		if (child->re_enumerate_wait) {
245 			err = usbd_set_config_index(child, USB_UNCONFIG_INDEX);
246 			if (err == 0)
247 				err = usbd_req_re_enumerate(child, NULL);
248 			if (err == 0)
249 				err = usbd_set_config_index(child, 0);
250 			if (err == 0) {
251 				err = usb_probe_and_attach(child,
252 				    USB_IFACE_INDEX_ANY);
253 			}
254 			child->re_enumerate_wait = 0;
255 			err = 0;
256 		}
257 		usbd_enum_unlock(child);
258 	}
259 
260 	/* check if probe and attach should be done */
261 
262 	if (child->driver_added_refcount != refcount) {
263 		child->driver_added_refcount = refcount;
264 		err = usb_probe_and_attach(child,
265 		    USB_IFACE_INDEX_ANY);
266 		if (err) {
267 			goto done;
268 		}
269 	}
270 	/* start control transfer, if device mode */
271 
272 	if (child->flags.usb_mode == USB_MODE_DEVICE)
273 		usbd_ctrl_transfer_setup(child);
274 
275 	/* if a HUB becomes present, do a recursive HUB explore */
276 
277 	if (child->hub)
278 		err = (child->hub->explore) (child);
279 
280 done:
281 	return (err);
282 }
283 
284 /*------------------------------------------------------------------------*
285  *	uhub_read_port_status - factored out code
286  *------------------------------------------------------------------------*/
287 static usb_error_t
288 uhub_read_port_status(struct uhub_softc *sc, uint8_t portno)
289 {
290 	struct usb_port_status ps;
291 	usb_error_t err;
292 
293 	err = usbd_req_get_port_status(
294 	    sc->sc_udev, NULL, &ps, portno);
295 
296 	/* update status regardless of error */
297 
298 	sc->sc_st.port_status = UGETW(ps.wPortStatus);
299 	sc->sc_st.port_change = UGETW(ps.wPortChange);
300 
301 	/* debugging print */
302 
303 	DPRINTFN(4, "port %d, wPortStatus=0x%04x, "
304 	    "wPortChange=0x%04x, err=%s\n",
305 	    portno, sc->sc_st.port_status,
306 	    sc->sc_st.port_change, usbd_errstr(err));
307 	return (err);
308 }
309 
310 /*------------------------------------------------------------------------*
311  *	uhub_reattach_port
312  *
313  * Returns:
314  *    0: Success
315  * Else: A control transaction failed
316  *------------------------------------------------------------------------*/
317 static usb_error_t
318 uhub_reattach_port(struct uhub_softc *sc, uint8_t portno)
319 {
320 	struct usb_device *child;
321 	struct usb_device *udev;
322 	enum usb_dev_speed speed;
323 	enum usb_hc_mode mode;
324 	usb_error_t err;
325 	uint8_t timeout;
326 
327 	DPRINTF("reattaching port %d\n", portno);
328 
329 	err = 0;
330 	timeout = 0;
331 	udev = sc->sc_udev;
332 	child = usb_bus_port_get_device(udev->bus,
333 	    udev->hub->ports + portno - 1);
334 
335 repeat:
336 
337 	/* first clear the port connection change bit */
338 
339 	err = usbd_req_clear_port_feature(udev, NULL,
340 	    portno, UHF_C_PORT_CONNECTION);
341 
342 	if (err) {
343 		goto error;
344 	}
345 	/* check if there is a child */
346 
347 	if (child != NULL) {
348 		/*
349 		 * Free USB device and all subdevices, if any.
350 		 */
351 		usb_free_device(child, 0);
352 		child = NULL;
353 	}
354 	/* get fresh status */
355 
356 	err = uhub_read_port_status(sc, portno);
357 	if (err) {
358 		goto error;
359 	}
360 	/* check if nothing is connected to the port */
361 
362 	if (!(sc->sc_st.port_status & UPS_CURRENT_CONNECT_STATUS)) {
363 		goto error;
364 	}
365 	/* check if there is no power on the port and print a warning */
366 
367 	if (!(sc->sc_st.port_status & UPS_PORT_POWER)) {
368 		DPRINTF("WARNING: strange, connected port %d "
369 		    "has no power\n", portno);
370 	}
371 	/* check if the device is in Host Mode */
372 
373 	if (!(sc->sc_st.port_status & UPS_PORT_MODE_DEVICE)) {
374 
375 		DPRINTF("Port %d is in Host Mode\n", portno);
376 
377 		if (sc->sc_st.port_status & UPS_SUSPEND) {
378 			/*
379 			 * NOTE: Should not get here in SuperSpeed
380 			 * mode, because the HUB should report this
381 			 * bit as zero.
382 			 */
383 			DPRINTF("Port %d was still "
384 			    "suspended, clearing.\n", portno);
385 			err = usbd_req_clear_port_feature(udev,
386 			    NULL, portno, UHF_PORT_SUSPEND);
387 		}
388 
389 		/* USB Host Mode */
390 
391 		/* wait for maximum device power up time */
392 
393 		usb_pause_mtx(NULL,
394 		    USB_MS_TO_TICKS(USB_PORT_POWERUP_DELAY));
395 
396 		/* reset port, which implies enabling it */
397 
398 		err = usbd_req_reset_port(udev, NULL, portno);
399 
400 		if (err) {
401 			DPRINTFN(0, "port %d reset "
402 			    "failed, error=%s\n",
403 			    portno, usbd_errstr(err));
404 			goto error;
405 		}
406 		/* get port status again, it might have changed during reset */
407 
408 		err = uhub_read_port_status(sc, portno);
409 		if (err) {
410 			goto error;
411 		}
412 		/* check if something changed during port reset */
413 
414 		if ((sc->sc_st.port_change & UPS_C_CONNECT_STATUS) ||
415 		    (!(sc->sc_st.port_status & UPS_CURRENT_CONNECT_STATUS))) {
416 			if (timeout) {
417 				DPRINTFN(0, "giving up port reset "
418 				    "- device vanished\n");
419 				goto error;
420 			}
421 			timeout = 1;
422 			goto repeat;
423 		}
424 	} else {
425 		DPRINTF("Port %d is in Device Mode\n", portno);
426 	}
427 
428 	/*
429 	 * Figure out the device speed
430 	 */
431 	switch (udev->speed) {
432 	case USB_SPEED_HIGH:
433 		if (sc->sc_st.port_status & UPS_HIGH_SPEED)
434 			speed = USB_SPEED_HIGH;
435 		else if (sc->sc_st.port_status & UPS_LOW_SPEED)
436 			speed = USB_SPEED_LOW;
437 		else
438 			speed = USB_SPEED_FULL;
439 		break;
440 	case USB_SPEED_FULL:
441 		if (sc->sc_st.port_status & UPS_LOW_SPEED)
442 			speed = USB_SPEED_LOW;
443 		else
444 			speed = USB_SPEED_FULL;
445 		break;
446 	case USB_SPEED_LOW:
447 		speed = USB_SPEED_LOW;
448 		break;
449 	case USB_SPEED_SUPER:
450 		if (udev->parent_hub == NULL) {
451 			/* Root HUB - special case */
452 			switch (sc->sc_st.port_status & UPS_OTHER_SPEED) {
453 			case 0:
454 				speed = USB_SPEED_FULL;
455 				break;
456 			case UPS_LOW_SPEED:
457 				speed = USB_SPEED_LOW;
458 				break;
459 			case UPS_HIGH_SPEED:
460 				speed = USB_SPEED_HIGH;
461 				break;
462 			default:
463 				speed = USB_SPEED_SUPER;
464 				break;
465 			}
466 		} else {
467 			speed = USB_SPEED_SUPER;
468 		}
469 		break;
470 	default:
471 		/* same speed like parent */
472 		speed = udev->speed;
473 		break;
474 	}
475 	if (speed == USB_SPEED_SUPER) {
476 		err = usbd_req_set_hub_u1_timeout(udev, NULL,
477 		    portno, 128 - (2 * udev->depth));
478 		if (err) {
479 			DPRINTFN(0, "port %d U1 timeout "
480 			    "failed, error=%s\n",
481 			    portno, usbd_errstr(err));
482 		}
483 		err = usbd_req_set_hub_u2_timeout(udev, NULL,
484 		    portno, 128 - (2 * udev->depth));
485 		if (err) {
486 			DPRINTFN(0, "port %d U2 timeout "
487 			    "failed, error=%s\n",
488 			    portno, usbd_errstr(err));
489 		}
490 	}
491 
492 	/*
493 	 * Figure out the device mode
494 	 *
495 	 * NOTE: This part is currently FreeBSD specific.
496 	 */
497 	if (sc->sc_st.port_status & UPS_PORT_MODE_DEVICE)
498 		mode = USB_MODE_DEVICE;
499 	else
500 		mode = USB_MODE_HOST;
501 
502 	/* need to create a new child */
503 	child = usb_alloc_device(sc->sc_dev, udev->bus, udev,
504 	    udev->depth + 1, portno - 1, portno, speed, mode);
505 	if (child == NULL) {
506 		DPRINTFN(0, "could not allocate new device\n");
507 		goto error;
508 	}
509 	return (0);			/* success */
510 
511 error:
512 	if (child != NULL) {
513 		/*
514 		 * Free USB device and all subdevices, if any.
515 		 */
516 		usb_free_device(child, 0);
517 		child = NULL;
518 	}
519 	if (err == 0) {
520 		if (sc->sc_st.port_status & UPS_PORT_ENABLED) {
521 			err = usbd_req_clear_port_feature(
522 			    sc->sc_udev, NULL,
523 			    portno, UHF_PORT_ENABLE);
524 		}
525 	}
526 	if (err) {
527 		DPRINTFN(0, "device problem (%s), "
528 		    "disabling port %d\n", usbd_errstr(err), portno);
529 	}
530 	return (err);
531 }
532 
533 /*------------------------------------------------------------------------*
534  *	usb_device_20_compatible
535  *
536  * Returns:
537  *    0: HUB does not support suspend and resume
538  * Else: HUB supports suspend and resume
539  *------------------------------------------------------------------------*/
540 static uint8_t
541 usb_device_20_compatible(struct usb_device *udev)
542 {
543 	if (udev == NULL)
544 		return (0);
545 	switch (udev->speed) {
546 	case USB_SPEED_LOW:
547 	case USB_SPEED_FULL:
548 	case USB_SPEED_HIGH:
549 		return (1);
550 	default:
551 		return (0);
552 	}
553 }
554 
555 /*------------------------------------------------------------------------*
556  *	uhub_suspend_resume_port
557  *
558  * Returns:
559  *    0: Success
560  * Else: A control transaction failed
561  *------------------------------------------------------------------------*/
562 static usb_error_t
563 uhub_suspend_resume_port(struct uhub_softc *sc, uint8_t portno)
564 {
565 	struct usb_device *child;
566 	struct usb_device *udev;
567 	uint8_t is_suspend;
568 	usb_error_t err;
569 
570 	DPRINTF("port %d\n", portno);
571 
572 	udev = sc->sc_udev;
573 	child = usb_bus_port_get_device(udev->bus,
574 	    udev->hub->ports + portno - 1);
575 
576 	/* first clear the port suspend change bit */
577 
578 	if (usb_device_20_compatible(udev)) {
579 		err = usbd_req_clear_port_feature(udev, NULL,
580 		    portno, UHF_C_PORT_SUSPEND);
581 	} else {
582 		err = usbd_req_clear_port_feature(udev, NULL,
583 		    portno, UHF_C_PORT_LINK_STATE);
584 	}
585 
586 	if (err) {
587 		DPRINTF("clearing suspend failed.\n");
588 		goto done;
589 	}
590 	/* get fresh status */
591 
592 	err = uhub_read_port_status(sc, portno);
593 	if (err) {
594 		DPRINTF("reading port status failed.\n");
595 		goto done;
596 	}
597 	/* convert current state */
598 
599 	if (usb_device_20_compatible(udev)) {
600 		if (sc->sc_st.port_status & UPS_SUSPEND) {
601 			is_suspend = 1;
602 		} else {
603 			is_suspend = 0;
604 		}
605 	} else {
606 		switch (UPS_PORT_LINK_STATE_GET(sc->sc_st.port_status)) {
607 		case UPS_PORT_LS_U0:
608 		case UPS_PORT_LS_U1:
609 			is_suspend = 0;
610 			break;
611 		default:
612 			is_suspend = 1;
613 			break;
614 		}
615 	}
616 
617 	DPRINTF("suspended=%u\n", is_suspend);
618 
619 	/* do the suspend or resume */
620 
621 	if (child) {
622 		/*
623 		 * This code handle two cases: 1) Host Mode - we can only
624 		 * receive resume here 2) Device Mode - we can receive
625 		 * suspend and resume here
626 		 */
627 		if (is_suspend == 0)
628 			usb_dev_resume_peer(child);
629 		else if ((child->flags.usb_mode == USB_MODE_DEVICE) ||
630 		    (usb_device_20_compatible(child) == 0))
631 			usb_dev_suspend_peer(child);
632 	}
633 done:
634 	return (err);
635 }
636 
637 /*------------------------------------------------------------------------*
638  *	uhub_root_interrupt
639  *
640  * This function is called when a Root HUB interrupt has
641  * happened. "ptr" and "len" makes up the Root HUB interrupt
642  * packet. This function is called having the "bus_mtx" locked.
643  *------------------------------------------------------------------------*/
644 void
645 uhub_root_intr(struct usb_bus *bus, const uint8_t *ptr, uint8_t len)
646 {
647 	USB_BUS_LOCK_ASSERT(bus, MA_OWNED);
648 
649 	usb_needs_explore(bus, 0);
650 }
651 
652 static uint8_t
653 uhub_is_too_deep(struct usb_device *udev)
654 {
655 	switch (udev->speed) {
656 	case USB_SPEED_FULL:
657 	case USB_SPEED_LOW:
658 	case USB_SPEED_HIGH:
659 		if (udev->depth > USB_HUB_MAX_DEPTH)
660 			return (1);
661 		break;
662 	case USB_SPEED_SUPER:
663 		if (udev->depth > USB_SS_HUB_DEPTH_MAX)
664 			return (1);
665 		break;
666 	default:
667 		break;
668 	}
669 	return (0);
670 }
671 
672 /*------------------------------------------------------------------------*
673  *	uhub_explore
674  *
675  * Returns:
676  *     0: Success
677  *  Else: Failure
678  *------------------------------------------------------------------------*/
679 static usb_error_t
680 uhub_explore(struct usb_device *udev)
681 {
682 	struct usb_hub *hub;
683 	struct uhub_softc *sc;
684 	struct usb_port *up;
685 	usb_error_t err;
686 	uint8_t portno;
687 	uint8_t x;
688 
689 	hub = udev->hub;
690 	sc = hub->hubsoftc;
691 
692 	DPRINTFN(11, "udev=%p addr=%d\n", udev, udev->address);
693 
694 	/* ignore devices that are too deep */
695 	if (uhub_is_too_deep(udev))
696 		return (USB_ERR_TOO_DEEP);
697 
698 	/* check if device is suspended */
699 	if (udev->flags.self_suspended) {
700 		/* need to wait until the child signals resume */
701 		DPRINTF("Device is suspended!\n");
702 		return (0);
703 	}
704 	for (x = 0; x != hub->nports; x++) {
705 		up = hub->ports + x;
706 		portno = x + 1;
707 
708 		err = uhub_read_port_status(sc, portno);
709 		if (err) {
710 			/* most likely the HUB is gone */
711 			break;
712 		}
713 		if (sc->sc_st.port_change & UPS_C_OVERCURRENT_INDICATOR) {
714 			DPRINTF("Overcurrent on port %u.\n", portno);
715 			err = usbd_req_clear_port_feature(
716 			    udev, NULL, portno, UHF_C_PORT_OVER_CURRENT);
717 			if (err) {
718 				/* most likely the HUB is gone */
719 				break;
720 			}
721 		}
722 		if (!(sc->sc_flags & UHUB_FLAG_DID_EXPLORE)) {
723 			/*
724 			 * Fake a connect status change so that the
725 			 * status gets checked initially!
726 			 */
727 			sc->sc_st.port_change |=
728 			    UPS_C_CONNECT_STATUS;
729 		}
730 		if (sc->sc_st.port_change & UPS_C_PORT_ENABLED) {
731 			err = usbd_req_clear_port_feature(
732 			    udev, NULL, portno, UHF_C_PORT_ENABLE);
733 			if (err) {
734 				/* most likely the HUB is gone */
735 				break;
736 			}
737 			if (sc->sc_st.port_change & UPS_C_CONNECT_STATUS) {
738 				/*
739 				 * Ignore the port error if the device
740 				 * has vanished !
741 				 */
742 			} else if (sc->sc_st.port_status & UPS_PORT_ENABLED) {
743 				DPRINTFN(0, "illegal enable change, "
744 				    "port %d\n", portno);
745 			} else {
746 
747 				if (up->restartcnt == USB_RESTART_MAX) {
748 					/* XXX could try another speed ? */
749 					DPRINTFN(0, "port error, giving up "
750 					    "port %d\n", portno);
751 				} else {
752 					sc->sc_st.port_change |=
753 					    UPS_C_CONNECT_STATUS;
754 					up->restartcnt++;
755 				}
756 			}
757 		}
758 		if (sc->sc_st.port_change & UPS_C_CONNECT_STATUS) {
759 			err = uhub_reattach_port(sc, portno);
760 			if (err) {
761 				/* most likely the HUB is gone */
762 				break;
763 			}
764 		}
765 		if (sc->sc_st.port_change & (UPS_C_SUSPEND | UPS_C_PORT_LINK_STATE)) {
766 			err = uhub_suspend_resume_port(sc, portno);
767 			if (err) {
768 				/* most likely the HUB is gone */
769 				break;
770 			}
771 		}
772 		err = uhub_explore_sub(sc, up);
773 		if (err) {
774 			/* no device(s) present */
775 			continue;
776 		}
777 		/* explore succeeded - reset restart counter */
778 		up->restartcnt = 0;
779 	}
780 
781 	/* initial status checked */
782 	sc->sc_flags |= UHUB_FLAG_DID_EXPLORE;
783 
784 	/* return success */
785 	return (USB_ERR_NORMAL_COMPLETION);
786 }
787 
788 static int
789 uhub_probe(device_t dev)
790 {
791 	struct usb_attach_arg *uaa = device_get_ivars(dev);
792 
793 	if (uaa->usb_mode != USB_MODE_HOST)
794 		return (ENXIO);
795 
796 	/*
797 	 * The subclass for USB HUBs is currently ignored because it
798 	 * is 0 for some and 1 for others.
799 	 */
800 	if (uaa->info.bConfigIndex == 0 &&
801 	    uaa->info.bDeviceClass == UDCLASS_HUB)
802 		return (0);
803 
804 	return (ENXIO);
805 }
806 
807 /* NOTE: The information returned by this function can be wrong. */
808 usb_error_t
809 uhub_query_info(struct usb_device *udev, uint8_t *pnports, uint8_t *ptt)
810 {
811 	struct usb_hub_descriptor hubdesc20;
812 	struct usb_hub_ss_descriptor hubdesc30;
813 	usb_error_t err;
814 	uint8_t nports;
815 	uint8_t tt;
816 
817 	if (udev->ddesc.bDeviceClass != UDCLASS_HUB)
818 		return (USB_ERR_INVAL);
819 
820 	nports = 0;
821 	tt = 0;
822 
823 	switch (udev->speed) {
824 	case USB_SPEED_LOW:
825 	case USB_SPEED_FULL:
826 	case USB_SPEED_HIGH:
827 		/* assuming that there is one port */
828 		err = usbd_req_get_hub_descriptor(udev, NULL, &hubdesc20, 1);
829 		if (err) {
830 			DPRINTFN(0, "getting USB 2.0 HUB descriptor failed,"
831 			    "error=%s\n", usbd_errstr(err));
832 			break;
833 		}
834 		nports = hubdesc20.bNbrPorts;
835 		if (nports > 127)
836 			nports = 127;
837 
838 		if (udev->speed == USB_SPEED_HIGH)
839 			tt = (UGETW(hubdesc20.wHubCharacteristics) >> 5) & 3;
840 		break;
841 
842 	case USB_SPEED_SUPER:
843 		err = usbd_req_get_ss_hub_descriptor(udev, NULL, &hubdesc30, 1);
844 		if (err) {
845 			DPRINTFN(0, "Getting USB 3.0 HUB descriptor failed,"
846 			    "error=%s\n", usbd_errstr(err));
847 			break;
848 		}
849 		nports = hubdesc30.bNbrPorts;
850 		if (nports > 16)
851 			nports = 16;
852 		break;
853 
854 	default:
855 		err = USB_ERR_INVAL;
856 		break;
857 	}
858 
859 	if (pnports != NULL)
860 		*pnports = nports;
861 
862 	if (ptt != NULL)
863 		*ptt = tt;
864 
865 	return (err);
866 }
867 
868 static int
869 uhub_attach(device_t dev)
870 {
871 	struct uhub_softc *sc = device_get_softc(dev);
872 	struct usb_attach_arg *uaa = device_get_ivars(dev);
873 	struct usb_device *udev = uaa->device;
874 	struct usb_device *parent_hub = udev->parent_hub;
875 	struct usb_hub *hub;
876 	struct usb_hub_descriptor hubdesc20;
877 	struct usb_hub_ss_descriptor hubdesc30;
878 	uint16_t pwrdly;
879 	uint8_t x;
880 	uint8_t nports;
881 	uint8_t portno;
882 	uint8_t removable;
883 	uint8_t iface_index;
884 	usb_error_t err;
885 
886 	sc->sc_udev = udev;
887 	sc->sc_dev = dev;
888 
889 	mtx_init(&sc->sc_mtx, "USB HUB mutex", NULL, MTX_DEF);
890 
891 	snprintf(sc->sc_name, sizeof(sc->sc_name), "%s",
892 	    device_get_nameunit(dev));
893 
894 	device_set_usb_desc(dev);
895 
896 	DPRINTFN(2, "depth=%d selfpowered=%d, parent=%p, "
897 	    "parent->selfpowered=%d\n",
898 	    udev->depth,
899 	    udev->flags.self_powered,
900 	    parent_hub,
901 	    parent_hub ?
902 	    parent_hub->flags.self_powered : 0);
903 
904 	if (uhub_is_too_deep(udev)) {
905 		DPRINTFN(0, "HUB at depth %d, "
906 		    "exceeds maximum. HUB ignored\n", (int)udev->depth);
907 		goto error;
908 	}
909 
910 	if (!udev->flags.self_powered && parent_hub &&
911 	    !parent_hub->flags.self_powered) {
912 		DPRINTFN(0, "Bus powered HUB connected to "
913 		    "bus powered HUB. HUB ignored\n");
914 		goto error;
915 	}
916 	/* get HUB descriptor */
917 
918 	DPRINTFN(2, "Getting HUB descriptor\n");
919 
920 	switch (udev->speed) {
921 	case USB_SPEED_LOW:
922 	case USB_SPEED_FULL:
923 	case USB_SPEED_HIGH:
924 		/* assuming that there is one port */
925 		err = usbd_req_get_hub_descriptor(udev, NULL, &hubdesc20, 1);
926 		if (err) {
927 			DPRINTFN(0, "getting USB 2.0 HUB descriptor failed,"
928 			    "error=%s\n", usbd_errstr(err));
929 			goto error;
930 		}
931 		/* get number of ports */
932 		nports = hubdesc20.bNbrPorts;
933 
934 		/* get power delay */
935 		pwrdly = ((hubdesc20.bPwrOn2PwrGood * UHD_PWRON_FACTOR) +
936 		    USB_EXTRA_POWER_UP_TIME);
937 
938 		/* get complete HUB descriptor */
939 		if (nports >= 8) {
940 			/* check number of ports */
941 			if (nports > 127) {
942 				DPRINTFN(0, "Invalid number of USB 2.0 ports,"
943 				    "error=%s\n", usbd_errstr(err));
944 				goto error;
945 			}
946 			/* get complete HUB descriptor */
947 			err = usbd_req_get_hub_descriptor(udev, NULL, &hubdesc20, nports);
948 
949 			if (err) {
950 				DPRINTFN(0, "Getting USB 2.0 HUB descriptor failed,"
951 				    "error=%s\n", usbd_errstr(err));
952 				goto error;
953 			}
954 			if (hubdesc20.bNbrPorts != nports) {
955 				DPRINTFN(0, "Number of ports changed\n");
956 				goto error;
957 			}
958 		}
959 		break;
960 	case USB_SPEED_SUPER:
961 		if (udev->parent_hub != NULL) {
962 			err = usbd_req_set_hub_depth(udev, NULL,
963 			    udev->depth - 1);
964 			if (err) {
965 				DPRINTFN(0, "Setting USB 3.0 HUB depth failed,"
966 				    "error=%s\n", usbd_errstr(err));
967 				goto error;
968 			}
969 		}
970 		err = usbd_req_get_ss_hub_descriptor(udev, NULL, &hubdesc30, 1);
971 		if (err) {
972 			DPRINTFN(0, "Getting USB 3.0 HUB descriptor failed,"
973 			    "error=%s\n", usbd_errstr(err));
974 			goto error;
975 		}
976 		/* get number of ports */
977 		nports = hubdesc30.bNbrPorts;
978 
979 		/* get power delay */
980 		pwrdly = ((hubdesc30.bPwrOn2PwrGood * UHD_PWRON_FACTOR) +
981 		    USB_EXTRA_POWER_UP_TIME);
982 
983 		/* get complete HUB descriptor */
984 		if (nports >= 8) {
985 			/* check number of ports */
986 			if (nports > ((udev->parent_hub != NULL) ? 15 : 127)) {
987 				DPRINTFN(0, "Invalid number of USB 3.0 ports,"
988 				    "error=%s\n", usbd_errstr(err));
989 				goto error;
990 			}
991 			/* get complete HUB descriptor */
992 			err = usbd_req_get_ss_hub_descriptor(udev, NULL, &hubdesc30, nports);
993 
994 			if (err) {
995 				DPRINTFN(0, "Getting USB 2.0 HUB descriptor failed,"
996 				    "error=%s\n", usbd_errstr(err));
997 				goto error;
998 			}
999 			if (hubdesc30.bNbrPorts != nports) {
1000 				DPRINTFN(0, "Number of ports changed\n");
1001 				goto error;
1002 			}
1003 		}
1004 		break;
1005 	default:
1006 		DPRINTF("Assuming HUB has only one port\n");
1007 		/* default number of ports */
1008 		nports = 1;
1009 		/* default power delay */
1010 		pwrdly = ((10 * UHD_PWRON_FACTOR) + USB_EXTRA_POWER_UP_TIME);
1011 		break;
1012 	}
1013 	if (nports == 0) {
1014 		DPRINTFN(0, "portless HUB\n");
1015 		goto error;
1016 	}
1017 	hub = malloc(sizeof(hub[0]) + (sizeof(hub->ports[0]) * nports),
1018 	    M_USBDEV, M_WAITOK | M_ZERO);
1019 
1020 	if (hub == NULL) {
1021 		goto error;
1022 	}
1023 	udev->hub = hub;
1024 
1025 #if USB_HAVE_TT_SUPPORT
1026 	/* init FULL-speed ISOCHRONOUS schedule */
1027 	usbd_fs_isoc_schedule_init_all(hub->fs_isoc_schedule);
1028 #endif
1029 	/* initialize HUB structure */
1030 	hub->hubsoftc = sc;
1031 	hub->explore = &uhub_explore;
1032 	hub->nports = nports;
1033 	hub->hubudev = udev;
1034 
1035 	/* if self powered hub, give ports maximum current */
1036 	if (udev->flags.self_powered) {
1037 		hub->portpower = USB_MAX_POWER;
1038 	} else {
1039 		hub->portpower = USB_MIN_POWER;
1040 	}
1041 
1042 	/* set up interrupt pipe */
1043 	iface_index = 0;
1044 	if (udev->parent_hub == NULL) {
1045 		/* root HUB is special */
1046 		err = 0;
1047 	} else {
1048 		/* normal HUB */
1049 		err = usbd_transfer_setup(udev, &iface_index, sc->sc_xfer,
1050 		    uhub_config, UHUB_N_TRANSFER, sc, &sc->sc_mtx);
1051 	}
1052 	if (err) {
1053 		DPRINTFN(0, "cannot setup interrupt transfer, "
1054 		    "errstr=%s\n", usbd_errstr(err));
1055 		goto error;
1056 	}
1057 	/* wait with power off for a while */
1058 	usb_pause_mtx(NULL, USB_MS_TO_TICKS(USB_POWER_DOWN_TIME));
1059 
1060 	/*
1061 	 * To have the best chance of success we do things in the exact same
1062 	 * order as Windoze98.  This should not be necessary, but some
1063 	 * devices do not follow the USB specs to the letter.
1064 	 *
1065 	 * These are the events on the bus when a hub is attached:
1066 	 *  Get device and config descriptors (see attach code)
1067 	 *  Get hub descriptor (see above)
1068 	 *  For all ports
1069 	 *     turn on power
1070 	 *     wait for power to become stable
1071 	 * (all below happens in explore code)
1072 	 *  For all ports
1073 	 *     clear C_PORT_CONNECTION
1074 	 *  For all ports
1075 	 *     get port status
1076 	 *     if device connected
1077 	 *        wait 100 ms
1078 	 *        turn on reset
1079 	 *        wait
1080 	 *        clear C_PORT_RESET
1081 	 *        get port status
1082 	 *        proceed with device attachment
1083 	 */
1084 
1085 	/* XXX should check for none, individual, or ganged power? */
1086 
1087 	removable = 0;
1088 
1089 	for (x = 0; x != nports; x++) {
1090 		/* set up data structures */
1091 		struct usb_port *up = hub->ports + x;
1092 
1093 		up->device_index = 0;
1094 		up->restartcnt = 0;
1095 		portno = x + 1;
1096 
1097 		/* check if port is removable */
1098 		switch (udev->speed) {
1099 		case USB_SPEED_LOW:
1100 		case USB_SPEED_FULL:
1101 		case USB_SPEED_HIGH:
1102 			if (!UHD_NOT_REMOV(&hubdesc20, portno))
1103 				removable++;
1104 			break;
1105 		case USB_SPEED_SUPER:
1106 			if (!UHD_NOT_REMOV(&hubdesc30, portno))
1107 				removable++;
1108 			break;
1109 		default:
1110 			DPRINTF("Assuming removable port\n");
1111 			removable++;
1112 			break;
1113 		}
1114 		if (!err) {
1115 			/* turn the power on */
1116 			err = usbd_req_set_port_feature(udev, NULL,
1117 			    portno, UHF_PORT_POWER);
1118 		}
1119 		if (err) {
1120 			DPRINTFN(0, "port %d power on failed, %s\n",
1121 			    portno, usbd_errstr(err));
1122 		}
1123 		DPRINTF("turn on port %d power\n",
1124 		    portno);
1125 
1126 		/* wait for stable power */
1127 		usb_pause_mtx(NULL, USB_MS_TO_TICKS(pwrdly));
1128 	}
1129 
1130 	device_printf(dev, "%d port%s with %d "
1131 	    "removable, %s powered\n", nports, (nports != 1) ? "s" : "",
1132 	    removable, udev->flags.self_powered ? "self" : "bus");
1133 
1134 	/* Start the interrupt endpoint, if any */
1135 
1136 	if (sc->sc_xfer[0] != NULL) {
1137 		mtx_lock(&sc->sc_mtx);
1138 		usbd_transfer_start(sc->sc_xfer[0]);
1139 		mtx_unlock(&sc->sc_mtx);
1140 	}
1141 
1142 	/* Enable automatic power save on all USB HUBs */
1143 
1144 	usbd_set_power_mode(udev, USB_POWER_MODE_SAVE);
1145 
1146 	return (0);
1147 
1148 error:
1149 	usbd_transfer_unsetup(sc->sc_xfer, UHUB_N_TRANSFER);
1150 
1151 	if (udev->hub) {
1152 		free(udev->hub, M_USBDEV);
1153 		udev->hub = NULL;
1154 	}
1155 
1156 	mtx_destroy(&sc->sc_mtx);
1157 
1158 	return (ENXIO);
1159 }
1160 
1161 /*
1162  * Called from process context when the hub is gone.
1163  * Detach all devices on active ports.
1164  */
1165 static int
1166 uhub_detach(device_t dev)
1167 {
1168 	struct uhub_softc *sc = device_get_softc(dev);
1169 	struct usb_hub *hub = sc->sc_udev->hub;
1170 	struct usb_device *child;
1171 	uint8_t x;
1172 
1173 	if (hub == NULL)		/* must be partially working */
1174 		return (0);
1175 
1176 	/* Make sure interrupt transfer is gone. */
1177 	usbd_transfer_unsetup(sc->sc_xfer, UHUB_N_TRANSFER);
1178 
1179 	/* Detach all ports */
1180 	for (x = 0; x != hub->nports; x++) {
1181 
1182 		child = usb_bus_port_get_device(sc->sc_udev->bus, hub->ports + x);
1183 
1184 		if (child == NULL) {
1185 			continue;
1186 		}
1187 
1188 		/*
1189 		 * Free USB device and all subdevices, if any.
1190 		 */
1191 		usb_free_device(child, 0);
1192 	}
1193 
1194 	free(hub, M_USBDEV);
1195 	sc->sc_udev->hub = NULL;
1196 
1197 	mtx_destroy(&sc->sc_mtx);
1198 
1199 	return (0);
1200 }
1201 
1202 static int
1203 uhub_suspend(device_t dev)
1204 {
1205 	DPRINTF("\n");
1206 	/* Sub-devices are not suspended here! */
1207 	return (0);
1208 }
1209 
1210 static int
1211 uhub_resume(device_t dev)
1212 {
1213 	DPRINTF("\n");
1214 	/* Sub-devices are not resumed here! */
1215 	return (0);
1216 }
1217 
1218 static void
1219 uhub_driver_added(device_t dev, driver_t *driver)
1220 {
1221 	usb_needs_explore_all();
1222 }
1223 
1224 struct hub_result {
1225 	struct usb_device *udev;
1226 	uint8_t	portno;
1227 	uint8_t	iface_index;
1228 };
1229 
1230 static void
1231 uhub_find_iface_index(struct usb_hub *hub, device_t child,
1232     struct hub_result *res)
1233 {
1234 	struct usb_interface *iface;
1235 	struct usb_device *udev;
1236 	uint8_t nports;
1237 	uint8_t x;
1238 	uint8_t i;
1239 
1240 	nports = hub->nports;
1241 	for (x = 0; x != nports; x++) {
1242 		udev = usb_bus_port_get_device(hub->hubudev->bus,
1243 		    hub->ports + x);
1244 		if (!udev) {
1245 			continue;
1246 		}
1247 		for (i = 0; i != USB_IFACE_MAX; i++) {
1248 			iface = usbd_get_iface(udev, i);
1249 			if (iface &&
1250 			    (iface->subdev == child)) {
1251 				res->iface_index = i;
1252 				res->udev = udev;
1253 				res->portno = x + 1;
1254 				return;
1255 			}
1256 		}
1257 	}
1258 	res->iface_index = 0;
1259 	res->udev = NULL;
1260 	res->portno = 0;
1261 }
1262 
1263 static int
1264 uhub_child_location_string(device_t parent, device_t child,
1265     char *buf, size_t buflen)
1266 {
1267 	struct uhub_softc *sc;
1268 	struct usb_hub *hub;
1269 	struct hub_result res;
1270 
1271 	if (!device_is_attached(parent)) {
1272 		if (buflen)
1273 			buf[0] = 0;
1274 		return (0);
1275 	}
1276 
1277 	sc = device_get_softc(parent);
1278 	hub = sc->sc_udev->hub;
1279 
1280 	mtx_lock(&Giant);
1281 	uhub_find_iface_index(hub, child, &res);
1282 	if (!res.udev) {
1283 		DPRINTF("device not on hub\n");
1284 		if (buflen) {
1285 			buf[0] = '\0';
1286 		}
1287 		goto done;
1288 	}
1289 	snprintf(buf, buflen, "bus=%u hubaddr=%u port=%u devaddr=%u interface=%u",
1290 	    (res.udev->parent_hub != NULL) ? res.udev->parent_hub->device_index : 0,
1291 	    res.portno, device_get_unit(res.udev->bus->bdev),
1292 	    res.udev->device_index, res.iface_index);
1293 done:
1294 	mtx_unlock(&Giant);
1295 
1296 	return (0);
1297 }
1298 
1299 static int
1300 uhub_child_pnpinfo_string(device_t parent, device_t child,
1301     char *buf, size_t buflen)
1302 {
1303 	struct uhub_softc *sc;
1304 	struct usb_hub *hub;
1305 	struct usb_interface *iface;
1306 	struct hub_result res;
1307 
1308 	if (!device_is_attached(parent)) {
1309 		if (buflen)
1310 			buf[0] = 0;
1311 		return (0);
1312 	}
1313 
1314 	sc = device_get_softc(parent);
1315 	hub = sc->sc_udev->hub;
1316 
1317 	mtx_lock(&Giant);
1318 	uhub_find_iface_index(hub, child, &res);
1319 	if (!res.udev) {
1320 		DPRINTF("device not on hub\n");
1321 		if (buflen) {
1322 			buf[0] = '\0';
1323 		}
1324 		goto done;
1325 	}
1326 	iface = usbd_get_iface(res.udev, res.iface_index);
1327 	if (iface && iface->idesc) {
1328 		snprintf(buf, buflen, "vendor=0x%04x product=0x%04x "
1329 		    "devclass=0x%02x devsubclass=0x%02x "
1330 		    "sernum=\"%s\" "
1331 		    "release=0x%04x "
1332 		    "intclass=0x%02x intsubclass=0x%02x" "%s%s",
1333 		    UGETW(res.udev->ddesc.idVendor),
1334 		    UGETW(res.udev->ddesc.idProduct),
1335 		    res.udev->ddesc.bDeviceClass,
1336 		    res.udev->ddesc.bDeviceSubClass,
1337 		    usb_get_serial(res.udev),
1338 		    UGETW(res.udev->ddesc.bcdDevice),
1339 		    iface->idesc->bInterfaceClass,
1340 		    iface->idesc->bInterfaceSubClass,
1341 		    iface->pnpinfo ? " " : "",
1342 		    iface->pnpinfo ? iface->pnpinfo : "");
1343 	} else {
1344 		if (buflen) {
1345 			buf[0] = '\0';
1346 		}
1347 		goto done;
1348 	}
1349 done:
1350 	mtx_unlock(&Giant);
1351 
1352 	return (0);
1353 }
1354 
1355 /*
1356  * The USB Transaction Translator:
1357  * ===============================
1358  *
1359  * When doing LOW- and FULL-speed USB transfers accross a HIGH-speed
1360  * USB HUB, bandwidth must be allocated for ISOCHRONOUS and INTERRUPT
1361  * USB transfers. To utilize bandwidth dynamically the "scatter and
1362  * gather" principle must be applied. This means that bandwidth must
1363  * be divided into equal parts of bandwidth. With regard to USB all
1364  * data is transferred in smaller packets with length
1365  * "wMaxPacketSize". The problem however is that "wMaxPacketSize" is
1366  * not a constant!
1367  *
1368  * The bandwidth scheduler which I have implemented will simply pack
1369  * the USB transfers back to back until there is no more space in the
1370  * schedule. Out of the 8 microframes which the USB 2.0 standard
1371  * provides, only 6 are available for non-HIGH-speed devices. I have
1372  * reserved the first 4 microframes for ISOCHRONOUS transfers. The
1373  * last 2 microframes I have reserved for INTERRUPT transfers. Without
1374  * this division, it is very difficult to allocate and free bandwidth
1375  * dynamically.
1376  *
1377  * NOTE about the Transaction Translator in USB HUBs:
1378  *
1379  * USB HUBs have a very simple Transaction Translator, that will
1380  * simply pipeline all the SPLIT transactions. That means that the
1381  * transactions will be executed in the order they are queued!
1382  *
1383  */
1384 
1385 /*------------------------------------------------------------------------*
1386  *	usb_intr_find_best_slot
1387  *
1388  * Return value:
1389  *   The best Transaction Translation slot for an interrupt endpoint.
1390  *------------------------------------------------------------------------*/
1391 static uint8_t
1392 usb_intr_find_best_slot(usb_size_t *ptr, uint8_t start,
1393     uint8_t end, uint8_t mask)
1394 {
1395 	usb_size_t min = 0 - 1;
1396 	usb_size_t sum;
1397 	uint8_t x;
1398 	uint8_t y;
1399 	uint8_t z;
1400 
1401 	y = 0;
1402 
1403 	/* find the last slot with lesser used bandwidth */
1404 
1405 	for (x = start; x < end; x++) {
1406 
1407 		sum = 0;
1408 
1409 		/* compute sum of bandwidth */
1410 		for (z = x; z < end; z++) {
1411 			if (mask & (1U << (z - x)))
1412 				sum += ptr[z];
1413 		}
1414 
1415 		/* check if the current multi-slot is more optimal */
1416 		if (min >= sum) {
1417 			min = sum;
1418 			y = x;
1419 		}
1420 
1421 		/* check if the mask is about to be shifted out */
1422 		if (mask & (1U << (end - 1 - x)))
1423 			break;
1424 	}
1425 	return (y);
1426 }
1427 
1428 /*------------------------------------------------------------------------*
1429  *	usb_hs_bandwidth_adjust
1430  *
1431  * This function will update the bandwith usage for the microframe
1432  * having index "slot" by "len" bytes. "len" can be negative.  If the
1433  * "slot" argument is greater or equal to "USB_HS_MICRO_FRAMES_MAX"
1434  * the "slot" argument will be replaced by the slot having least used
1435  * bandwidth. The "mask" argument is used for multi-slot allocations.
1436  *
1437  * Returns:
1438  *    The slot in which the bandwidth update was done: 0..7
1439  *------------------------------------------------------------------------*/
1440 static uint8_t
1441 usb_hs_bandwidth_adjust(struct usb_device *udev, int16_t len,
1442     uint8_t slot, uint8_t mask)
1443 {
1444 	struct usb_bus *bus = udev->bus;
1445 	struct usb_hub *hub;
1446 	enum usb_dev_speed speed;
1447 	uint8_t x;
1448 
1449 	USB_BUS_LOCK_ASSERT(bus, MA_OWNED);
1450 
1451 	speed = usbd_get_speed(udev);
1452 
1453 	switch (speed) {
1454 	case USB_SPEED_LOW:
1455 	case USB_SPEED_FULL:
1456 		if (speed == USB_SPEED_LOW) {
1457 			len *= 8;
1458 		}
1459 		/*
1460 	         * The Host Controller Driver should have
1461 	         * performed checks so that the lookup
1462 	         * below does not result in a NULL pointer
1463 	         * access.
1464 	         */
1465 
1466 		hub = udev->parent_hs_hub->hub;
1467 		if (slot >= USB_HS_MICRO_FRAMES_MAX) {
1468 			slot = usb_intr_find_best_slot(hub->uframe_usage,
1469 			    USB_FS_ISOC_UFRAME_MAX, 6, mask);
1470 		}
1471 		for (x = slot; x < 8; x++) {
1472 			if (mask & (1U << (x - slot))) {
1473 				hub->uframe_usage[x] += len;
1474 				bus->uframe_usage[x] += len;
1475 			}
1476 		}
1477 		break;
1478 	default:
1479 		if (slot >= USB_HS_MICRO_FRAMES_MAX) {
1480 			slot = usb_intr_find_best_slot(bus->uframe_usage, 0,
1481 			    USB_HS_MICRO_FRAMES_MAX, mask);
1482 		}
1483 		for (x = slot; x < 8; x++) {
1484 			if (mask & (1U << (x - slot))) {
1485 				bus->uframe_usage[x] += len;
1486 			}
1487 		}
1488 		break;
1489 	}
1490 	return (slot);
1491 }
1492 
1493 /*------------------------------------------------------------------------*
1494  *	usb_hs_bandwidth_alloc
1495  *
1496  * This function is a wrapper function for "usb_hs_bandwidth_adjust()".
1497  *------------------------------------------------------------------------*/
1498 void
1499 usb_hs_bandwidth_alloc(struct usb_xfer *xfer)
1500 {
1501 	struct usb_device *udev;
1502 	uint8_t slot;
1503 	uint8_t mask;
1504 	uint8_t speed;
1505 
1506 	udev = xfer->xroot->udev;
1507 
1508 	if (udev->flags.usb_mode != USB_MODE_HOST)
1509 		return;		/* not supported */
1510 
1511 	xfer->endpoint->refcount_bw++;
1512 	if (xfer->endpoint->refcount_bw != 1)
1513 		return;		/* already allocated */
1514 
1515 	speed = usbd_get_speed(udev);
1516 
1517 	switch (xfer->endpoint->edesc->bmAttributes & UE_XFERTYPE) {
1518 	case UE_INTERRUPT:
1519 		/* allocate a microframe slot */
1520 
1521 		mask = 0x01;
1522 		slot = usb_hs_bandwidth_adjust(udev,
1523 		    xfer->max_frame_size, USB_HS_MICRO_FRAMES_MAX, mask);
1524 
1525 		xfer->endpoint->usb_uframe = slot;
1526 		xfer->endpoint->usb_smask = mask << slot;
1527 
1528 		if ((speed != USB_SPEED_FULL) &&
1529 		    (speed != USB_SPEED_LOW)) {
1530 			xfer->endpoint->usb_cmask = 0x00 ;
1531 		} else {
1532 			xfer->endpoint->usb_cmask = (-(0x04 << slot)) & 0xFE;
1533 		}
1534 		break;
1535 
1536 	case UE_ISOCHRONOUS:
1537 		switch (usbd_xfer_get_fps_shift(xfer)) {
1538 		case 0:
1539 			mask = 0xFF;
1540 			break;
1541 		case 1:
1542 			mask = 0x55;
1543 			break;
1544 		case 2:
1545 			mask = 0x11;
1546 			break;
1547 		default:
1548 			mask = 0x01;
1549 			break;
1550 		}
1551 
1552 		/* allocate a microframe multi-slot */
1553 
1554 		slot = usb_hs_bandwidth_adjust(udev,
1555 		    xfer->max_frame_size, USB_HS_MICRO_FRAMES_MAX, mask);
1556 
1557 		xfer->endpoint->usb_uframe = slot;
1558 		xfer->endpoint->usb_cmask = 0;
1559 		xfer->endpoint->usb_smask = mask << slot;
1560 		break;
1561 
1562 	default:
1563 		xfer->endpoint->usb_uframe = 0;
1564 		xfer->endpoint->usb_cmask = 0;
1565 		xfer->endpoint->usb_smask = 0;
1566 		break;
1567 	}
1568 
1569 	DPRINTFN(11, "slot=%d, mask=0x%02x\n",
1570 	    xfer->endpoint->usb_uframe,
1571 	    xfer->endpoint->usb_smask >> xfer->endpoint->usb_uframe);
1572 }
1573 
1574 /*------------------------------------------------------------------------*
1575  *	usb_hs_bandwidth_free
1576  *
1577  * This function is a wrapper function for "usb_hs_bandwidth_adjust()".
1578  *------------------------------------------------------------------------*/
1579 void
1580 usb_hs_bandwidth_free(struct usb_xfer *xfer)
1581 {
1582 	struct usb_device *udev;
1583 	uint8_t slot;
1584 	uint8_t mask;
1585 
1586 	udev = xfer->xroot->udev;
1587 
1588 	if (udev->flags.usb_mode != USB_MODE_HOST)
1589 		return;		/* not supported */
1590 
1591 	xfer->endpoint->refcount_bw--;
1592 	if (xfer->endpoint->refcount_bw != 0)
1593 		return;		/* still allocated */
1594 
1595 	switch (xfer->endpoint->edesc->bmAttributes & UE_XFERTYPE) {
1596 	case UE_INTERRUPT:
1597 	case UE_ISOCHRONOUS:
1598 
1599 		slot = xfer->endpoint->usb_uframe;
1600 		mask = xfer->endpoint->usb_smask;
1601 
1602 		/* free microframe slot(s): */
1603 		usb_hs_bandwidth_adjust(udev,
1604 		    -xfer->max_frame_size, slot, mask >> slot);
1605 
1606 		DPRINTFN(11, "slot=%d, mask=0x%02x\n",
1607 		    slot, mask >> slot);
1608 
1609 		xfer->endpoint->usb_uframe = 0;
1610 		xfer->endpoint->usb_cmask = 0;
1611 		xfer->endpoint->usb_smask = 0;
1612 		break;
1613 
1614 	default:
1615 		break;
1616 	}
1617 }
1618 
1619 /*------------------------------------------------------------------------*
1620  *	usbd_fs_isoc_schedule_init_sub
1621  *
1622  * This function initialises an USB FULL speed isochronous schedule
1623  * entry.
1624  *------------------------------------------------------------------------*/
1625 #if USB_HAVE_TT_SUPPORT
1626 static void
1627 usbd_fs_isoc_schedule_init_sub(struct usb_fs_isoc_schedule *fss)
1628 {
1629 	fss->total_bytes = (USB_FS_ISOC_UFRAME_MAX *
1630 	    USB_FS_BYTES_PER_HS_UFRAME);
1631 	fss->frame_bytes = (USB_FS_BYTES_PER_HS_UFRAME);
1632 	fss->frame_slot = 0;
1633 }
1634 #endif
1635 
1636 /*------------------------------------------------------------------------*
1637  *	usbd_fs_isoc_schedule_init_all
1638  *
1639  * This function will reset the complete USB FULL speed isochronous
1640  * bandwidth schedule.
1641  *------------------------------------------------------------------------*/
1642 #if USB_HAVE_TT_SUPPORT
1643 void
1644 usbd_fs_isoc_schedule_init_all(struct usb_fs_isoc_schedule *fss)
1645 {
1646 	struct usb_fs_isoc_schedule *fss_end = fss + USB_ISOC_TIME_MAX;
1647 
1648 	while (fss != fss_end) {
1649 		usbd_fs_isoc_schedule_init_sub(fss);
1650 		fss++;
1651 	}
1652 }
1653 #endif
1654 
1655 /*------------------------------------------------------------------------*
1656  *	usb_isoc_time_expand
1657  *
1658  * This function will expand the time counter from 7-bit to 16-bit.
1659  *
1660  * Returns:
1661  *   16-bit isochronous time counter.
1662  *------------------------------------------------------------------------*/
1663 uint16_t
1664 usb_isoc_time_expand(struct usb_bus *bus, uint16_t isoc_time_curr)
1665 {
1666 	uint16_t rem;
1667 
1668 	USB_BUS_LOCK_ASSERT(bus, MA_OWNED);
1669 
1670 	rem = bus->isoc_time_last & (USB_ISOC_TIME_MAX - 1);
1671 
1672 	isoc_time_curr &= (USB_ISOC_TIME_MAX - 1);
1673 
1674 	if (isoc_time_curr < rem) {
1675 		/* the time counter wrapped around */
1676 		bus->isoc_time_last += USB_ISOC_TIME_MAX;
1677 	}
1678 	/* update the remainder */
1679 
1680 	bus->isoc_time_last &= ~(USB_ISOC_TIME_MAX - 1);
1681 	bus->isoc_time_last |= isoc_time_curr;
1682 
1683 	return (bus->isoc_time_last);
1684 }
1685 
1686 /*------------------------------------------------------------------------*
1687  *	usbd_fs_isoc_schedule_isoc_time_expand
1688  *
1689  * This function does multiple things. First of all it will expand the
1690  * passed isochronous time, which is the return value. Then it will
1691  * store where the current FULL speed isochronous schedule is
1692  * positioned in time and where the end is. See "pp_start" and
1693  * "pp_end" arguments.
1694  *
1695  * Returns:
1696  *   Expanded version of "isoc_time".
1697  *
1698  * NOTE: This function depends on being called regularly with
1699  * intervals less than "USB_ISOC_TIME_MAX".
1700  *------------------------------------------------------------------------*/
1701 #if USB_HAVE_TT_SUPPORT
1702 uint16_t
1703 usbd_fs_isoc_schedule_isoc_time_expand(struct usb_device *udev,
1704     struct usb_fs_isoc_schedule **pp_start,
1705     struct usb_fs_isoc_schedule **pp_end,
1706     uint16_t isoc_time)
1707 {
1708 	struct usb_fs_isoc_schedule *fss_end;
1709 	struct usb_fs_isoc_schedule *fss_a;
1710 	struct usb_fs_isoc_schedule *fss_b;
1711 	struct usb_hub *hs_hub;
1712 
1713 	isoc_time = usb_isoc_time_expand(udev->bus, isoc_time);
1714 
1715 	hs_hub = udev->parent_hs_hub->hub;
1716 
1717 	if (hs_hub != NULL) {
1718 
1719 		fss_a = hs_hub->fs_isoc_schedule +
1720 		    (hs_hub->isoc_last_time % USB_ISOC_TIME_MAX);
1721 
1722 		hs_hub->isoc_last_time = isoc_time;
1723 
1724 		fss_b = hs_hub->fs_isoc_schedule +
1725 		    (isoc_time % USB_ISOC_TIME_MAX);
1726 
1727 		fss_end = hs_hub->fs_isoc_schedule + USB_ISOC_TIME_MAX;
1728 
1729 		*pp_start = hs_hub->fs_isoc_schedule;
1730 		*pp_end = fss_end;
1731 
1732 		while (fss_a != fss_b) {
1733 			if (fss_a == fss_end) {
1734 				fss_a = hs_hub->fs_isoc_schedule;
1735 				continue;
1736 			}
1737 			usbd_fs_isoc_schedule_init_sub(fss_a);
1738 			fss_a++;
1739 		}
1740 
1741 	} else {
1742 
1743 		*pp_start = NULL;
1744 		*pp_end = NULL;
1745 	}
1746 	return (isoc_time);
1747 }
1748 #endif
1749 
1750 /*------------------------------------------------------------------------*
1751  *	usbd_fs_isoc_schedule_alloc
1752  *
1753  * This function will allocate bandwidth for an isochronous FULL speed
1754  * transaction in the FULL speed schedule. The microframe slot where
1755  * the transaction should be started is stored in the byte pointed to
1756  * by "pstart". The "len" argument specifies the length of the
1757  * transaction in bytes.
1758  *
1759  * Returns:
1760  *    0: Success
1761  * Else: Error
1762  *------------------------------------------------------------------------*/
1763 #if USB_HAVE_TT_SUPPORT
1764 uint8_t
1765 usbd_fs_isoc_schedule_alloc(struct usb_fs_isoc_schedule *fss,
1766     uint8_t *pstart, uint16_t len)
1767 {
1768 	uint8_t slot = fss->frame_slot;
1769 
1770 	/* Compute overhead and bit-stuffing */
1771 
1772 	len += 8;
1773 
1774 	len *= 7;
1775 	len /= 6;
1776 
1777 	if (len > fss->total_bytes) {
1778 		*pstart = 0;		/* set some dummy value */
1779 		return (1);		/* error */
1780 	}
1781 	if (len > 0) {
1782 
1783 		fss->total_bytes -= len;
1784 
1785 		while (len >= fss->frame_bytes) {
1786 			len -= fss->frame_bytes;
1787 			fss->frame_bytes = USB_FS_BYTES_PER_HS_UFRAME;
1788 			fss->frame_slot++;
1789 		}
1790 
1791 		fss->frame_bytes -= len;
1792 	}
1793 	*pstart = slot;
1794 	return (0);			/* success */
1795 }
1796 #endif
1797 
1798 /*------------------------------------------------------------------------*
1799  *	usb_bus_port_get_device
1800  *
1801  * This function is NULL safe.
1802  *------------------------------------------------------------------------*/
1803 struct usb_device *
1804 usb_bus_port_get_device(struct usb_bus *bus, struct usb_port *up)
1805 {
1806 	if ((bus == NULL) || (up == NULL)) {
1807 		/* be NULL safe */
1808 		return (NULL);
1809 	}
1810 	if (up->device_index == 0) {
1811 		/* nothing to do */
1812 		return (NULL);
1813 	}
1814 	return (bus->devices[up->device_index]);
1815 }
1816 
1817 /*------------------------------------------------------------------------*
1818  *	usb_bus_port_set_device
1819  *
1820  * This function is NULL safe.
1821  *------------------------------------------------------------------------*/
1822 void
1823 usb_bus_port_set_device(struct usb_bus *bus, struct usb_port *up,
1824     struct usb_device *udev, uint8_t device_index)
1825 {
1826 	if (bus == NULL) {
1827 		/* be NULL safe */
1828 		return;
1829 	}
1830 	/*
1831 	 * There is only one case where we don't
1832 	 * have an USB port, and that is the Root Hub!
1833          */
1834 	if (up) {
1835 		if (udev) {
1836 			up->device_index = device_index;
1837 		} else {
1838 			device_index = up->device_index;
1839 			up->device_index = 0;
1840 		}
1841 	}
1842 	/*
1843 	 * Make relationships to our new device
1844 	 */
1845 	if (device_index != 0) {
1846 #if USB_HAVE_UGEN
1847 		mtx_lock(&usb_ref_lock);
1848 #endif
1849 		bus->devices[device_index] = udev;
1850 #if USB_HAVE_UGEN
1851 		mtx_unlock(&usb_ref_lock);
1852 #endif
1853 	}
1854 	/*
1855 	 * Debug print
1856 	 */
1857 	DPRINTFN(2, "bus %p devices[%u] = %p\n", bus, device_index, udev);
1858 }
1859 
1860 /*------------------------------------------------------------------------*
1861  *	usb_needs_explore
1862  *
1863  * This functions is called when the USB event thread needs to run.
1864  *------------------------------------------------------------------------*/
1865 void
1866 usb_needs_explore(struct usb_bus *bus, uint8_t do_probe)
1867 {
1868 	uint8_t do_unlock;
1869 
1870 	DPRINTF("\n");
1871 
1872 	if (bus == NULL) {
1873 		DPRINTF("No bus pointer!\n");
1874 		return;
1875 	}
1876 	if ((bus->devices == NULL) ||
1877 	    (bus->devices[USB_ROOT_HUB_ADDR] == NULL)) {
1878 		DPRINTF("No root HUB\n");
1879 		return;
1880 	}
1881 	if (mtx_owned(&bus->bus_mtx)) {
1882 		do_unlock = 0;
1883 	} else {
1884 		USB_BUS_LOCK(bus);
1885 		do_unlock = 1;
1886 	}
1887 	if (do_probe) {
1888 		bus->do_probe = 1;
1889 	}
1890 	if (usb_proc_msignal(&bus->explore_proc,
1891 	    &bus->explore_msg[0], &bus->explore_msg[1])) {
1892 		/* ignore */
1893 	}
1894 	if (do_unlock) {
1895 		USB_BUS_UNLOCK(bus);
1896 	}
1897 }
1898 
1899 /*------------------------------------------------------------------------*
1900  *	usb_needs_explore_all
1901  *
1902  * This function is called whenever a new driver is loaded and will
1903  * cause that all USB busses are re-explored.
1904  *------------------------------------------------------------------------*/
1905 void
1906 usb_needs_explore_all(void)
1907 {
1908 	struct usb_bus *bus;
1909 	devclass_t dc;
1910 	device_t dev;
1911 	int max;
1912 
1913 	DPRINTFN(3, "\n");
1914 
1915 	dc = usb_devclass_ptr;
1916 	if (dc == NULL) {
1917 		DPRINTFN(0, "no devclass\n");
1918 		return;
1919 	}
1920 	/*
1921 	 * Explore all USB busses in parallell.
1922 	 */
1923 	max = devclass_get_maxunit(dc);
1924 	while (max >= 0) {
1925 		dev = devclass_get_device(dc, max);
1926 		if (dev) {
1927 			bus = device_get_softc(dev);
1928 			if (bus) {
1929 				usb_needs_explore(bus, 1);
1930 			}
1931 		}
1932 		max--;
1933 	}
1934 }
1935 
1936 /*------------------------------------------------------------------------*
1937  *	usb_bus_power_update
1938  *
1939  * This function will ensure that all USB devices on the given bus are
1940  * properly suspended or resumed according to the device transfer
1941  * state.
1942  *------------------------------------------------------------------------*/
1943 #if USB_HAVE_POWERD
1944 void
1945 usb_bus_power_update(struct usb_bus *bus)
1946 {
1947 	usb_needs_explore(bus, 0 /* no probe */ );
1948 }
1949 #endif
1950 
1951 /*------------------------------------------------------------------------*
1952  *	usbd_transfer_power_ref
1953  *
1954  * This function will modify the power save reference counts and
1955  * wakeup the USB device associated with the given USB transfer, if
1956  * needed.
1957  *------------------------------------------------------------------------*/
1958 #if USB_HAVE_POWERD
1959 void
1960 usbd_transfer_power_ref(struct usb_xfer *xfer, int val)
1961 {
1962 	static const usb_power_mask_t power_mask[4] = {
1963 		[UE_CONTROL] = USB_HW_POWER_CONTROL,
1964 		[UE_BULK] = USB_HW_POWER_BULK,
1965 		[UE_INTERRUPT] = USB_HW_POWER_INTERRUPT,
1966 		[UE_ISOCHRONOUS] = USB_HW_POWER_ISOC,
1967 	};
1968 	struct usb_device *udev;
1969 	uint8_t needs_explore;
1970 	uint8_t needs_hw_power;
1971 	uint8_t xfer_type;
1972 
1973 	udev = xfer->xroot->udev;
1974 
1975 	if (udev->device_index == USB_ROOT_HUB_ADDR) {
1976 		/* no power save for root HUB */
1977 		return;
1978 	}
1979 	USB_BUS_LOCK(udev->bus);
1980 
1981 	xfer_type = xfer->endpoint->edesc->bmAttributes & UE_XFERTYPE;
1982 
1983 	udev->pwr_save.last_xfer_time = ticks;
1984 	udev->pwr_save.type_refs[xfer_type] += val;
1985 
1986 	if (xfer->flags_int.control_xfr) {
1987 		udev->pwr_save.read_refs += val;
1988 		if (xfer->flags_int.usb_mode == USB_MODE_HOST) {
1989 			/*
1990 			 * It is not allowed to suspend during a
1991 			 * control transfer:
1992 			 */
1993 			udev->pwr_save.write_refs += val;
1994 		}
1995 	} else if (USB_GET_DATA_ISREAD(xfer)) {
1996 		udev->pwr_save.read_refs += val;
1997 	} else {
1998 		udev->pwr_save.write_refs += val;
1999 	}
2000 
2001 	if (val > 0) {
2002 		if (udev->flags.self_suspended)
2003 			needs_explore = usb_peer_should_wakeup(udev);
2004 		else
2005 			needs_explore = 0;
2006 
2007 		if (!(udev->bus->hw_power_state & power_mask[xfer_type])) {
2008 			DPRINTF("Adding type %u to power state\n", xfer_type);
2009 			udev->bus->hw_power_state |= power_mask[xfer_type];
2010 			needs_hw_power = 1;
2011 		} else {
2012 			needs_hw_power = 0;
2013 		}
2014 	} else {
2015 		needs_explore = 0;
2016 		needs_hw_power = 0;
2017 	}
2018 
2019 	USB_BUS_UNLOCK(udev->bus);
2020 
2021 	if (needs_explore) {
2022 		DPRINTF("update\n");
2023 		usb_bus_power_update(udev->bus);
2024 	} else if (needs_hw_power) {
2025 		DPRINTF("needs power\n");
2026 		if (udev->bus->methods->set_hw_power != NULL) {
2027 			(udev->bus->methods->set_hw_power) (udev->bus);
2028 		}
2029 	}
2030 }
2031 #endif
2032 
2033 /*------------------------------------------------------------------------*
2034  *	usb_peer_should_wakeup
2035  *
2036  * This function returns non-zero if the current device should wake up.
2037  *------------------------------------------------------------------------*/
2038 static uint8_t
2039 usb_peer_should_wakeup(struct usb_device *udev)
2040 {
2041 	return ((udev->power_mode == USB_POWER_MODE_ON) ||
2042 	    (udev->driver_added_refcount != udev->bus->driver_added_refcount) ||
2043 	    (udev->re_enumerate_wait != 0) ||
2044 	    (udev->pwr_save.type_refs[UE_ISOCHRONOUS] != 0) ||
2045 	    (udev->pwr_save.write_refs != 0) ||
2046 	    ((udev->pwr_save.read_refs != 0) &&
2047 	    (udev->flags.usb_mode == USB_MODE_HOST) &&
2048 	    (usb_device_20_compatible(udev) != 0) &&
2049 	    (usb_peer_can_wakeup(udev) == 0)));
2050 }
2051 
2052 /*------------------------------------------------------------------------*
2053  *	usb_bus_powerd
2054  *
2055  * This function implements the USB power daemon and is called
2056  * regularly from the USB explore thread.
2057  *------------------------------------------------------------------------*/
2058 #if USB_HAVE_POWERD
2059 void
2060 usb_bus_powerd(struct usb_bus *bus)
2061 {
2062 	struct usb_device *udev;
2063 	usb_ticks_t temp;
2064 	usb_ticks_t limit;
2065 	usb_ticks_t mintime;
2066 	usb_size_t type_refs[5];
2067 	uint8_t x;
2068 
2069 	limit = usb_power_timeout;
2070 	if (limit == 0)
2071 		limit = hz;
2072 	else if (limit > 255)
2073 		limit = 255 * hz;
2074 	else
2075 		limit = limit * hz;
2076 
2077 	DPRINTF("bus=%p\n", bus);
2078 
2079 	USB_BUS_LOCK(bus);
2080 
2081 	/*
2082 	 * The root HUB device is never suspended
2083 	 * and we simply skip it.
2084 	 */
2085 	for (x = USB_ROOT_HUB_ADDR + 1;
2086 	    x != bus->devices_max; x++) {
2087 
2088 		udev = bus->devices[x];
2089 		if (udev == NULL)
2090 			continue;
2091 
2092 		temp = ticks - udev->pwr_save.last_xfer_time;
2093 
2094 		if (usb_peer_should_wakeup(udev)) {
2095 			/* check if we are suspended */
2096 			if (udev->flags.self_suspended != 0) {
2097 				USB_BUS_UNLOCK(bus);
2098 				usb_dev_resume_peer(udev);
2099 				USB_BUS_LOCK(bus);
2100 			}
2101 		} else if ((temp >= limit) &&
2102 		    (udev->flags.usb_mode == USB_MODE_HOST) &&
2103 		    (udev->flags.self_suspended == 0)) {
2104 			/* try to do suspend */
2105 
2106 			USB_BUS_UNLOCK(bus);
2107 			usb_dev_suspend_peer(udev);
2108 			USB_BUS_LOCK(bus);
2109 		}
2110 	}
2111 
2112 	/* reset counters */
2113 
2114 	mintime = 0 - 1;
2115 	type_refs[0] = 0;
2116 	type_refs[1] = 0;
2117 	type_refs[2] = 0;
2118 	type_refs[3] = 0;
2119 	type_refs[4] = 0;
2120 
2121 	/* Re-loop all the devices to get the actual state */
2122 
2123 	for (x = USB_ROOT_HUB_ADDR + 1;
2124 	    x != bus->devices_max; x++) {
2125 
2126 		udev = bus->devices[x];
2127 		if (udev == NULL)
2128 			continue;
2129 
2130 		/* we found a non-Root-Hub USB device */
2131 		type_refs[4] += 1;
2132 
2133 		/* "last_xfer_time" can be updated by a resume */
2134 		temp = ticks - udev->pwr_save.last_xfer_time;
2135 
2136 		/*
2137 		 * Compute minimum time since last transfer for the complete
2138 		 * bus:
2139 		 */
2140 		if (temp < mintime)
2141 			mintime = temp;
2142 
2143 		if (udev->flags.self_suspended == 0) {
2144 			type_refs[0] += udev->pwr_save.type_refs[0];
2145 			type_refs[1] += udev->pwr_save.type_refs[1];
2146 			type_refs[2] += udev->pwr_save.type_refs[2];
2147 			type_refs[3] += udev->pwr_save.type_refs[3];
2148 		}
2149 	}
2150 
2151 	if (mintime >= (1 * hz)) {
2152 		/* recompute power masks */
2153 		DPRINTF("Recomputing power masks\n");
2154 		bus->hw_power_state = 0;
2155 		if (type_refs[UE_CONTROL] != 0)
2156 			bus->hw_power_state |= USB_HW_POWER_CONTROL;
2157 		if (type_refs[UE_BULK] != 0)
2158 			bus->hw_power_state |= USB_HW_POWER_BULK;
2159 		if (type_refs[UE_INTERRUPT] != 0)
2160 			bus->hw_power_state |= USB_HW_POWER_INTERRUPT;
2161 		if (type_refs[UE_ISOCHRONOUS] != 0)
2162 			bus->hw_power_state |= USB_HW_POWER_ISOC;
2163 		if (type_refs[4] != 0)
2164 			bus->hw_power_state |= USB_HW_POWER_NON_ROOT_HUB;
2165 	}
2166 	USB_BUS_UNLOCK(bus);
2167 
2168 	if (bus->methods->set_hw_power != NULL) {
2169 		/* always update hardware power! */
2170 		(bus->methods->set_hw_power) (bus);
2171 	}
2172 	return;
2173 }
2174 #endif
2175 
2176 /*------------------------------------------------------------------------*
2177  *	usb_dev_resume_peer
2178  *
2179  * This function will resume an USB peer and do the required USB
2180  * signalling to get an USB device out of the suspended state.
2181  *------------------------------------------------------------------------*/
2182 static void
2183 usb_dev_resume_peer(struct usb_device *udev)
2184 {
2185 	struct usb_bus *bus;
2186 	int err;
2187 
2188 	/* be NULL safe */
2189 	if (udev == NULL)
2190 		return;
2191 
2192 	/* check if already resumed */
2193 	if (udev->flags.self_suspended == 0)
2194 		return;
2195 
2196 	/* we need a parent HUB to do resume */
2197 	if (udev->parent_hub == NULL)
2198 		return;
2199 
2200 	DPRINTF("udev=%p\n", udev);
2201 
2202 	if ((udev->flags.usb_mode == USB_MODE_DEVICE) &&
2203 	    (udev->flags.remote_wakeup == 0)) {
2204 		/*
2205 		 * If the host did not set the remote wakeup feature, we can
2206 		 * not wake it up either!
2207 		 */
2208 		DPRINTF("remote wakeup is not set!\n");
2209 		return;
2210 	}
2211 	/* get bus pointer */
2212 	bus = udev->bus;
2213 
2214 	/* resume parent hub first */
2215 	usb_dev_resume_peer(udev->parent_hub);
2216 
2217 	/* reduce chance of instant resume failure by waiting a little bit */
2218 	usb_pause_mtx(NULL, USB_MS_TO_TICKS(20));
2219 
2220 	if (usb_device_20_compatible(udev)) {
2221 		/* resume current port (Valid in Host and Device Mode) */
2222 		err = usbd_req_clear_port_feature(udev->parent_hub,
2223 		    NULL, udev->port_no, UHF_PORT_SUSPEND);
2224 		if (err) {
2225 			DPRINTFN(0, "Resuming port failed\n");
2226 			return;
2227 		}
2228 	}
2229 
2230 	/* resume settle time */
2231 	usb_pause_mtx(NULL, USB_MS_TO_TICKS(USB_PORT_RESUME_DELAY));
2232 
2233 	if (bus->methods->device_resume != NULL) {
2234 		/* resume USB device on the USB controller */
2235 		(bus->methods->device_resume) (udev);
2236 	}
2237 	USB_BUS_LOCK(bus);
2238 	/* set that this device is now resumed */
2239 	udev->flags.self_suspended = 0;
2240 #if USB_HAVE_POWERD
2241 	/* make sure that we don't go into suspend right away */
2242 	udev->pwr_save.last_xfer_time = ticks;
2243 
2244 	/* make sure the needed power masks are on */
2245 	if (udev->pwr_save.type_refs[UE_CONTROL] != 0)
2246 		bus->hw_power_state |= USB_HW_POWER_CONTROL;
2247 	if (udev->pwr_save.type_refs[UE_BULK] != 0)
2248 		bus->hw_power_state |= USB_HW_POWER_BULK;
2249 	if (udev->pwr_save.type_refs[UE_INTERRUPT] != 0)
2250 		bus->hw_power_state |= USB_HW_POWER_INTERRUPT;
2251 	if (udev->pwr_save.type_refs[UE_ISOCHRONOUS] != 0)
2252 		bus->hw_power_state |= USB_HW_POWER_ISOC;
2253 #endif
2254 	USB_BUS_UNLOCK(bus);
2255 
2256 	if (bus->methods->set_hw_power != NULL) {
2257 		/* always update hardware power! */
2258 		(bus->methods->set_hw_power) (bus);
2259 	}
2260 
2261 	usbd_sr_lock(udev);
2262 
2263 	/* notify all sub-devices about resume */
2264 	err = usb_suspend_resume(udev, 0);
2265 
2266 	usbd_sr_unlock(udev);
2267 
2268 	/* check if peer has wakeup capability */
2269 	if (usb_peer_can_wakeup(udev) &&
2270 	    usb_device_20_compatible(udev)) {
2271 		/* clear remote wakeup */
2272 		err = usbd_req_clear_device_feature(udev,
2273 		    NULL, UF_DEVICE_REMOTE_WAKEUP);
2274 		if (err) {
2275 			DPRINTFN(0, "Clearing device "
2276 			    "remote wakeup failed: %s\n",
2277 			    usbd_errstr(err));
2278 		}
2279 	}
2280 }
2281 
2282 /*------------------------------------------------------------------------*
2283  *	usb_dev_suspend_peer
2284  *
2285  * This function will suspend an USB peer and do the required USB
2286  * signalling to get an USB device into the suspended state.
2287  *------------------------------------------------------------------------*/
2288 static void
2289 usb_dev_suspend_peer(struct usb_device *udev)
2290 {
2291 	struct usb_device *child;
2292 	int err;
2293 	uint8_t x;
2294 	uint8_t nports;
2295 
2296 repeat:
2297 	/* be NULL safe */
2298 	if (udev == NULL)
2299 		return;
2300 
2301 	/* check if already suspended */
2302 	if (udev->flags.self_suspended)
2303 		return;
2304 
2305 	/* we need a parent HUB to do suspend */
2306 	if (udev->parent_hub == NULL)
2307 		return;
2308 
2309 	DPRINTF("udev=%p\n", udev);
2310 
2311 	/* check if the current device is a HUB */
2312 	if (udev->hub != NULL) {
2313 		nports = udev->hub->nports;
2314 
2315 		/* check if all devices on the HUB are suspended */
2316 		for (x = 0; x != nports; x++) {
2317 			child = usb_bus_port_get_device(udev->bus,
2318 			    udev->hub->ports + x);
2319 
2320 			if (child == NULL)
2321 				continue;
2322 
2323 			if (child->flags.self_suspended)
2324 				continue;
2325 
2326 			DPRINTFN(1, "Port %u is busy on the HUB!\n", x + 1);
2327 			return;
2328 		}
2329 	}
2330 
2331 	if (usb_peer_can_wakeup(udev) &&
2332 	    usb_device_20_compatible(udev)) {
2333 		/*
2334 		 * This request needs to be done before we set
2335 		 * "udev->flags.self_suspended":
2336 		 */
2337 
2338 		/* allow device to do remote wakeup */
2339 		err = usbd_req_set_device_feature(udev,
2340 		    NULL, UF_DEVICE_REMOTE_WAKEUP);
2341 		if (err) {
2342 			DPRINTFN(0, "Setting device "
2343 			    "remote wakeup failed\n");
2344 		}
2345 	}
2346 
2347 	USB_BUS_LOCK(udev->bus);
2348 	/*
2349 	 * Checking for suspend condition and setting suspended bit
2350 	 * must be atomic!
2351 	 */
2352 	err = usb_peer_should_wakeup(udev);
2353 	if (err == 0) {
2354 		/*
2355 		 * Set that this device is suspended. This variable
2356 		 * must be set before calling USB controller suspend
2357 		 * callbacks.
2358 		 */
2359 		udev->flags.self_suspended = 1;
2360 	}
2361 	USB_BUS_UNLOCK(udev->bus);
2362 
2363 	if (err != 0) {
2364 		if (usb_peer_can_wakeup(udev) &&
2365 		    usb_device_20_compatible(udev)) {
2366 			/* allow device to do remote wakeup */
2367 			err = usbd_req_clear_device_feature(udev,
2368 			    NULL, UF_DEVICE_REMOTE_WAKEUP);
2369 			if (err) {
2370 				DPRINTFN(0, "Setting device "
2371 				    "remote wakeup failed\n");
2372 			}
2373 		}
2374 
2375 		if (udev->flags.usb_mode == USB_MODE_DEVICE) {
2376 			/* resume parent HUB first */
2377 			usb_dev_resume_peer(udev->parent_hub);
2378 
2379 			/* reduce chance of instant resume failure by waiting a little bit */
2380 			usb_pause_mtx(NULL, USB_MS_TO_TICKS(20));
2381 
2382 			/* resume current port (Valid in Host and Device Mode) */
2383 			err = usbd_req_clear_port_feature(udev->parent_hub,
2384 			    NULL, udev->port_no, UHF_PORT_SUSPEND);
2385 
2386 			/* resume settle time */
2387 			usb_pause_mtx(NULL, USB_MS_TO_TICKS(USB_PORT_RESUME_DELAY));
2388 		}
2389 		DPRINTF("Suspend was cancelled!\n");
2390 		return;
2391 	}
2392 
2393 	usbd_sr_lock(udev);
2394 
2395 	/* notify all sub-devices about suspend */
2396 	err = usb_suspend_resume(udev, 1);
2397 
2398 	usbd_sr_unlock(udev);
2399 
2400 	if (udev->bus->methods->device_suspend != NULL) {
2401 		usb_timeout_t temp;
2402 
2403 		/* suspend device on the USB controller */
2404 		(udev->bus->methods->device_suspend) (udev);
2405 
2406 		/* do DMA delay */
2407 		temp = usbd_get_dma_delay(udev);
2408 		if (temp != 0)
2409 			usb_pause_mtx(NULL, USB_MS_TO_TICKS(temp));
2410 
2411 	}
2412 
2413 	if (usb_device_20_compatible(udev)) {
2414 		/* suspend current port */
2415 		err = usbd_req_set_port_feature(udev->parent_hub,
2416 		    NULL, udev->port_no, UHF_PORT_SUSPEND);
2417 		if (err) {
2418 			DPRINTFN(0, "Suspending port failed\n");
2419 			return;
2420 		}
2421 	}
2422 
2423 	udev = udev->parent_hub;
2424 	goto repeat;
2425 }
2426 
2427 /*------------------------------------------------------------------------*
2428  *	usbd_set_power_mode
2429  *
2430  * This function will set the power mode, see USB_POWER_MODE_XXX for a
2431  * USB device.
2432  *------------------------------------------------------------------------*/
2433 void
2434 usbd_set_power_mode(struct usb_device *udev, uint8_t power_mode)
2435 {
2436 	/* filter input argument */
2437 	if ((power_mode != USB_POWER_MODE_ON) &&
2438 	    (power_mode != USB_POWER_MODE_OFF))
2439 		power_mode = USB_POWER_MODE_SAVE;
2440 
2441 	power_mode = usbd_filter_power_mode(udev, power_mode);
2442 
2443 	udev->power_mode = power_mode;	/* update copy of power mode */
2444 
2445 #if USB_HAVE_POWERD
2446 	usb_bus_power_update(udev->bus);
2447 #endif
2448 }
2449 
2450 /*------------------------------------------------------------------------*
2451  *	usbd_filter_power_mode
2452  *
2453  * This function filters the power mode based on hardware requirements.
2454  *------------------------------------------------------------------------*/
2455 uint8_t
2456 usbd_filter_power_mode(struct usb_device *udev, uint8_t power_mode)
2457 {
2458 	struct usb_bus_methods *mtod;
2459 	int8_t temp;
2460 
2461 	mtod = udev->bus->methods;
2462 	temp = -1;
2463 
2464 	if (mtod->get_power_mode != NULL)
2465 		(mtod->get_power_mode) (udev, &temp);
2466 
2467 	/* check if we should not filter */
2468 	if (temp < 0)
2469 		return (power_mode);
2470 
2471 	/* use fixed power mode given by hardware driver */
2472 	return (temp);
2473 }
2474