usr/src/man/man9f/usb_get_dev_data.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USB_GET_DEV_DATA 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_get_dev_data, usb_free_dev_data, usb_free_descr_tree, usb_print_descr_tree
   9 \- Retrieve device configuration information
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15
  16
  17 \fBint\fR \fBusb_get_dev_data\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t **\fR\fIdev_data\fR,
  18      \fBusb_reg_parse_lvl_t\fR \fIparse_level\fR, \fBusb_flags_t\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBusb_free_dev_data\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBusb_free_descr_tree\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBusb_print_descr_tree\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR);
  34 .fi
  35
  36 .SH INTERFACE LEVEL
  37 .LP
  38 Solaris DDI specific (Solaris DDI)
  39 .SH PARAMETERS
  40 .LP
  41 For \fBusb_get_dev_data()\fR:
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIdip\fR\fR
  46 .ad
  47 .RS 15n
  48 Pointer to device's dev_info structure.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIdev_data\fR\fR
  55 .ad
  56 .RS 15n
  57 Address in which pointer to info is returned.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIparse_level\fR\fR
  64 .ad
  65 .RS 15n
  66 Portion of device represented in the tree of parsed descriptors. See below for
  67 possible usb_reg_parse_lvl_t values and explanations.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIflags\fR\fR
  74 .ad
  75 .RS 15n
  76 Not used.
  77 .RE
  78
  79 .sp
  80 .LP
  81 For \fBusb_free_dev_data()\fR:
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIdip\fR\fR
  86 .ad
  87 .RS 12n
  88 Pointer to device's dev_info structure.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIdev_data\fR\fR
  95 .ad
  96 .RS 12n
  97 Pointer to usb_client_dev_data_t to be freed.
  98 .RE
  99
 100 .sp
 101 .LP
 102 For \fBusb_free_descr_tree()\fR:
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIdip\fR\fR
 107 .ad
 108 .RS 12n
 109 Pointer to device's dev_info structure.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIdev_data\fR\fR
 116 .ad
 117 .RS 12n
 118 Pointer to usb_client_dev_data_t containing the descriptor tree to free.
 119 .RE
 120
 121 .sp
 122 .LP
 123 For \fBusb_print_descr_tree()\fR:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fIdip\fR\fR
 128 .ad
 129 .RS 12n
 130 Pointer to device's dev_info structure.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fIdev_data\fR\fR
 137 .ad
 138 .RS 12n
 139 Pointer to usb_client_dev_data_t containing the descriptor tree to display
 140 on-screen.
 141 .RE
 142
 143 .SH DESCRIPTION
 144 .LP
 145 The \fBusb_get_dev_data()\fR function interrogates a device and returns its
 146 configuration information in a usb_client_dev_data_t structure. Most USBA
 147 functions require information which comes from a usb_client_dev_data_t, and all
 148 other functions in this man page operate on this structure. Please see
 149 \fBusb_client_dev_data(9S)\fR for a full content description. Pass the
 150 usb_client_dev_data_t structure to \fBusb_client_detach\fR(9F) to completely
 151 deallocate it.
 152 .sp
 153 .LP
 154 A descriptor tree is included in the information returned. The
 155 usb_reg_parse_lvl_t type represents the extent of the device to be
 156 represented by the returned tree (2nd arg to usb_get_dev_data) or what is
 157 actually represented in the returned tree (dev_parse_level field of the
 158 returned usb_client_dev_data_t). It has the following possible values:
 159 .sp
 160 .ne 2
 161 .na
 162 \fBUSB_PARSE_LVL_NONE\fR
 163 .ad
 164 .RS 22n
 165 Build no tree. dev_n_cfg  returns 0, dev_cfg and dev_curr_cfg  are returned
 166 NULL, and  the dev_curr_xxx fields are invalid.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fBUSB_PARSE_LVL_IF\fR
 173 .ad
 174 .RS 22n
 175 If configuration number and interface properties are set (as when different
 176 interfaces are viewed by the OS as different device instances), parse
 177 configured interface only. If an OS device instance is set up to represent an
 178 entire physical device, USB_PARSE_LVL_IF works like USB_PARSE_LVL_ALL.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fBUSB_PARSE_LVL_CFG\fR
 185 .ad
 186 .RS 22n
 187 Parse entire configuration of configured interface only. Behaves similarly to
 188 USB_PARSE_LVL_IF, except that entire configuration is returned.
 189 .RE
 190
 191 .sp
 192 .ne 2
 193 .na
 194 \fBUSB_PARSE_LVL_ALL\fR
 195 .ad
 196 .RS 22n
 197 Parse entire device (all configurations), even when driver is bound to a single
 198 interface of a single configuration.
 199 .RE
 200
 201 .sp
 202 .LP
 203 The \fBusb_free_dev_data()\fR function undoes what \fBusb_get_dev_data()\fR set
 204 up.  It releases memory for all strings, descriptors, and trees set up by
 205 \fBusb_get_dev_data()\fR.
 206 .sp
 207 .LP
 208 The \fBusb_free_descr_tree()\fR function frees the descriptor tree of its
 209 usb_client_dev_data_t argument, while leaving the rest of the information
 210 intact. The intent is for drivers to free memory after copying needed
 211 descriptor information from the tree. Upon return, the following
 212 usb_client_dev_data_t fields  are modified as follows: dev_cfg is NULL,
 213 dev_n_cfg  is zero and dev_parse_level  is USB_PARSE_LVL_NONE. Additionally,
 214 dev_curr_cfg is NULL and dev_curr_if is invalid.
 215 .sp
 216 .LP
 217 The \fBusb_print_descr_tree()\fR function is an easy-to-use diagnostic aid
 218 which dumps the descriptor tree to the screen when the system is verbose booted
 219 (\fBboot\fR \fB-v\fR). Output is spaced with blank lines for readability and
 220 provides you with an on-screen look at what a device has to offer.
 221 .SH RETURN VALUES
 222 .LP
 223 For \fBusb_get_dev_data()\fR:
 224 .sp
 225 .ne 2
 226 .na
 227 \fBUSB_SUCCESS\fR
 228 .ad
 229 .RS 23n
 230 Registration is successful.
 231 .RE
 232
 233 .sp
 234 .ne 2
 235 .na
 236 \fBUSB_INVALID_ARGS\fR
 237 .ad
 238 .RS 23n
 239 \fIdip\fR or \fIdev_data\fR is \fBNULL\fR. \fIparse_level\fR is invalid.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fBUSB_INVALID_CONTEXT\fR
 246 .ad
 247 .RS 23n
 248 Called from interrupt context.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fBUSB_INVALID_VERSION\fR
 255 .ad
 256 .RS 23n
 257 \fBusb_client_attach\fR(9F) was not called first.
 258 .RE
 259
 260 .sp
 261 .ne 2
 262 .na
 263 \fBUSB_FAILURE\fR
 264 .ad
 265 .RS 23n
 266 Bad descriptor info or other internal error.
 267 .RE
 268
 269 .sp
 270 .LP
 271 For \fBusb_free_dev_data()\fR: None
 272 .sp
 273 .LP
 274 For \fBusb_free_descr_tree()\fR: None, but no operation occurs if \fIdip\fR
 275 and/or \fIdev_data\fR are NULL.
 276 .sp
 277 .LP
 278 For \fBusb_print_descr_tree()\fR:
 279 .sp
 280 .ne 2
 281 .na
 282 \fBUSB_SUCCESS\fR
 283 .ad
 284 .RS 23n
 285 Descriptor tree dump is successful.
 286 .RE
 287
 288 .sp
 289 .ne 2
 290 .na
 291 \fBUSB_INVALID_ARGS\fR
 292 .ad
 293 .RS 23n
 294 \fIdev_data\fR or \fIdip\fR are NULL.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fBUSB_INVALID_CONTEXT\fR
 301 .ad
 302 .RS 23n
 303 Called from interrupt context.
 304 .RE
 305
 306 .sp
 307 .ne 2
 308 .na
 309 \fBUSB_FAILURE\fR
 310 .ad
 311 .RS 23n
 312 Other error.
 313 .RE
 314
 315 .SH CONTEXT
 316 .LP
 317 The \fBusb_get_dev_data()\fR and \fBusb_print_descr_tree()\fR functions may be
 318 called from user or kernel context.
 319 .sp
 320 .LP
 321 The \fBusb_free_dev_data()\fR and \fBusb_free_descr_tree()\fR functions may be
 322 called from user, kernel or interrupt context.
 323 .SH EXAMPLES
 324 .in +2
 325 .nf
 326 In this example, assume a device has the configuration shown
 327 below, and the endpoint of config 2, iface 1, alt 1
 328 which supports intr IN transfers needs to be found.
 329 Config 2, iface 1 is the "default" config/iface for the
 330 current OS device node.
 331
 332       config 1
 333           iface 0
 334               endpt 0
 335       config 2
 336           iface 0
 337           iface 1
 338               alt 0
 339                   endpt 0
 340                       cv 0
 341               alt 1
 342                   endpt 0
 343                   endpt 1
 344                       cv 0
 345                   endpt 2
 346               alt 2
 347                   endpt 0
 348                       cv 0
 349
 350       usb_client_dev_data_t *dev_data;
 351       usb_ep_descr_t ep_descr;
 352       usb_ep_data_t *ep_tree_node;
 353       uint8_t interface = 1;
 354       uint8_t alternate = 1;
 355       uint8_t first_ep_number = 0;
 356
 357       /*
 358        * We want default config/iface, so specify USB__PARSE_LVL_IF.
 359        * Default config will be returned as dev_cfg[0].
 360       /
 361         if (usb_get_dev_data(dip, &dev_data,
 362           USB_PARSE_LVL_IF, 0) != USB_SUCCESS) {
 363               cmn_err (CE_WARN,
 364                   "%s%d: Couldn't get USB configuration descr tree",
 365                   ddi_driver_name(dip), ddi_get_instance(dip));
 366
 367               return (USB_FAILURE);
 368       }
 369
 370       ep_tree_node = usb_lookup_ep_data(dip, dev_data, interface,
 371            alternate, first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN);
 372       if (ep_tree_node != NULL) {
 373           ep_descr = ep_tree_node->ep_descr;
 374       } else {
 375               cmn_r (CE_WARN,
 376                   "%s%d: Device is missing intr-IN endpoint",
 377                   ddi_driver_name(dip), ddi_get_instance(dip));
 378
 379               usb_free_descr_tree(dip, &dev_data);
 380
 381               return (USB_FAILURE);
 382       }
 383
 384 .fi
 385 .in -2
 386
 387 .SH ATTRIBUTES
 388 .LP
 389 See \fBattributes\fR(5) for descriptions of the following attributes:
 390 .sp
 391
 392 .sp
 393 .TS
 394 box;
 395 c | c
 396 l | l .
 397 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 398 _
 399 Architecture    PCI-based systems
 400 _
 401 Interface stability     Committed
 402 .TE
 403
 404 .SH SEE ALSO
 405 .LP
 406 \fBattributes\fR(5), \fBusb_client_attach\fR(9F), \fBusb_get_alt_if\fR(9F),
 407 \fBusb_get_cfg\fR(9F), \fBusb_get_string_descr\fR(9F),
 408 \fBusb_lookup_ep_data\fR(9F), \fBusb_parse_data\fR(9F),
 409 \fBusb_pipe_xopen\fR(9F), \fBusb_cfg_descr\fR(9S),
 410 \fBusb_client_dev_data(9S)\fR, \fBusb_ep_descr\fR(9S), \fBusb_if_descr\fR(9S),
 411 \fBusb_string_descr\fR(9S)