1usb_client_dev_data(9S) Data Structures for Drivers usb_client_dev_data(9S)
2
6 usb_client_dev_data - Device configuration information
7
9 #include <sys/usb/usba.h>
10
13 Solaris DDI specific (Solaris DDI)
14
16 The usb_client_dev_data_t structure carries all device configuration
17 information. It is provided to a USB client driver through a call to
18 usb_get_dev_data(9F). Most USBA functions require information which
19 comes from this structure.
20 The usb_client_dev_data_t structure fields are:
23 usb_pipe_handle_t dev_default_ph; /* deflt ctrl pipe handle */
25 ddi_iblock_cookie_t dev_iblock_cookie;/* for calls to mutex_init */
27 /* for mutexes used by intr */
28 /* context callbacks. */
29 usb_dev_descr_t *dev_descr; /* parsed* dev. descriptor */
31 char *dev_mfg; /* manufacturer's ID string */
33 char *dev_product; /* product ID string */
35 char *dev_serial; /* serial num. string */
37 usb_reg_parse_lvl_t dev_parse_level; /* Parse level */
39 /* reflecting the tree */
40 /* (if any) returned through */
41 /* the dev_cfg array. */
42 usb_cfg_data_t *dev_cfg; /* parsed* descr tree.*/
44 uint_t dev_n_cfg; /* num cfgs in parsed descr. */
46 /* tree, dev_cfg array below.*/
47 usb_cfg_data_t *dev_curr_cfg; /* Pointer to the tree config*/
49 /* corresponding to the cfg */
50 /* active at the time of the */
51 /* usb_get_dev_data() call */
52 int dev_curr_if; /* First active interface in */
54 /* tree under driver's control.*/
55 /* Always zero when driver */
57 /* controls whole device. */
58 * A parsed descriptor is in a struct whose fields' have been adjusted
60 to the host processor. This may include endianness adjustment (the USB
61 standard defines that devices report in little-endian bit order) or
62 structure padding as necessary.
63 dev_parse_level represents the extent of the device represented by the
67 tree returned by the dev_cfg field and has the following possible val‐
68 ues:
69 USB_PARSE_LVL_NONE Build no tree. dev_n_cfg returns 0, dev_cfg and
71 dev_curr_cfg are returned NULL, the dev_curr_xxx
72 fields are invalid.
73 USB_PARSE_LVL_IF Parse configured interface only, if configura‐
76 tion# and interface properties are set (as when
77 different interfaces are viewed by the OS as dif‐
78 ferent device instances). If an OS device
79 instance is set up to represent an entire physi‐
80 cal device, this works like USB_PARSE_LVL_ALL.
81 USB_PARSE_LVL_CFG Parse entire configuration of configured inter‐
84 face only. This is like USB_PARSE_LVL_IF except
85 entire configuration is returned.
86 USB_PARSE_LVL_ALL Parse entire device (all configurations), even
89 when driver is bound to a single interface of a
90 single configuration.
91 The default control pipe handle is used mainly for control commands and
95 device setup.
96 The dev_iblock_cookie is used to initialize client driver mutexes which
99 are used in interrupt-context callback handlers. (All callback han‐
100 dlers called with USB_CB_INTR_CONTEXT in their usb_cb_flags_t arg exe‐
101 cute in interrupt context.) This cookie is used in lieu of one returned
102 by ddi_get_iblock_cookie(9F). Mutexes used in other handlers or under
103 other conditions should initialize per mutex_init(9F).
104 The parsed standard USB device descriptor is used for device type iden‐
107 tification.
108 The several ID strings, including the manufacturer's ID, product ID,
111 and serial number may be used to identify the device in messages or to
112 compare it to other devices.
113 The descriptor tree, returned by dev_cfg, makes a device's parsed stan‐
116 dard USB descriptors available to the driver. The tree is designed to
117 be easily traversed to get any or all standard USB 2.0 descriptors.
118 (See the "Tree Structure" section of this manpage below.) dev_n_cfg
119 returns the number of configurations in the tree. Note that this value
120 may differ from the number of configurations returned in the device
121 descriptor.
122 A returned parse_level field of USB_PARSE_LVL_ALL indicates that all
125 configurations are represented in the tree. This results when
126 USB_PARSE_LVL_ALL is explicitly requested by the caller in the flags
127 argument to usb_get_dev_data(), or when the whole device is seen by the
128 system for the current OS device node (as opposed to only a single con‐
129 figuration for that OS device node). USB_PARSE_LVL_CFG is returned when
130 one entire configuration is returned in the tree. USB_PARSE_LVL_IF is
131 returned when one interface of one configuration is returned in the
132 tree. In the latter two cases, the returned configuration is at
133 dev_cfg[USB_DEV_DEFAULT_CONFIG_INDEX]. USB_PARSE_LVL_NONE is returned
134 when no tree is returned. Note that the value of this field can differ
135 from the parse_level requested as an argument to usb_get_dev_data().
136 TREE STRUCTURE
138 The root of the tree is dev_cfg, an array of usb_cfg_data_t configura‐
139 tion nodes, each representing one device configuration. The
140 array index does not correspond to a configuration's value; use the
141 bConfigurationValue field of the configuration descriptor within to
142 find out the proper number for a given configuration.
143 The size of the array is returned in dev_n_cfg. The array itself is not
146 NULL terminated.
147 When USB_PARSE_LVL_ALL is returned in dev_parse_level, index 0 pertains
150 to the first valid configuration. This pertains to device configuration
151 1 as USB configuration 0 is not defined. When dev_parse_level returns
152 USB_PARSE_LVL_CFG or USB_PARSE_LVL_IF, index 0 pertains to the device's
153 one configuration recognized by the system. (Note that the configura‐
154 tion level is the only descriptor level in the tree where the index
155 value does not correspond to the descriptor's value.)
156 Each usb_cfg_data_t configuration node contains a parsed usb configura‐
159 tion descriptor (usb_cfg_descr_t cfg_descr) a pointer to its string
160 description (char *cfg_str) and string size (cfg_strsize), a pointer to
161 an array of interface nodes (usb_if_data_t *cfg_if), and a pointer to
162 an array of class/vendor (cv) descriptor nodes (usb_cvs_data_t
163 *cfg_cvs). The interface node array size is kept in cfg_n_if, and the
164 cv node array size is kept in cfg_n_cvs; neither array is NULL termi‐
165 nated. When USB_PARSE_LVL_IF is returned in dev_parse_level, the only
166 interface (or alternate group) included in the tree is that which is
167 recognized by the system for the current OS device node.
168 Each interface can present itself potentially in one of several alter‐
171 nate ways. An alternate tree node (usb_alt_if_data_t) repre‐
172 sents an alternate representation. Each usb_if_data_t interface node
173 points to an array of alternate nodes (usb_alt_if_data_t *if_alt)
174 and contains the size of the array (if_n_alt).
175 Each interface alternate node holds an interface descriptor
178 (usb_if_descr_t altif_descr), a pointer to its string description (char
179 *altif_str), and has its own set of endpoints and bound cv descriptors.
180 The pointer to the array of endpoints is usb_ep_data_t *altif_ep); the
181 endpoint array size is altif_n_ep. The pointer to the array of cv
182 descriptors is usb_cvs_data_t *altif_cvs; the cv descriptor array size
183 is altif_n_cvs.
184 Each endpoint node holds an endpoint descriptor (usb_ep_descr_t
187 ep_descr), a pointer to an array of cv descriptors for that endpoint
188 (usb_cvs_data_t *ep_cvs), and the size of that array (ep_n_cvs). An
189 endpoint descriptor may be passed to usb_pipe_open(9F) to establish a
190 logical connection for data transfer.
191 Class and vendor descriptors (cv descriptors) are grouped with the con‐
194 figuration, interface or endpoint descriptors they immediately follow
195 in the raw data returned by the device. Tree nodes representing such
196 descriptors (usb_cvs_data_t) contain a pointer to the raw data (uchar_t
197 *cvs_buf) and the size of the data (uint_t cvs_buf_len).
198 Configuration and interface alternate nodes return string descriptions.
201 Note that all string descriptions returned have a maximum length of
202 USB_MAXSTRINGLEN bytes and are in English ASCII.
203
205 In the following example, a device's configuration data, including the
206 following descriptor tree, is retrieved by usb_get_dev_data(9F) into
207 usb_client_dev_data_t *reg_data:
208 config 1
210 iface 0
211 alt 0
212 endpt 0
213 config 2
214 iface 0
215 iface 1
216 alt 0
217 endpt 0
218 cv 0
219 alt 1
220 endpt 0
221 endpt 1
222 cv 0
223 endpt 2
224 alt 2
225 endpt 0
226 cv 0
227 and suppose that the C/V data is of the following format:
229 typedef struct cv_data {
231 char char1;
232 short short1;
233 char char2;
234 } cv_data_t;
235 Parse the data of C/V descriptor 0, second configuration
237 (index 1), iface 1, alt 2, endpt 0.
238 usb_client_dev_data_t reg_data;
240 usb_cvs_data_t *cv_node;
241 cv_data_t parsed_data;
242 cv_node =
244 ®_data->dev_cfg[1].cfg_if[1].if_alt[2].altif_ep[0].ep_cvs[0];
245 (void)usb_parse_data("csc",
246 (void *)(&cv_node->cvs_buf), cv_node->cvs_buf_len,
247 &parsed_data, sizeof(cv_data_t));
248
251 See attributes(5) for descriptions of the following attributes:
252 ┌─────────────────────────────┬─────────────────────────────┐
257 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
258 ├─────────────────────────────┼─────────────────────────────┤
259 │Architecture │PCI-based systems │
260 ├─────────────────────────────┼─────────────────────────────┤
261 │Interface stability │Committed │
262 ├─────────────────────────────┼─────────────────────────────┤
263 │Availability │SUNWusb │
264 └─────────────────────────────┴─────────────────────────────┘
265
267 usb_get_alt_if(9F), usb_get_cfg(9F), usb_get_dev_data(9F),
268 usb_get_string_descr(9F), usb_lookup_ep_data(9F), usb_parse_data(9F),
269 usb_pipe_open(9F), usb_cfg_descr(9S), usb_if_descr(9S),
270 usb_ep_descr(9S), usb_string_descr(9S)
271SunOS 5.11 5 Jan 2004 usb_client_dev_data(9S)