| blob | 036e50feed6f66a93a3abf5e3571ed5857464743 |
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 Dec 20, 2016
15 .Dt USBA_DEVICE 9S
16 .Os
17 .Sh NAME
18 .Nm usba_device ,
19 .Nm usba_device_t
20 .Nd USBA Device Data Structure
21 .Sh SYNOPSIS
22 .In sys/usb/usba/hcdi.h
23 .Sh INTERFACE LEVEL
24 .Sy Volatile -
25 illumos USB HCD private
26 .Pp
27 This is a private data structure that is not part of the stable DDI.
28 It may be removed or changed at any time.
29 .Sh DESCRIPTION
30 The
31 .Sy usba_device_t
32 structure is used by the illumos USB Architecture (USBA) to represent a
33 physical USB device.
34 While a given USB device may be a composite device, a USB device that implements
35 two or more classes, there will still only be a single device structure.
36 A USB device is always plugged into a port on some hub, excepting the root hub,
37 and has an address on the USB fabric.
38 .Pp
39 Many of the USB HCD driver operations pass a
40 .Sy usba_device_t
41 to the HCD driver.
42 The
43 .Sy usba_device_t
44 should be used by an HCD driver in a
45 .Em read-only
46 fashion.
47 A subset of the structure's fields that are useful for HCD drivers to read are
48 listed below.
49 .Pp
50 In addition, there are two optional HCD entry points that interact with
51 this structure and give the change for a driver to store per-device
52 state.
53 If the driver implements the
54 .Xr usba_hcdi_device_init 9E
55 and
56 .Xr usba_hcdi_device_fini 9E
57 functions, then the private data stored from
58 .Xr usba_hcdi_device_init 9E
59 can be retrieved with
60 .Xr usba_hcdi_get_device_private 9F .
61 .Sh STRUCTURE MEMBERS
62 The
63 .Sy usba_device_t
64 structure includes the following members:
65 .Bd -literal -offset indent
66 dev_info_t *usb_dip
67 usba_hubdi_t *usb_hubdi;
68 usb_addr_t usb_addr;
69 usb_dev_descr_t *usb_dev_descr;
70 char *usb_mfg_str;
71 char *usb_product_str;
72 char *usb_serialno_str;
73 usb_port_status_t usb_port_status;
74 usb_port_t usb_port;
75 usba_device_t *usb_hs_hub_usba_dev;
76 usba_device_t *usb_parent_hub;
77 .Ed
78 .Pp
79 The
80 .Sy usb_dip
81 member is a pointer to the device's
82 .Sy dev_info_t
83 structure.
84 This generally is used if the HCD driver wants to get naming information for
85 diagnostic purposes.
86 When duplicating requests for isochronous and interrupt requests, HCD drivers
87 should use the
88 .Sy dev_info_t
89 from the
90 .Xr usba_pipe_handle_data_t 9S .
91 .Pp
92 The
93 .Sy usb_hubdi
94 member can be used to determine whether or not the
95 .Sy usba_device_t
96 in question is a hub or not.
97 HCD drivers should compare this member to
98 .Dv NULL .
99 If the member is not
100 .Dv NULL ,
101 then this USB device corresponds to a hub.
102 .Pp
103 the
104 .Sy usb_addr
105 member indicates the address of the USB device on the broader USB bus.
106 Note, that the actual address assigned to the device may be different,
107 especially if the HCD driver implements the optional
108 .Xr usba_hcdi_device_address 9E
109 entry point.
110 See the section
111 .Sy USB addressing
112 in
113 .Xr usba_hcdi 9E
114 for more information.
115 .Pp
116 The
117 .Sy usb_dev_descr
118 member points to the device descriptor for a given device.
119 This structure is documented in
120 .Xr usb_dev_descr 9S .
121 This member may be
122 .Dv NULL
123 as it may not have been populated during device
124 attachment.
125 This member may be
126 .Dv NULL .
127 HCD drivers should always check for
128 .Dv NULL
129 before dereferencing it.
130 .Pp
131 The
132 .Sy usb_mfg_str
133 member may contain a pointer to a character string with the name of the
134 manufacturer as retrieved from the device.
135 This member may be
136 .Dv NULL .
137 HCD drivers should always check for
138 .Dv NULL
139 before dereferencing it.
140 .Pp
141 The
142 .Sy usb_product_str
143 member may contain a pointer to a character string with the name of the
144 product as retrieved from the device.
145 This member may be
146 .Dv NULL .
147 HCD drivers should always check for
148 .Dv NULL
149 before dereferencing it.
150 .Pp
151 The
152 .Sy usb_serialno_str
153 member may contain a pointer to a character string with the serial
154 number of the device as retrieved from the device.
155 This member may be
156 .Dv NULL .
157 HCD drivers should always check for
158 .Dv NULL
159 before dereferencing it.
160 .Pp
161 The
162 .Sy usb_port_status
163 contains a
164 .Xr usb_port_status_t 9T
165 entry, which describes the current negotiated speed of the device.
166 See
167 .Xr usb_port_status_t 9T
168 for more information on the values and types.
169 .Pp
170 The
171 .Sy usb_port
172 member contains the port on a hub that the device is plugged into.
173 Ports are always numbered starting at 1.
174 .Pp
175 The
176 .Sy usb_hs_hub_usba_dev
177 member is set when there is a parent high-speed hub.
178 This is most notable for low- and full- speed devices which require split
179 transaction support.
180 This points to the
181 .Sy usb_device_t
182 structure that is the closest high-speed parent hub.
183 This member should
184 always be set to
185 .Dv NULL
186 for super-speed devices.
187 A device operating a super-speed can never be plugged into a high-speed hub.
188 .Pp
189 The
190 .Sy usb_parent_hub
191 member points to the
192 .Sy usba_device_t
193 structure that the device in question is plugged into.
194 If the device represents the root hub, then this field will be
195 .Dv NULL .
196 .Sh SEE ALSO
197 .Xr usba_hcdi 9E ,
198 .Xr usba_hcdi_device_address 9E ,
199 .Xr usba_hcdi_device_fini 9E ,
200 .Xr usba_hcdi_device_init 9E ,
201 .Xr usba_pipe_handle_data_t 9S ,
202 .Xr usb_port_status_t 9T