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
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.
12 .\" Copyright 2016 Joyent, Inc.
20 .Nd USBA Device Data Structure
22 .In sys/usb/usba/hcdi.h
25 illumos USB HCD private
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.
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
39 Many of the USB HCD driver operations pass a
41 to the HCD driver. The
43 should be used by an HCD driver in a
45 fashion. A subset of the structure's fields that are useful for HCD
46 drivers to read are listed below.
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
53 .Xr usba_hcdi_device_fini 9E
54 functions, then the private data stored from
55 .Xr usba_hcdi_device_init 9E
57 .Xr usba_hcdi_get_device_private 9F .
61 structure includes the following members:
62 .Bd -literal -offset indent
64 usba_hubdi_t *usb_hubdi;
66 usb_dev_descr_t *usb_dev_descr;
68 char *usb_product_str;
69 char *usb_serialno_str;
70 usb_port_status_t usb_port_status;
72 usba_device_t *usb_hs_hub_usba_dev;
73 usba_device_t *usb_parent_hub;
78 member is a pointer to the device's
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
85 .Xr usba_pipe_handle_data_t 9S .
89 member can be used to determine whether or not the
91 in question is a hub or not. HCD drivers should compare this member to
95 then this USB device corresponds to a hub.
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
107 for more information.
111 member points to the device descriptor for a given device. This
112 structure is documented in
113 .Xr usb_dev_descr 9S .
116 as it may not have been populated during device
117 attachment. This member may be
119 HCD drivers should always check for
121 before dereferencing it.
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
128 HCD drivers should always check for
130 before dereferencing it.
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
137 HCD drivers should always check for
139 before dereferencing it.
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
146 HCD drivers should always check for
148 before dereferencing it.
151 .Sy usb_port_status_t
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.
160 member contains the port on a hub that the device is plugged into. Ports
161 are always numbered starting at 1.
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
169 structure that is the closest high-speed parent hub. This member should
172 for super-speed devices. A device operating a super-speed can never be
173 plugged into a high-speed hub.
179 structure that the device in question is plugged into. If the device
180 represents the root hub, then this field will be
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