1usb_get_dev_data(9F)     Kernel Functions for Drivers     usb_get_dev_data(9F)
2
3
4

NAME

6       usb_get_dev_data,        usb_free_dev_data,        usb_free_descr_tree,
7       usb_print_descr_tree - Retrieve device configuration information
8

SYNOPSIS

10       #include <sys/usb/usba.h>
11
12
13
14       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
17
18       void usb_free_dev_data(dev_info_t *dip, usb_client_dev_data_t *dev_data);
19
20
21       void usb_free_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);
22
23
24       int usb_print_descr_tree(dev_info_t *dip, usb_client_dev_data_t *dev_data);
25
26

INTERFACE LEVEL

28       Solaris DDI specific (Solaris DDI)
29

PARAMETERS

31       For usb_get_dev_data():
32
33       dip            Pointer to device's dev_info structure.
34
35
36       dev_data       Address in which pointer to info is returned.
37
38
39       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
43
44       flags          Not used.
45
46
47
48       For usb_free_dev_data():
49
50       dip         Pointer to device's dev_info structure.
51
52
53       dev_data    Pointer to usb_client_dev_data_t to be freed.
54
55
56
57       For usb_free_descr_tree():
58
59       dip         Pointer to device's dev_info structure.
60
61
62       dev_data    Pointer to usb_client_dev_data_t containing the  descriptor
63                   tree to free.
64
65
66
67       For usb_print_descr_tree():
68
69       dip         Pointer to device's dev_info structure.
70
71
72       dev_data    Pointer  to usb_client_dev_data_t containing the descriptor
73                   tree to display on-screen.
74
75

DESCRIPTION

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
85
86       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
93       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
97
98       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
106
107       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
111
112       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
116
117
118       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
122
123       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
131
132       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

RETURN VALUES

139       For usb_get_dev_data():
140
141       USB_SUCCESS            Registration is successful.
142
143
144       USB_INVALID_ARGS       dip or dev_data is NULL. parse_level is invalid.
145
146
147       USB_INVALID_CONTEXT    Called from interrupt context.
148
149
150       USB_INVALID_VERSION    usb_client_attach(9F) was not called first.
151
152
153       USB_FAILURE            Bad descriptor info or other internal error.
154
155
156
157       For usb_free_dev_data(): None
158
159
160       For  usb_free_descr_tree(): None, but no operation occurs if dip and/or
161       dev_data are NULL.
162
163
164       For usb_print_descr_tree():
165
166       USB_SUCCESS            Descriptor tree dump is successful.
167
168
169       USB_INVALID_ARGS       dev_data or dip are NULL.
170
171
172       USB_INVALID_CONTEXT    Called from interrupt context.
173
174
175       USB_FAILURE            Other error.
176
177

CONTEXT

179       The usb_get_dev_data()  and  usb_print_descr_tree()  functions  may  be
180       called from user or kernel context.
181
182
183       The  usb_free_dev_data()  and  usb_free_descr_tree()  functions  may be
184       called from user, kernel or interrupt context.
185

EXAMPLES

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
193               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
211               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
218               /*
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
228                       return (USB_FAILURE);
229               }
230
231               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
240                       usb_free_descr_tree(dip, &dev_data);
241
242                       return (USB_FAILURE);
243               }
244
245
246

ATTRIBUTES

248       See attributes(5) for descriptions of the following attributes:
249
250
251
252
253       ┌─────────────────────────────┬─────────────────────────────┐
254       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
255       ├─────────────────────────────┼─────────────────────────────┤
256       │Architecture                 │PCI-based systems            │
257       ├─────────────────────────────┼─────────────────────────────┤
258       │Interface stability          │Committed                    │
259       ├─────────────────────────────┼─────────────────────────────┤
260       │Availability                 │SUNWusb                      │
261       └─────────────────────────────┴─────────────────────────────┘
262

SEE ALSO

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)
269
270
271
272SunOS 5.11                        5 Jan 2004              usb_get_dev_data(9F)
Impressum