share/man/man9f/usb_pipe_ctrl_xfer.9f

   1 '\" te
   2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USB_PIPE_CTRL_XFER 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_pipe_ctrl_xfer, usb_pipe_ctrl_xfer_wait \- USB control pipe transfer
   9 functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15 \fBint\fR \fBusb_pipe_ctrl_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR,
  16      \fBusb_ctrl_req_t *\fR\fIrequest\fR, \fBusb_flags_t\fR \fIflags\fR);
  17
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBusb_pipe_ctrl_xfer_wait\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR,
  23      \fBusb_ctrl_setup_t *\fR\fIsetup\fR, \fBmblk_t **\fR\fIdata\fR,
  24      \fBusb_cr_t *\fR \fIcompletion_reason\fR, \fBusb_cb_flags_t *cb_\fR\fIflags\fR,
  25      \fBusb_flags_t\fR \fIflags\fR);
  26 .fi
  27
  28 .SH INTERFACE LEVEL
  29 .LP
  30 Solaris DDI specific (Solaris DDI)
  31 .SH PARAMETERS
  32 .LP
  33 For \fBusb_pipe_ctrl_xfer()\fR:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIpipe_handle\fR\fR
  38 .ad
  39 .RS 15n
  40 Control pipe handle on which request is made.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIrequest\fR\fR
  47 .ad
  48 .RS 15n
  49 Pointer to control transfer request.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIflags\fR\fR
  56 .ad
  57 .RS 15n
  58 USB_FLAGS_SLEEP is the only flag recognized. Wait for all pending request
  59 callbacks to complete.
  60 .RE
  61
  62 .sp
  63 .LP
  64 For \fBusb_pipe_ctrl_xfer_wait()\fR:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIpipe_handle\fR\fR
  69 .ad
  70 .RS 21n
  71 Control pipe handle on which request is made.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIsetup\fR\fR
  78 .ad
  79 .RS 21n
  80 Pointer to setup parameters. (See below.)
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fIdata\fR\fR
  87 .ad
  88 .RS 21n
  89 Pointer to mblk containing data bytes to transfer with command.  Ignored if
  90 NULL.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fIcompletion_reason\fR\fR
  97 .ad
  98 .RS 21n
  99 Returns overall completion status. Ignored if NULL. Please see
 100 \fBusb_callback_flags\fR(9S) for more information.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIcallback_flags\fR\fR
 107 .ad
 108 .RS 21n
 109 Returns flags set either during autoclearing or some other callback, which
 110 indicate recovery handling done in callback. Ignored if NULL.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fIflags\fR\fR
 117 .ad
 118 .RS 21n
 119 No flags are recognized. Reserved for future expansion.
 120 .RE
 121
 122 .SH DESCRIPTION
 123 .LP
 124 The \fBusb_pipe_ctrl_xfer()\fR function requests the USBA framework to perform
 125 a transfer through a USB control pipe. The request is passed to the host
 126 controller driver (HCD), which performs the necessary transactions to complete
 127 the request. Requests are synchronous when USB_FLAGS_SLEEP is specified in
 128 flags; calls for synchronous requests do not return until their transaction is
 129 completed. Asynchronous requests (made without specifying the USB_FLAGS_SLEEP
 130 flag) notifies the caller of their completion via a callback function.
 131 .sp
 132 .LP
 133 The \fBusb_pipe_ctrl_xfer_wait()\fR function is a wrapper around
 134 \fBusb_pipe_ctrl_xfer()\fR that performs allocation and deallocation of all
 135 required data structures, and a synchronous control-pipe transfer. It takes a
 136 usb_ctrl_setup_t containing most usb setup parameters as an argument:
 137 .sp
 138 .in +2
 139 .nf
 140  uchar_t      bmRequestType   /* characteristics of request. */
 141                               /* (See USB 2.0 spec, section 9.3). */
 142                               /*  Combine one direction of:   */
 143                               /*      USB_DEV_REQ_HOST_TO_DEV */
 144                               /*      USB_DEV_REQ_DEV_TO_HOST */
 145                               /*  with one request type of:   */
 146                               /*      USB_DEV_REQ_TYPE_STANDARD */
 147                               /*      USB_DEV_REQ_TYPE_CLASS  */
 148                               /*      USB_DEV_REQ_TYPE_VENDOR */
 149                               /*  with one recipient type of: */
 150                               /*      USB_DEV_REQ_RCPT_DEV    */
 151                               /*      USB_DEV_REQ_RCPT_IF     */
 152                               /*      USB_DEV_REQ_RCPT_EP     */
 153                               /*      USB_DEV_REQ_RCPT_OTHER. */
 154
 155  uchar_t      bRequest        /* request or command.          */
 156                               /* (See USB 2.0 spec, section   */
 157                               /* 9.3 for standard commands.)  */
 158
 159  uint16_t     wValue         /* value which varies according to */
 160                               /* the command (bRequest).      */
 161
 162  uint16_t     wIndex          /* value which varies according to */
 163                               /* the command, typically used to */
 164                               /* pass an index or offset. */
 165
 166  uint16_t     wLength         /* number of data bytes to transfer */
 167                               /* with command, if any.  Same as */
 168                               /* size of mblk "data" below.   */
 169
 170  usb_req_attrs_t attrs;       /* required request attributes */
 171 .fi
 172 .in -2
 173
 174 .sp
 175 .LP
 176 Please see \fBusb_request_attributes\fR(9S), or refer to Section \fI5.5\fR of
 177 the \fIUSB 2.0\fR specification for more information on these parameters. (The
 178 USB 2.0 specification is available at \fIwww.usb.org\fR.)
 179 .sp
 180 .LP
 181 Mblks for data are allocated optionally when a request is allocated via
 182 \fBusb_alloc_ctrl_req\fR(9F) by passing a positive value for the \fIlen\fR
 183 argument. Control requests passing or receiving no supplemental data need not
 184 allocate an mblk.
 185 .SH RETURN VALUES
 186 .LP
 187 For \fBusb_pipe_ctrl_xfer()\fR:
 188 .sp
 189 .ne 2
 190 .na
 191 \fBUSB_SUCCESS\fR
 192 .ad
 193 .RS 25n
 194 Transfer was successful.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fBUSB_INVALID_ARGS\fR
 201 .ad
 202 .RS 25n
 203 Request is \fBNULL\fR.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fBUSB_INVALID_CONTEXT\fR
 210 .ad
 211 .RS 25n
 212 Called from interrupt context with the USB_FLAGS_SLEEP flag set.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fBUSB_INVALID_REQUEST\fR
 219 .ad
 220 .RS 25n
 221 The request has been freed or otherwise invalidated.
 222 .sp
 223 A set of conflicting attributes were specified. See
 224 \fBusb_request_attributes\fR(9S).
 225 .sp
 226 The normal and/or exception callback is NULL and USB_FLAGS_SLEEP is not set.
 227 .sp
 228 Data space not provided to a control request while ctrl_wLength is nonzero.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fBUSB_INVALID_PIPE\fR
 235 .ad
 236 .RS 25n
 237 Pipe handle is NULL or invalid.
 238 .sp
 239 Pipe is closing or closed.
 240 .RE
 241
 242 .sp
 243 .ne 2
 244 .na
 245 \fBUSB_NO_RESOURCES\fR
 246 .ad
 247 .RS 25n
 248 Memory, descriptors or other resources unavailable.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fBUSB_HC_HARDWARE_ERROR\fR
 255 .ad
 256 .RS 25n
 257 Host controller is in error state.
 258 .RE
 259
 260 .sp
 261 .ne 2
 262 .na
 263 \fBUSB_FAILURE\fR
 264 .ad
 265 .RS 25n
 266 An asynchronous transfer failed or an internal error occurred.
 267 .sp
 268 The pipe is in an unsuitable state (error, busy, not ready).
 269 .RE
 270
 271 .sp
 272 .LP
 273 Additional status information may be available in the ctrl_completion_reason
 274 and ctrl_cb_flags fields of the request. Please see
 275 \fBusb_callback_flags\fR(9S) and \fBusb_completion_reason\fR(9S) for more
 276 information.
 277 .sp
 278 .LP
 279 For \fBusb_pipe_ctrl_xfer_wait()\fR:
 280 .sp
 281 .ne 2
 282 .na
 283 \fBUSB_SUCCESS\fR
 284 .ad
 285 .RS 23n
 286 Request was successful.
 287 .RE
 288
 289 .sp
 290 .ne 2
 291 .na
 292 \fBUSB_INVALID_CONTEXT\fR
 293 .ad
 294 .RS 23n
 295 Called from interrupt context.
 296 .RE
 297
 298 .sp
 299 .ne 2
 300 .na
 301 \fBUSB_INVALID_ARGS\fR
 302 .ad
 303 .RS 23n
 304 \fIdip\fR is NULL.
 305 .RE
 306
 307 .sp
 308 .LP
 309 Any error code returned by \fBusb_pipe_ctrl_xfer()\fR.
 310 .sp
 311 .LP
 312 Additional status information may be available in the ctrl_completion_reason
 313 and ctrl_cb_flags fields of the request. Please see
 314 \fBusb_callback_flags\fR(9S) and \fBusb_completion_reason\fR(9S) for more
 315 information.
 316 .SH CONTEXT
 317 .LP
 318 The \fBusb_pipe_ctrl_xfer()\fR function may be called from kernel or user
 319 context without regard to arguments and from the interrupt context only when
 320 the USB_FLAGS_SLEEP flag is clear.
 321 .sp
 322 .LP
 323 The \fBusb_pipe_ctrl_xfer_wait()\fR function may be called from kernel or user
 324 context.
 325 .SH EXAMPLES
 326 .in +2
 327 .nf
 328   /* Allocate, initialize and issue a synchronous control request. */
 329
 330   usb_ctrl_req_t ctrl_req;
 331   void control_pipe_exception_callback(
 332       usb_pipe_handle_t, usb_ctrl_req_t*);
 333
 334   ctrl_req = usb_alloc_ctrl_req(dip, 0, USB_FLAGS_SLEEP);
 335
 336   ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_HOST_TO_DEV |
 337       USB_DEV_REQ_TYPE_CLASS | USB_DEV_REQ_RCPT_OTHER;
 338
 339   ctrl_req->ctrl_bRequest     = (uint8_t)USB_PRINTER_SOFT_RESET;
 340   ctrl_req->ctrl_exc_cb       = control_pipe_exception_callback;
 341   ...
 342   ...
 343   if ((rval = usb_pipe_ctrl_xfer(pipe, ctrl_req, USB_FLAGS_SLEEP))
 344       != USB_SUCCESS) {
 345           cmn_err (CE_WARN, "%s%d: Error issuing USB cmd.",
 346               ddi_driver_name(dip), ddi_get_instance(dip));
 347   }
 348
 349   -------
 350
 351   /*
 352    * Allocate, initialize and issue an asynchronous control request to
 353    * read a configuration descriptor.
 354    */
 355
 356   usb_ctrl_req_t *ctrl_req;
 357   void control_pipe_normal_callback(
 358       usb_pipe_handle_t, usb_ctrl_req_t*);
 359   void control_pipe_exception_callback(
 360       usb_pipe_handle_t, usb_ctrl_req_t*);
 361   struct buf *bp = ...;
 362
 363   ctrl_req =
 364       usb_alloc_ctrl_req(dip, sizeof(usb_cfg_descr_t), USB_FLAGS_SLEEP);
 365
 366   ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_DEV_TO_HOST |
 367       USB_DEV_REQ_TYPE_STANDARD | USB_DEV_REQ_RCPT_DEV;
 368
 369   ctrl_req->ctrl_wLength      = sizeof(usb_cfg_descr_t);
 370   ctrl_req->ctrl_wValue       = USB_DESCR_TYPE_SETUP_CFG | 0;
 371   ctrl_req->ctrl_bRequest     = (uint8_t)USB_REQ_GET_DESCR;
 372   ctrl_req->ctrl_cb           = control_pipe_normal_callback;
 373   ctrl_req->ctrl_exc_cb       = control_pipe_exception_callback;
 374
 375   /* Make buf struct available to callback handler. */
 376   ctrl_req->ctrl_client_private = (usb_opaque_t)bp;
 377   ...
 378   ...
 379   if ((rval = usb_pipe_ctrl_xfer(pipe, ctrl_req, USB_FLAGS_NOSLEEP))
 380       != USB_SUCCESS) {
 381           cmn_err (CE_WARN, "%s%d: Error issuing USB cmd.",
 382               ddi_driver_name(dip), ddi_get_instance(dip));
 383   }
 384
 385   -------
 386
 387   /* Call usb_pipe_ctrl_xfer_wait() to get device status. */
 388
 389   mblk_t *data;
 390   usb_cr_t completion_reason;
 391   usb_cb_flags_t callback_flags;
 392   usb_ctrl_setup_t setup_params = {
 393       USB_DEV_REQ_DEV_TO_HOST |       /* bmRequestType */
 394           USB_DEV_REQ_TYPE_STANDARD | USB_DEV_REQ_RCPT_DEV,
 395       USB_REQ_GET_STATUS,             /* bRequest */
 396       0,                              /* wValue */
 397       0,                              /* wIndex */
 398       USB_GET_STATUS_LEN,             /* wLength */
 399       0                               /* attributes. */
 400   };
 401
 402   if (usb_pipe_ctrl_xfer_wait(
 403       pipe,
 404       &setup_params,
 405       &data,
 406       &compleetion_reason,
 407       &callback_flags,
 408       0) != USB_SUCCESS) {
 409           cmn_err (CE_WARN,
 410               "%s%d: USB get status command failed: "
 411               "reason=%d callback_flags=0x%x",
 412               ddi_driver_name(dip), ddi_get_instance(dip),
 413               completion_reason, callback_flags);
 414           return (EIO);
 415   }
 416
 417   /* Check data length.  Should be USB_GET_STATUS_LEN (2 bytes). */
 418   length_returned = data->b_wptr - data->b_rptr;
 419   if (length_returned != USB_GET_STATUS_LEN) {
 420         cmn_err (CE_WARN,
 421             "%s%d: USB get status command returned %d bytes of data.",
 422             ddi_driver_name(dip), ddi_get_instance(dip), length_returned);
 423           return (EIO);
 424   }
 425
 426   /* Retrieve data in endian neutral way. */
 427   status = (*(data->b_rptr + 1) << 8) | *(data->b_rptr);
 428
 429 .fi
 430 .in -2
 431
 432 .SH ATTRIBUTES
 433 .LP
 434 See \fBattributes\fR(5) for descriptions of the following attributes:
 435 .sp
 436
 437 .sp
 438 .TS
 439 box;
 440 c | c
 441 l | l .
 442 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 443 _
 444 Architecture    PCI-based systems
 445 _
 446 Interface stability     Committed
 447 .TE
 448
 449 .SH SEE ALSO
 450 .LP
 451 \fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F),
 452 \fBusb_get_status\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
 453 \fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F),
 454 \fBusb_pipe_xopen\fR(9F), \fBusb_pipe_reset\fR(9F),
 455 \fBusb_pipe_get_state\fR(9F), \fBusb_bulk_request\fR(9S),
 456 \fBusb_callback_flags\fR(9S), \fBusb_ctrl_request\fR(9S),
 457 \fBusb_completion_reason\fR(9S), \fBusb_intr_request\fR(9S),
 458 \fBusb_isoc_request\fR(9S)