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