share/man/man9s/usb_client_dev_data.9s

   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_CLIENT_DEV_DATA 9S "Oct 30, 2016"
   7 .SH NAME
   8 usb_client_dev_data \- Device configuration information
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13 .fi
  14
  15 .SH INTERFACE LEVEL
  16 .LP
  17 Solaris DDI specific (Solaris DDI)
  18 .SH DESCRIPTION
  19 .LP
  20 The usb_client_dev_data_t structure carries all device configuration
  21 information. It is provided to a USB client driver through a call to
  22 \fBusb_get_dev_data\fR(9F). Most USBA functions require information which comes
  23 from this structure.
  24 .sp
  25 .LP
  26 The usb_client_dev_data_t structure fields are:
  27 .sp
  28 .in +2
  29 .nf
  30  usb_pipe_handle_t   dev_default_ph;   /* deflt ctrl pipe handle */
  31
  32  ddi_iblock_cookie_t dev_iblock_cookie;/* for calls to mutex_init */
  33                                        /* for mutexes used by intr */
  34                                        /* context callbacks. */
  35
  36  usb_dev_descr_t     *dev_descr;      /* parsed* dev. descriptor */
  37
  38  char                *dev_mfg;        /* manufacturer's ID string */
  39
  40  char                *dev_product;    /* product ID string */
  41
  42  char                *dev_serial;     /* serial num. string */
  43
  44  usb_reg_parse_lvl_t dev_parse_level; /* Parse level */
  45                                       /* reflecting the tree */
  46                                       /* (if any) returned through */
  47                                       /* the dev_cfg array. */
  48
  49  usb_cfg_data_t      *dev_cfg;        /* parsed* descr  tree.*/
  50
  51  uint_t              dev_n_cfg;       /* num cfgs in parsed descr. */
  52                                       /* tree, dev_cfg array below.*/
  53
  54  usb_cfg_data_t      *dev_curr_cfg;   /* Pointer to the tree config*/
  55                                       /* corresponding to the cfg */
  56                                       /* active at the time of the */
  57                                       /* usb_get_dev_data() call */
  58
  59  int                 dev_curr_if;     /* First active interface in */
  60                                       /* tree under driver's control.*/
  61
  62                                       /* Always zero when driver */
  63                                       /* controls whole device. */
  64
  65 * A parsed descriptor is in a struct whose fields' have been adjusted
  66   to the host processor.  This may include endianness adjustment (the USB
  67   standard defines that devices report in little-endian bit order) or
  68   structure padding as necessary.
  69 .fi
  70 .in -2
  71
  72 .sp
  73 .LP
  74 dev_parse_level represents the extent of the device represented by the tree
  75 returned by the dev_cfg field and has the following possible values:
  76 .sp
  77 .ne 2
  78 .na
  79 \fBUSB_PARSE_LVL_NONE\fR
  80 .ad
  81 .RS 22n
  82 Build no tree. dev_n_cfg returns 0, dev_cfg and dev_curr_cfg are returned NULL,
  83 the dev_curr_xxx fields are invalid.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fBUSB_PARSE_LVL_IF\fR
  90 .ad
  91 .RS 22n
  92 Parse configured interface only, if configuration# and interface properties are
  93 set (as when different interfaces are viewed by the OS as different device
  94 instances). If an OS device instance is set up to represent an entire physical
  95 device, this works like USB_PARSE_LVL_ALL.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fBUSB_PARSE_LVL_CFG\fR
 102 .ad
 103 .RS 22n
 104 Parse entire configuration of configured interface only. This is like
 105 USB_PARSE_LVL_IF except entire configuration is returned.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fBUSB_PARSE_LVL_ALL\fR
 112 .ad
 113 .RS 22n
 114 Parse entire device (all configurations), even when driver is bound to a single
 115 interface of a single configuration.
 116 .RE
 117
 118 .sp
 119 .LP
 120 The default control pipe handle is used mainly for control commands and device
 121 setup.
 122 .sp
 123 .LP
 124 The dev_iblock_cookie is used to initialize client driver mutexes which are
 125 used in interrupt-context callback handlers.  (All callback handlers called
 126 with USB_CB_INTR_CONTEXT in their usb_cb_flags_t arg execute in interrupt
 127 context.) This cookie is used in lieu of one returned by
 128 \fBddi_get_iblock_cookie\fR(9F). Mutexes used in other handlers or under other
 129 conditions should initialize per \fBmutex_init\fR(9F).
 130 .sp
 131 .LP
 132 The parsed standard USB device descriptor is used for device type
 133 identification.
 134 .sp
 135 .LP
 136 The several ID strings, including the manufacturer's ID, product ID, and serial
 137 number may be used to identify the device in messages or to compare it to other
 138 devices.
 139 .sp
 140 .LP
 141 The descriptor tree, returned by dev_cfg, makes a device's parsed standard USB
 142 descriptors available to the driver. The tree is designed to be easily
 143 traversed to get any or all standard \fIUSB 3.0\fR descriptors.  (See the "Tree
 144 Structure" section of this manpage below.)  dev_n_cfg returns the number of
 145 configurations in the tree. Note that this value may differ from the number of
 146 configurations returned in the device descriptor.
 147 .sp
 148 .LP
 149 A returned parse_level field of USB_PARSE_LVL_ALL indicates that all
 150 configurations are represented in the tree. This results when USB_PARSE_LVL_ALL
 151 is explicitly requested by the caller in the flags argument to
 152 \fBusb_get_dev_data()\fR, or when the whole device is seen by the system for
 153 the current OS device node (as opposed to only a single configuration for that
 154 OS device node). USB_PARSE_LVL_CFG is returned when one entire configuration is
 155 returned in the tree. USB_PARSE_LVL_IF is returned when one interface of one
 156 configuration is returned in the tree. In the latter two cases, the returned
 157 configuration is at     dev_cfg[USB_DEV_DEFAULT_CONFIG_INDEX].
 158 USB_PARSE_LVL_NONE is returned when no tree is returned. Note that the value of
 159 this field can differ from the parse_level requested as an argument to
 160 \fBusb_get_dev_data()\fR.
 161 .SS "TREE STRUCTURE"
 162 .LP
 163 The root of the tree is dev_cfg, an array of usb_cfg_data_t configuration
 164 nodes, each representing one device configuration. The array index does
 165 not correspond to a configuration's value; use the bConfigurationValue field of
 166 the configuration descriptor within to find out the proper number for a given
 167 configuration.
 168 .sp
 169 .LP
 170 The size of the array is returned in dev_n_cfg. The array itself is not NULL
 171 terminated.
 172 .sp
 173 .LP
 174 When USB_PARSE_LVL_ALL is returned in dev_parse_level, index 0 pertains to the
 175 first valid configuration. This pertains to device configuration 1 as USB
 176 configuration 0 is not defined. When dev_parse_level returns USB_PARSE_LVL_CFG
 177 or USB_PARSE_LVL_IF, index 0 pertains to the device's one configuration
 178 recognized by the system. (Note that the configuration level is the only
 179 descriptor level in the tree where the index value does not correspond to the
 180 descriptor's value.)
 181 .sp
 182 .LP
 183 Each usb_cfg_data_t configuration node contains a parsed usb configuration
 184 descriptor (usb_cfg_descr_t cfg_descr) a pointer to its string description
 185 (char *cfg_str) and string size (cfg_strsize), a pointer to an array of
 186 interface nodes (usb_if_data_t *cfg_if), and a pointer to an array of
 187 class/vendor (cv) descriptor nodes (usb_cvs_data_t *cfg_cvs). The interface
 188 node array size is kept in cfg_n_if, and the cv node array size is kept in
 189 cfg_n_cvs; neither array is NULL terminated. When USB_PARSE_LVL_IF is returned
 190 in dev_parse_level, the only interface (or alternate group) included in the
 191 tree is that which is recognized by the system for the current OS device node.
 192 .sp
 193 .LP
 194 Each interface can present itself potentially in one of several alternate ways.
 195 An alternate tree node (usb_alt_if_data_t)         represents an alternate
 196 representation. Each usb_if_data_t interface node points to an array of
 197 alternate nodes (usb_alt_if_data_t *if_alt)         and contains the size of
 198 the array (if_n_alt).
 199 .sp
 200 .LP
 201 Each interface alternate node holds an interface descriptor (usb_if_descr_t
 202 altif_descr), a pointer to its string description (char *altif_str), and has
 203 its own set of endpoints and bound cv descriptors. The pointer to the array of
 204 endpoints is usb_ep_data_t *altif_ep); the endpoint array size is altif_n_ep.
 205 The pointer to the array of cv descriptors is usb_cvs_data_t *altif_cvs; the cv
 206 descriptor array size is altif_n_cvs.
 207 .sp
 208 .LP
 209 Each endpoint node holds an endpoint descriptor (usb_ep_descr_t ep_descr), a
 210 pointer to an array of cv descriptors for that endpoint (usb_cvs_data_t
 211 *ep_cvs), and the size of that array (ep_n_cvs). An endpoint descriptor may be
 212 passed to \fBusb_pipe_open\fR(9F) to establish a logical connection for data
 213 transfer.
 214 .sp
 215 .LP
 216 Class and vendor descriptors (cv descriptors) are grouped with the
 217 configuration, interface or endpoint descriptors they immediately follow in the
 218 raw data returned by the device.  Tree nodes representing such descriptors
 219 (usb_cvs_data_t) contain a pointer to the raw data (uchar_t *cvs_buf) and the
 220 size of the data (uint_t cvs_buf_len).
 221 .sp
 222 .LP
 223 Configuration and interface alternate nodes return string descriptions. Note
 224 that all string descriptions returned have a maximum length of USB_MAXSTRINGLEN
 225 bytes and are in English ASCII.
 226 .SH EXAMPLES
 227 .LP
 228 In the following example, a device's configuration data, including the
 229 following descriptor tree, is retrieved by \fBusb_get_dev_data\fR(9F) into
 230 usb_client_dev_data_t *reg_data:
 231 .sp
 232 .in +2
 233 .nf
 234        config 1
 235             iface 0
 236                 alt 0
 237                     endpt 0
 238         config 2
 239             iface 0
 240             iface 1
 241                 alt 0
 242                     endpt 0
 243                         cv 0
 244                 alt 1
 245                     endpt 0
 246                     endpt 1
 247                         cv 0
 248                     endpt 2
 249                 alt 2
 250                     endpt 0
 251                         cv 0
 252
 253         and suppose that the C/V data is of the following format:
 254
 255         typedef struct cv_data {
 256             char char1;
 257             short short1;
 258             char char2;
 259         } cv_data_t;
 260
 261         Parse the data of C/V descriptor 0, second configuration
 262         (index 1), iface 1, alt 2, endpt 0.
 263
 264         usb_client_dev_data_t reg_data;
 265         usb_cvs_data_t *cv_node;
 266         cv_data_t parsed_data;
 267
 268         cv_node =
 269            &reg_data->dev_cfg[1].cfg_if[1].if_alt[2].altif_ep[0].ep_cvs[0];
 270         (void)usb_parse_data("csc",
 271            (void *)(&cv_node->cvs_buf), cv_node->cvs_buf_len,
 272            &parsed_data, sizeof(cv_data_t));
 273 .fi
 274 .in -2
 275
 276 .SH ATTRIBUTES
 277 .LP
 278 See \fBattributes\fR(5) for descriptions of the following attributes:
 279 .sp
 280
 281 .sp
 282 .TS
 283 box;
 284 c | c
 285 l | l .
 286 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 287 _
 288 Architecture    PCI-based systems
 289 _
 290 Interface stability     Committed
 291 .TE
 292
 293 .SH SEE ALSO
 294 .LP
 295 \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), \fBusb_get_dev_data\fR(9F),
 296 \fBusb_get_string_descr\fR(9F), \fBusb_lookup_ep_data\fR(9F),
 297 \fBusb_parse_data\fR(9F), \fBusb_pipe_open\fR(9F), \fBusb_cfg_descr\fR(9S),
 298 \fBusb_if_descr\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_string_descr\fR(9S)