usr/src/man/man9f/usb_get_cfg.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_CFG 9F "Jan 5, 2004"
   7 .SH NAME
   8 usb_get_cfg, usb_set_cfg \- Get and set current USB device configuration
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13
  14
  15
  16 \fBint\fR \fBusb_get_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfgval\fR, \fBusb_flags_t\fR \fIflags\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBusb_set_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfg_index\fR, \fBusb_flags_t\fR \fIflags\fR,
  22      \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, \fBusb_opaque_t\fR
  23      \fIcallback_arg\fR, \fBint\fR  \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, \fBusb_opaque_t\fR
  24      \fIcallback_arg\fR);
  25 .fi
  26
  27 .SH INTERFACE LEVEL
  28 .sp
  29 .LP
  30 Solaris DDI specific (Solaris DDI)
  31 .SH PARAMETERS
  32 .sp
  33 .LP
  34 For \fBusb_get_cfg()\fR:
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIdip\fR\fR
  39 .ad
  40 .RS 10n
  41 Pointer to device's dev_info structure.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIcfgval\fR\fR
  48 .ad
  49 .RS 10n
  50 Pointer to returned configuration value.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIflags\fR\fR
  57 .ad
  58 .RS 10n
  59 Not used.  Always waits for completion.
  60 .RE
  61
  62 .sp
  63 .LP
  64 For \fBusb_set_cfg()\fR:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIdip\fR\fR
  69 .ad
  70 .RS 16n
  71 Pointer to device's dev_info structure.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIcfg_index\fR\fR
  78 .ad
  79 .RS 16n
  80 Desired device configuration index. Set to USB_DEV_DEFAULT_CONFIG_INDEX to
  81 restore default configuration.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIflags\fR\fR
  88 .ad
  89 .RS 16n
  90 Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call
  91 callback.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fIcallback\fR\fR
  98 .ad
  99 .RS 16n
 100 Callback handler to notify of asynchronous completion.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIcallback_arg\fR\fR
 107 .ad
 108 .RS 16n
 109 Second argument passed to callback handler.
 110 .RE
 111
 112 .SH DESCRIPTION
 113 .sp
 114 .LP
 115 The \fBusb_get_cfg()\fR function retrieves the current configuration. It
 116 ignores the flags argument and always blocks while contacting the device.
 117 .sp
 118 .LP
 119 The \fBusb_set_cfg()\fR function sets a new configuration. Because this call
 120 changes the device's mode of operation, the device must be quiescent and have
 121 all pipes, with the exception of the default control pipe, closed. The driver
 122 must have control over the entire device and cannot own just a single interface
 123 on a composite device. Additionally, its device node must not be a parent to
 124 other device nodes that can be operated by other drivers. The driver must own
 125 the device exclusively, otherwise drivers managing other parts of the device
 126 would be affected without their knowledge or control.
 127 .sp
 128 .LP
 129 This call updates all internal USBA framework data structures, whereas issuing
 130 a raw USB_REQ_SET_CFG device request does not.  The \fBusb_set_cfg()\fR
 131 function is the only supported programmatic way to change device configuration.
 132 .sp
 133 .LP
 134 This call blocks if USB_FLAGS_SLEEP is set in flags.  It returns immediately
 135 and calls the callback on completion if USB_FLAGS_SLEEP is not set.
 136 .SH RETURN VALUES
 137 .sp
 138 .LP
 139 For \fBusb_get_cfg()\fR:
 140 .sp
 141 .ne 2
 142 .na
 143 \fBUSB_SUCCESS\fR
 144 .ad
 145 .RS 20n
 146 New configuration is retrieved.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fBUSB_INVALID_ARGS\fR
 153 .ad
 154 .RS 20n
 155 \fIcfgval\fR or \fIdip\fR is NULL.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fBUSB_FAILURE\fR
 162 .ad
 163 .RS 20n
 164 Configuration cannot be retrieved.
 165 .RE
 166
 167 .sp
 168 .LP
 169 For \fBusb_set_cfg()\fR:
 170 .sp
 171 .ne 2
 172 .na
 173 \fBUSB_SUCCESS\fR
 174 .ad
 175 .RS 23n
 176 New configuration is set.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fBUSB_INVALID_ARGS\fR
 183 .ad
 184 .RS 23n
 185 dip is NULL.
 186 .sp
 187 USB_FLAGS_SLEEP is clear and callback is NULL.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fBUSB_INVALID_CONTEXT\fR
 194 .ad
 195 .RS 23n
 196 Called from interrupt context with USB_FLAGS_SLEEP specified.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fBUSB_INVALID_PERM\fR
 203 .ad
 204 .RS 23n
 205 Caller does not own entire device or device is a parent to child devices.
 206 .RE
 207
 208 .sp
 209 .ne 2
 210 .na
 211 \fBUSB_BUSY\fR
 212 .ad
 213 .RS 23n
 214 One or more pipes other than the default control pipe are open on the device.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fBUSB_INVALID_PIPE\fR
 221 .ad
 222 .RS 23n
 223 Pipe handle is NULL or invalid, or pipe is closing or closed.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fBUSB_FAILURE\fR
 230 .ad
 231 .RS 23n
 232 An illegal configuration is specified.
 233 .sp
 234 One or more pipes other than the default control pipe are open on the device.
 235 .RE
 236
 237 .SH CONTEXT
 238 .sp
 239 .LP
 240 The \fBusb_get_cfg()\fR function may be called from user or kernel context.
 241 .sp
 242 .LP
 243 The \fBusb_set_cfg()\fR function may be called from user or kernel context
 244 always. It may be called from interrupt context only if USB_FLAGS_SLEEP is not
 245 set in flags.
 246 .sp
 247 .LP
 248 If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if
 249 supplied, can block because it is executing in kernel context. Otherwise the
 250 callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more
 251 information on callbacks.
 252 .SH EXAMPLES
 253 .sp
 254 .in +2
 255 .nf
 256  Setting the configuration to the one at index 1 (in the
 257   array of usb_cfg_data_t configuration nodes as returned
 258   by usb_get_dev_data()), and verifying what the configuration
 259   is at that index. (See usb_get_dev_data(9F)).
 260
 261   uint_t cfg_index = 1;
 262
 263   /*
 264    * Assume all pipes other than the default control pipe
 265    * are closed and make sure all requests to the default
 266    * control pipe have completed. /
 267    */
 268
 269
 270   if (usb_set_cfg(dip, cfg_index, USB_FLAGS_SLEEP, NULL, 0)
 271           != USB_SUCCESS) {
 272           cmn_err (CE_WARN,
 273               "%s%d: Error setting USB device to configuration #%d",
 274               ddi_driver_name(dip), ddi_get_instance(dip), cfg_index);
 275   }
 276
 277   if (usb_get_cfg(dip, &bConfigurationValue, 0) == USB_SUCCESS) {
 278           cmn_err (CE_WARN, "%s%d: USB device active configuration is %d",
 279               ddi_driver_name(dip), ddi_get_instance(dip),
 280               bConfigurationValue);
 281   } else {
 282           ...
 283           ...
 284   }
 285
 286 .fi
 287 .in -2
 288
 289 .SH ATTRIBUTES
 290 .sp
 291 .LP
 292 See \fBattributes\fR(5) for descriptions of the following attributes:
 293 .sp
 294
 295 .sp
 296 .TS
 297 box;
 298 c | c
 299 l | l .
 300 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 301 _
 302 Architecture    PCI-based systems
 303 _
 304 Interface stability     Committed
 305 .TE
 306
 307 .SH SEE ALSO
 308 .sp
 309 .LP
 310 \fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_dev_data\fR(9F),
 311 \fBusb_get_string_descr\fR(9F), \fBusb_pipe_open\fR(9F),
 312 \fBusb_callback_flags\fR(9S), \fBusb_cfg_descr\fR(9S), \fBusb_ep_descr\fR(9S),
 313 \fBusb_if_descr\fR(9S)