1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Joyent, Inc.
13 .\"
14 .Dd Sep 16, 2016
15 .Dt USBA_HCDI_BIND_ROOT_HUB 9F
16 .Os
17 .Sh NAME
18 .Nm usba_hubdi_bind_root_hub ,
19 .Nm usba_hubdi_unbind_root_hub
20 .Nd bind and unbind the root USB hub
21 .Sh SYNOPSIS
22 .In sys/usb/usba/hubdi.h
23 .Ft int
24 .Fo usba_hubdi_bind_root_hub
25 .Fa "dev_info_t *dip"
26 .Fa "uchar_t *hub_descr"
27 .Fa "size_t descr_len"
28 .Fa "usb_dev_descr_t *dev_descr"
29 .Fc
30 .Ft int
31 .Fo usba_hubdi_unbind_root_hub
32 .Fa "dev_info_t *dip"
33 .Fc
34 .Sh INTERFACE LEVEL
35 .Sy Volatile -
36 illumos USB HCD private function
37 .Pp
38 This is a private function that is not part of the stable DDI.
39 It may be removed or changed at any time.
40 .Sh PARAMETERS
41 .Bl -tag -width Fa
42 .It Fa dip
43 Pointer to the device's
44 .Sy dev_info
45 structure.
46 .It Fa hub_descr
47 Pointer to a byte array that contains the standard descriptors for a USB
48 Hub device.
49 .It Fa descr_len
50 The length in bytes of the
51 .Fa hub_descr
52 byte array.
53 .It Fa dev_descr
54 A filled in standard USB device descriptor.
55 .El
56 .Sh DESCRIPTION
57 The
58 .Fn usba_hubdi_bind_root_hub
59 and
60 .Fn usba_hubdi_unbind_root_hub
61 functions are used to bind and unbind the root USB hub that is a part of
62 every HCD driver.
63 See
64 .Xr usba_hcdi 9E
65 for more information on this relationship.
66 .Pp
67 The
68 .Fn usba_hubdi_root_bind_driver
69 is used after calling the
70 .Xr usba_hcdi_register 9F
71 function during a device's
72 .Xr attach 9E
73 entry point.
74 .Pp
75 Because the root hub is generally a virtual hub, the HCD driver is
76 responsible for making it appear to the system as a normal USB hub.
77 .Pp
78 The contents of the
79 .Fa hub_descr
80 should be the standard USB Hub class-specific descriptor.
81 This hub descriptor should match a hub of a similar class of speed.
82 For example, with the xhci controller, a USB 3.x Hub class-specific descriptor
83 is used, where as for the ehci controller, a USB 2.x Hub class-specific
84 descriptor is used.
85 For more information, see the USB 3.1 specification, section 10.15.2
86 .Em Class-specific Descriptors .
87 .Pp
88 Similarly, the contents of the
89 .Fa dev_descr
90 need to be a filled in USB device descriptor that indicates that the
91 root hub corresponds to the appropriate USB generation.
92 For more information on the contents, see
93 .Xr usb_dev_descr 9S
94 and the USB 3.1 specification, section 10.15.1
95 .Em Standard Descriptors for Hub Class .
96 .Pp
97 The
98 .Fn usba_hubdi_unbind_root_hub
99 function is used to detach the root hub associated with the HCD driver.
100 This should be called during a device's
101 .Xr detach 9E
102 routine before calling
103 .Xr usba_hcdi_unregister 9F .
104 .Pp
105 If a call to the
106 .Fn usba_hubdi_unbind_root_hub
107 function fails during a device's
108 .Xr detach 9E
109 function, then it should fail the call to
110 .Xr detach 9E .
111 .Sh CONTEXT
112 The
113 .Fn usba_hubdi_bind_root_hub
114 function should only be called during a device's
115 .Xr attach 9E
116 entry point.
117 .Pp
118 The
119 .Fn usba_hubdi_unbind_root_hub
120 function should only be called during a device's
121 .Xr detach 9E entry point.
122 .Sh RETURN VALUES
123 Upon successful completion, the
124 .Fn usba_hubdi_bind_root_hub
125 and
126 .Fn usba_hubdi_unbind_root_hub
127 functions return
128 .Sy USB_SUCCESS .
129 Otherwise, they return
130 .Sy USB_FAILURE
131 to indicate that they could not proceed.
132 .Sh SEE ALSO
133 .Xr attach 9E ,
134 .Xr detach 9E ,
135 .Xr usba_hcdi 9E ,
136 .Xr usba_hcdi_register 9F ,
137 .Xr usba_hcdi_unregister 9F ,
138 .Xr usb_dev_Descr 9S