share/man/man9f/usb_get_alt_if.9f

   1 '\" te
   2 .\" Copyright (c) 2006 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_ALT_IF 9F "Dec 29, 2006"
   7 .SH NAME
   8 usb_get_alt_if, usb_set_alt_if, usb_get_if_number, usb_owns_device \- Get and
   9 set alternate interface values
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15
  16
  17 \fBint\fR \fBusb_get_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR,
  18      \fBuint_t *\fR\fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBusb_set_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR,
  24      \fBuint_t\fR \fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR,
  25      \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR,
  26      \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags\fR),
  27      \fBusb_opaque_t\fR \fIcallback_arg\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fB\fR
  33
  34 \fBint\fR \fBusb_get_if_number\fR(\fBdev_info_t *\fR\fIdip\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fB\fR
  40
  41 \fBboolean_t\fR \fBusb_owns_device\fR(\fBdev_info_t *\fR\fIdip\fR);
  42 .fi
  43
  44 .SH INTERFACE LEVEL
  45 .sp
  46 .LP
  47 Solaris DDI specific (Solaris DDI)
  48 .SH PARAMETERS
  49 .sp
  50 .LP
  51 For \fBusb_get_alt_if()\fR:
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIdip\fR\fR
  56 .ad
  57 .RS 20n
  58 Pointer to device's \fBdev_info\fR structure.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIinterface_number\fR\fR
  65 .ad
  66 .RS 20n
  67 Interface of the desired alternate.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIalternate_number\fR\fR
  74 .ad
  75 .RS 20n
  76 Address where current alternate setting is returned.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIflags\fR\fR
  83 .ad
  84 .RS 20n
  85 No flags are recognized. Reserved for future expansion.
  86 .RE
  87
  88 .sp
  89 .LP
  90 For \fBusb_set_alt_if()\fR:
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIdip\fR\fR
  95 .ad
  96 .RS 20n
  97 Pointer to device's \fBdev_info\fR structure.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIinterface_number\fR\fR
 104 .ad
 105 .RS 20n
 106 Interface of the desired alternate.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fIalternate_number\fR\fR
 113 .ad
 114 .RS 20n
 115 Alternate interface number to be set.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fIflags\fR\fR
 122 .ad
 123 .RS 20n
 124 Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call
 125 callback.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fIcallback\fR\fR
 132 .ad
 133 .RS 20n
 134 Callback handler to notify of asynchronous completion.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fIcallback_arg\fR\fR
 141 .ad
 142 .RS 20n
 143 Second argument passed to callback handler.
 144 .RE
 145
 146 .sp
 147 .LP
 148 For \fBusb_get_if_number()\fR:
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fIdip\fR\fR
 153 .ad
 154 .RS 7n
 155 Pointer to device's \fBdev_info\fR structure.
 156 .RE
 157
 158 .sp
 159 .LP
 160 For \fBusb_owns_device()\fR:
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fIdip\fR\fR
 165 .ad
 166 .RS 7n
 167 Pointer to device's \fBdev_info\fR structure.
 168 .RE
 169
 170 .SH DESCRIPTION
 171 .sp
 172 .LP
 173 USB devices can have multiple configurations, each with many interfaces. Within
 174 interfaces are alternate settings, and within alternate settings are endpoints.
 175 .sp
 176 .LP
 177 Each interface within a configuration may be represented by the kernel as a
 178 device node. Only one set of device nodes (interfaces as determined by the
 179 configuration) can be active at one time.
 180 .sp
 181 .LP
 182 Alternates to an interface represent different ways the kernel sees a device
 183 node. Only one alternate setting within an interface can be active (or
 184 selected) at one time.  The functions presented in this man page get or set
 185 interface or alternate setting information.
 186 .sp
 187 .LP
 188 The \fBusb_get_alt_if()\fR function requests the device to return the current
 189 alternate setting of the given interface. This function ignores the flags
 190 argument and always blocks.
 191 .sp
 192 .LP
 193 The \fBusb_set_alt_if()\fR function requests the device to set the interface
 194 and its alternate setting as specified. Because this call changes the current
 195 device's interface and sets the new interface's mode of operation as seen by
 196 the system, the driver must insure that all pipes other than the default
 197 control pipe are closed and quiescent. To avoid contending with another driver
 198 for a different part of the device, the driver must be bound to: the entire
 199 device, the interface-association which includes the alternative interface, or
 200 to the interface whose number is \fIinterface_number\fR.
 201 .sp
 202 .LP
 203 If \fBUSB_FLAGS_SLEEP\fR is set in flags, \fBusb_set_alt_if()\fR blocks until
 204 completed. Otherwise, \fBusb_set_alt_if()\fR returns immediately and calls the
 205 callback handler when completed.
 206 .sp
 207 .LP
 208 \fIcallback\fR is the asynchronous callback handler and takes the following
 209 arguments:
 210 .sp
 211 .ne 2
 212 .na
 213 \fBusb_pipe_handle_t pipe_handle\fR
 214 .ad
 215 .sp .6
 216 .RS 4n
 217 Handle of the default control pipe used to perform the request.
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fBusb_opaque_t callback_arg\fR
 224 .ad
 225 .sp .6
 226 .RS 4n
 227 Callback_arg specified to \fBusb_set_alt_if()\fR.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fBint rval\fR
 234 .ad
 235 .sp .6
 236 .RS 4n
 237 Request status.
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fBusb_cb_flags_t callback_flags:\fR
 244 .ad
 245 .sp .6
 246 .RS 4n
 247 Status of the queueing operation. Can be:
 248 .sp
 249 USB_CB_NO_INFO - Callback was uneventful.
 250 .sp
 251 USB_CB_ASYNC_REQ_FAILED   -  Error queueing request.
 252 .sp
 253 USB_CB_NO_RESOURCES   -   Error allocating resources.
 254 .RE
 255
 256 .sp
 257 .LP
 258 The \fBusb_get_if_number()\fR function returns the interface number, or
 259 \fBUSB_COMBINED_NODE\fR or \fBUSB_DEVICE_NODE\fR node indicating that the
 260 driver is bound to the entire device.
 261 .sp
 262 .LP
 263 The \fBusb_owns_device()\fR function returns \fBB_TRUE\fR if the driver of the
 264 dip  argument owns the entire device, or \fBB_FALSE\fR if it owns just a
 265 particular interface.
 266 .SH RETURN VALUES
 267 .sp
 268 .LP
 269 For \fBusb_get_alt_if()\fR:
 270 .sp
 271 .ne 2
 272 .na
 273 \fBUSB_SUCCESS\fR
 274 .ad
 275 .RS 23n
 276 Interface's alternate setting was successfully obtained.
 277 .RE
 278
 279 .sp
 280 .ne 2
 281 .na
 282 \fBUSB_INVALID_ARGS\fR
 283 .ad
 284 .RS 23n
 285 Pointer to alternate_number and/or dip are NULL.
 286 .RE
 287
 288 .sp
 289 .ne 2
 290 .na
 291 \fBUSB_INVALID_CONTEXT\fR
 292 .ad
 293 .RS 23n
 294 Called from interrupt context.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fBUSB_FAILURE\fR
 301 .ad
 302 .RS 23n
 303 The interface number is invalid.
 304 .sp
 305 An access error occurred.
 306 .RE
 307
 308 .sp
 309 .LP
 310 For \fBusb_set_alt_if()\fR:
 311 .sp
 312 .ne 2
 313 .na
 314 \fBUSB_SUCCESS\fR
 315 .ad
 316 .RS 23n
 317 Alternate interface was successfully set.
 318 .RE
 319
 320 .sp
 321 .ne 2
 322 .na
 323 \fBUSB_INVALID_ARGS\fR
 324 .ad
 325 .RS 23n
 326 dip is NULL. USB_FLAGS_SLEEP is clear and callback is NULL.
 327 .RE
 328
 329 .sp
 330 .ne 2
 331 .na
 332 \fBUSB_INVALID_PERM\fR
 333 .ad
 334 .RS 23n
 335 dip does not own the interface to be set.
 336 .RE
 337
 338 .sp
 339 .ne 2
 340 .na
 341 \fBUSB_INVALID_CONTEXT\fR
 342 .ad
 343 .RS 23n
 344 Called from interrupt context with USB_FLAGS_SLEEP specified.
 345 .RE
 346
 347 .sp
 348 .ne 2
 349 .na
 350 \fBUSB_INVALID_PIPE\fR
 351 .ad
 352 .RS 23n
 353 Pipe handle is NULL, invalid, or refers to a pipe that is closing or closed.
 354 .RE
 355
 356 .sp
 357 .ne 2
 358 .na
 359 \fBUSB_FAILURE\fR
 360 .ad
 361 .RS 23n
 362 The interface number and/or alternate setting are invalid.
 363 .sp
 364 Pipes were open.
 365 .sp
 366 An access error occurred.
 367 .RE
 368
 369 .sp
 370 .LP
 371 For \fBusb_get_if_number()\fR:
 372 .sp
 373 .LP
 374 \fBUSB_COMBINED_NODE\fR if the driver is responsible for the entire active
 375 device configuration. The \fBdip\fR doesn't correspond to an entire physical
 376 device.
 377 .sp
 378 .LP
 379 \fBUSB_DEVICE_NODE\fR if the driver is responsible for the entire device. The
 380 \fIdip\fR corresponds to an entire physical device.
 381 .sp
 382 .LP
 383 interface number: otherwise.
 384 .sp
 385 .LP
 386 For \fBusb_owns_device()\fR:
 387 .sp
 388 .ne 2
 389 .na
 390 \fBB_TRUE\fR
 391 .ad
 392 .RS 11n
 393 Driver of the dip argument owns the entire device.
 394 .RE
 395
 396 .sp
 397 .ne 2
 398 .na
 399 \fBB_FALSE\fR
 400 .ad
 401 .RS 11n
 402 Driver of the dip argument owns only the current interface.
 403 .RE
 404
 405 .SH CONTEXT
 406 .sp
 407 .LP
 408 The \fBusb_get_if_number()\fR and \fBusb_owns_device()\fR functions may be
 409 called from user or kernel context.
 410 .sp
 411 .LP
 412 The \fBusb_set_alt_if()\fR function may always be called from user or kernel
 413 context. It may be called from interrupt context only if \fBUSB_FLAGS_SLEEP\fR
 414 is not set in flags. If the \fBUSB_CB_ASYNC_REQ_FAILED\fR bit is clear in
 415 \fBusb_cb_flags_t\fR, the callback, if supplied, can block because it is
 416 executing in kernel context. Otherwise the callback cannot block. See
 417 \fBusb_callback_flags\fR(9S) for more information on callbacks.
 418 .sp
 419 .LP
 420 The \fBusb_get_alt_if()\fR function may be called from user or kernel context.
 421 .SH EXAMPLES
 422 .sp
 423 .in +2
 424 .nf
 425 /* Change alternate setting of interface 0.  Wait for completion. */
 426 if (usb_set_alt_if(
 427     dip, 0, new_alternate_setting_num, USB_FLAGS_SLEEP, NULL, 0) !=
 428     USB_SUCCESS) {
 429         cmn_err (CE_WARN,
 430             "%s%d: Error setting alternate setting on pipe",
 431             ddi_driver_name(dip), ddi_get_instance(dip));
 432         }
 433 }
 434 .fi
 435 .in -2
 436
 437 .SH ATTRIBUTES
 438 .sp
 439 .LP
 440 See \fBattributes\fR(5) for descriptions of the following attributes:
 441 .sp
 442
 443 .sp
 444 .TS
 445 box;
 446 c | c
 447 l | l .
 448 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 449 _
 450 Architecture    PCI-based systems
 451 _
 452 Interface stability     Committed
 453 .TE
 454
 455 .SH SEE ALSO
 456 .sp
 457 .LP
 458 \fBattributes\fR(5), \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_get_dev_data\fR(9F),
 459 \fBusb_get_string_descr\fR(9F), \fBusb_get_cfg\fR(9F)