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