1usb_get_dev_data(9F) Kernel Functions for Drivers usb_get_dev_data(9F)
2
6 usb_get_dev_data, usb_free_dev_data, usb_free_descr_tree,
7 usb_print_descr_tree - Retrieve device configuration information
8
10 #include <sys/usb/usba.h>
11 int usb_get_dev_data(dev_info_t *dip, usb_client_dev_data_t **dev_data,
15 usb_reg_parse_lvl_t parse_level, usb_flags_t flags);
16 void usb_free_dev_data(dev_info_t *dip, usb_client_dev_data_t *dev_data);
19 void usb_free_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);
22 int usb_print_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);
25
28 Solaris DDI specific (Solaris DDI)
29
31 For usb_get_dev_data():
32 dip Pointer to device's dev_info structure.
34 dev_data Address in which pointer to info is returned.
37 parse_level Portion of device represented in the tree of parsed
40 descriptors. See below for possible usb_reg_parse_lvl_t
41 values and explanations.
42 flags Not used.
45 For usb_free_dev_data():
49 dip Pointer to device's dev_info structure.
51 dev_data Pointer to usb_client_dev_data_t to be freed.
54 For usb_free_descr_tree():
58 dip Pointer to device's dev_info structure.
60 dev_data Pointer to usb_client_dev_data_t containing the descriptor
63 tree to free.
64 For usb_print_descr_tree():
68 dip Pointer to device's dev_info structure.
70 dev_data Pointer to usb_client_dev_data_t containing the descriptor
73 tree to display on-screen.
74
77 The usb_get_dev_data() function interrogates a device and returns its
78 configuration information in a usb_client_dev_data_t structure. Most
79 USBA functions require information which comes from a
80 usb_client_dev_data_t, and all other functions in this man page operate
81 on this structure. Please see usb_client_dev_data(9S) for a full con‐
82 tent description. Pass the usb_client_dev_data_t structure to
83 usb_client_detach(9F) to completely deallocate it.
84 A descriptor tree is included in the information returned. The
87 usb_reg_parse_lvl_t type represents the extent of the device to be
88 represented by the returned tree (2nd arg to usb_get_dev_data) or what
89 is actually represented in the returned tree (dev_parse_level field of
90 the returned usb_client_dev_data_t). It has the following possible val‐
91 ues:
92 USB_PARSE_LVL_NONE Build no tree. dev_n_cfg returns 0, dev_cfg and
94 dev_curr_cfg are returned NULL, and the
95 dev_curr_xxx fields are invalid.
96 USB_PARSE_LVL_IF If configuration number and interface properties
99 are set (as when different interfaces are viewed
100 by the OS as different device instances), parse
101 configured interface only. If an OS device
102 instance is set up to represent an entire physi‐
103 cal device, USB_PARSE_LVL_IF works like
104 USB_PARSE_LVL_ALL.
105 USB_PARSE_LVL_CFG Parse entire configuration of configured inter‐
108 face only. Behaves similarly to USB_PARSE_LVL_IF,
109 except that entire configuration is returned.
110 USB_PARSE_LVL_ALL Parse entire device (all configurations), even
113 when driver is bound to a single interface of a
114 single configuration.
115 The usb_free_dev_data() function undoes what usb_get_dev_data() set up.
119 It releases memory for all strings, descriptors, and trees set up by
120 usb_get_dev_data().
121 The usb_free_descr_tree() function frees the descriptor tree of its
124 usb_client_dev_data_t argument, while leaving the rest of the informa‐
125 tion intact. The intent is for drivers to free memory after copying
126 needed descriptor information from the tree. Upon return, the following
127 usb_client_dev_data_t fields are modified as follows: dev_cfg is NULL,
128 dev_n_cfg is zero and dev_parse_level is USB_PARSE_LVL_NONE. Addi‐
129 tionally, dev_curr_cfg is NULL and dev_curr_if is invalid.
130 The usb_print_descr_tree() function is an easy-to-use diagnostic aid
133 which dumps the descriptor tree to the screen when the system is ver‐
134 bose booted (boot -v). Output is spaced with blank lines for readabil‐
135 ity and provides you with an on-screen look at what a device has to
136 offer.
137
139 For usb_get_dev_data():
140 USB_SUCCESS Registration is successful.
142 USB_INVALID_ARGS dip or dev_data is NULL. parse_level is invalid.
145 USB_INVALID_CONTEXT Called from interrupt context.
148 USB_INVALID_VERSION usb_client_attach(9F) was not called first.
151 USB_FAILURE Bad descriptor info or other internal error.
154 For usb_free_dev_data(): None
158 For usb_free_descr_tree(): None, but no operation occurs if dip and/or
161 dev_data are NULL.
162 For usb_print_descr_tree():
165 USB_SUCCESS Descriptor tree dump is successful.
167 USB_INVALID_ARGS dev_data or dip are NULL.
170 USB_INVALID_CONTEXT Called from interrupt context.
173 USB_FAILURE Other error.
176
179 The usb_get_dev_data() and usb_print_descr_tree() functions may be
180 called from user or kernel context.
181 The usb_free_dev_data() and usb_free_descr_tree() functions may be
184 called from user, kernel or interrupt context.
185
187 In this example, assume a device has the configuration shown
188 below, and the endpoint of config 2, iface 1, alt 1
189 which supports intr IN transfers needs to be found.
190 Config 2, iface 1 is the "default" config/iface for the
191 current OS device node.
192 config 1
194 iface 0
195 endpt 0
196 config 2
197 iface 0
198 iface 1
199 alt 0
200 endpt 0
201 cv 0
202 alt 1
203 endpt 0
204 endpt 1
205 cv 0
206 endpt 2
207 alt 2
208 endpt 0
209 cv 0
210 usb_client_dev_data_t *dev_data;
212 usb_ep_descr_t ep_descr;
213 usb_ep_data_t *ep_tree_node;
214 uint8_t interface = 1;
215 uint8_t alternate = 1;
216 uint8_t first_ep_number = 0;
217 /*
219 * We want default config/iface, so specify USB__PARSE_LVL_IF.
220 * Default config will be returned as dev_cfg[0].
221 /
222 if (usb_get_dev_data(dip, &dev_data,
223 USB_PARSE_LVL_IF, 0) != USB_SUCCESS) {
224 cmn_err (CE_WARN,
225 "%s%d: Couldn't get USB configuration descr tree",
226 ddi_driver_name(dip), ddi_get_instance(dip));
227 return (USB_FAILURE);
229 }
230 ep_tree_node = usb_lookup_ep_data(dip, dev_data, interface,
232 alternate, first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN);
233 if (ep_tree_node != NULL) {
234 ep_descr = ep_tree_node->ep_descr;
235 } else {
236 cmn_r (CE_WARN,
237 "%s%d: Device is missing intr-IN endpoint",
238 ddi_driver_name(dip), ddi_get_instance(dip));
239 usb_free_descr_tree(dip, &dev_data);
241 return (USB_FAILURE);
243 }
244
248 See attributes(5) for descriptions of the following attributes:
249 ┌─────────────────────────────┬─────────────────────────────┐
254 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
255 ├─────────────────────────────┼─────────────────────────────┤
256 │Architecture │PCI-based systems │
257 ├─────────────────────────────┼─────────────────────────────┤
258 │Interface stability │Committed │
259 ├─────────────────────────────┼─────────────────────────────┤
260 │Availability │SUNWusb │
261 └─────────────────────────────┴─────────────────────────────┘
262
264 attributes(5), usb_client_attach(9F), usb_get_alt_if(9F),
265 usb_get_cfg(9F), usb_get_string_descr(9F), usb_lookup_ep_data(9F),
266 usb_parse_data(9F), usb_pipe_open(9F), usb_cfg_descr(9S),
267 usb_client_dev_data(9S), usb_ep_descr(9S), usb_if_descr(9S),
268 usb_string_descr(9S)
269SunOS 5.11 5 Jan 2004 usb_get_dev_data(9F)