share/man/man9f/usb_pipe_intr_xfer.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_PIPE_INTR_XFER 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_pipe_intr_xfer, usb_pipe_stop_intr_polling \- USB interrupt transfer and
   9 polling functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/usb/usba.h>
  14
  15
  16
  17 \fBint\fR \fBusb_pipe_intr_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_intr_req_t *\fR\fIrequest\fR,
  18      \fBusb_flags_t\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBusb_pipe_stop_intr_polling\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb__flags_t\fR \fIflags\fR);
  24 .fi
  25
  26 .SH INTERFACE LEVEL
  27 .LP
  28 Solaris DDI specific (Solaris DDI)
  29 .SH PARAMETERS
  30 .LP
  31 For \fBusb_pipe_intr_xfer()\fR:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fIpipe_handle\fR\fR
  36 .ad
  37 .RS 15n
  38 Interrupt pipe handle on which request is made.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIrequest\fR\fR
  45 .ad
  46 .RS 15n
  47 Pointer to interrupt transfer request.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIflags\fR\fR
  54 .ad
  55 .RS 15n
  56 USB_FLAGS_SLEEP is the only flag recognized. Wait for needed resources if
  57 unavailable. For requests specifying the USB_ATTRS_ONE_XFER attribute, wait for
  58 the request to complete.
  59 .RE
  60
  61 .sp
  62 .LP
  63 For \fBusb_pipe_stop_intr_polling()\fR:
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fIpipe_handle\fR\fR
  68 .ad
  69 .RS 15n
  70 Interrupt pipe handle on which to stop polling for data.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fIflags\fR\fR
  77 .ad
  78 .RS 15n
  79 USB_FLAGS_SLEEP is the only flag recognized. Wait for polling to stop.
  80 .RE
  81
  82 .SH DESCRIPTION
  83 .LP
  84 The \fBusb_pipe_intr_xfer()\fR function requests the USBA framework to perform
  85 a transfer through a USB interrupt pipe. The request is passed to the host
  86 controller driver (HCD), which performs the necessary transactions to complete
  87 the request.
  88 .sp
  89 .LP
  90 There are three categories of interrupt transfers: periodic or polled
  91 interrupt-IN, single-transfer interrupt-IN, and (single-transfer)
  92 interrupt-OUT.
  93 .SS "Periodic Interrupt-IN Transfers"
  94 .LP
  95 Periodic or polled interrupt-IN transfers execute on input requests which do
  96 not have the USB_ATTRS_ONE_XFER attribute set. One request enables repetitive
  97 transfers at a periodic rate set by the endpoint's bInterval. There can be only
  98 one interrupt-IN request submitted at a time.
  99 .sp
 100 .LP
 101 Periodic interrupt-IN transfers are always asynchronous. Client driver
 102 notification of new data is always via a callback. The USB_FLAGS_SLEEP flag is
 103 only to wait for resources to become available. Callbacks must always be in
 104 place to receive transfer completion notification. Please see
 105 \fBusb_callback_flags\fR(9S) for details on USB callbacks.
 106 .sp
 107 .LP
 108 Calls made to \fBusb_pipe_intr_xfer()\fR for starting input polling need
 109 allocate only one request. The USBA framework allocates a new request each time
 110 polling has new data to return.  (Note that each request returned must be freed
 111 via \fBusb_free_intr_req\fR(9F). Specify a zero length when calling
 112 \fBusb_alloc_intr_req()\fR to allocate the original request, since it will not
 113 be used to return data.  Set the intr_len in the request to specify how much
 114 data can be returned per polling interval.
 115 .sp
 116 .LP
 117 The original request passed to \fBusb_pipe_intr_xfer()\fR is used to return
 118 status when polling is terminated, or on an error condition when the
 119 USB_ATTRS_AUTOCLEARING attribute is set for the request. If autoclearing is not
 120 set, the current (non-original) request is returned on error. Call
 121 \fBusb_pipe_reset\fR(9F) to reset the pipe and get back the original request in
 122 this case. The USB_CR_STOPPED_POLLING flag is always set for callbacks where
 123 the original request is returned.
 124 .SS "Single-transfer Interrupt-IN Transfers"
 125 .LP
 126 Interrupt-IN requests which have the USB_ATTRS_ONE_XFER attribute perform a
 127 single transfer. Such requests are synchronous when the USB_FLAGS_SLEEP flag is
 128 specified. Calls for synchronous requests do not return until their transaction
 129 is complete, and their callbacks are optional. The request is returned to the
 130 client through the normal or the exception completion callback to signal either
 131 normal completion or an error condition.
 132 .SS "Interrupt-OUT Transfers"
 133 .LP
 134 Interrupt-OUT requests always set up for a single transfer. However, multiple
 135 requests can be queued and execute in periodic fashion until depleted.
 136 .sp
 137 .LP
 138 Interrupt-OUT transfers are synchronous when the USB_FLAGS_SLEEP flag is set in
 139 the request's flags. Calls for synchronous transfers will not return until
 140 their transaction has completed. Calls for asynchronous transfers notify the
 141 client driver of transaction completion via a normal callback, or error
 142 completion via an exception callback.
 143 .sp
 144 .LP
 145 The \fBusb_pipe_stop_intr_polling()\fR function terminates polling on
 146 interrupt-IN pipes and does the following:
 147 .br
 148 .in +2
 149 1. Cease polling.
 150 .in -2
 151 .br
 152 .in +2
 153 2. Allow any requests-in-progress to complete and be returned to the client
 154 driver through the normal callback mechanism.
 155 .in -2
 156 .br
 157 .in +2
 158 3. Idle the pipe.
 159 .in -2
 160 .br
 161 .in +2
 162 4. Return the original polling request to the client driver through an
 163 exception callback with a completion reason of USB_CR_STOPPED_POLLING.
 164 .in -2
 165 .sp
 166 .LP
 167 The client driver may restart polling from an exception callback only if the
 168 callback corresponds to an original request. The callback handler checks for
 169 the following completion reasons to ensure that a callback corresponds to an
 170 original request:
 171 .sp
 172 .in +2
 173 .nf
 174         USB_CR_STOPPED_POLLING,
 175         USB_CR_PIPE_RESET,
 176         USB_CR_PIPE_CLOSING,
 177         USB_CR_NOT_SUPPORTED
 178 .fi
 179 .in -2
 180
 181 .sp
 182 .LP
 183 The callback handler also checks the request's intr_data field to mark original
 184 polling requests, when the requests are created with a zero \fIlen\fR argument.
 185 In this case, a NULL intr_data field distinguishes a returned original request
 186 from a request allocated by the framework during polling.
 187 .sp
 188 .LP
 189 Mblks for data for interrupt-OUT requests are allocated when a request is
 190 allocated via \fBusb_alloc_intr_req\fR(9F) by passing a non-negative value for
 191 the \fIlen\fR argument.
 192 .SH RETURN VALUES
 193 .LP
 194 For \fBusb_pipe_intr_xfer()\fR
 195 .sp
 196 .ne 2
 197 .na
 198 \fBUSB_SUCCESS\fR
 199 .ad
 200 .RS 25n
 201 Transfer was successful.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fBUSB_INVALID_ARGS\fR
 208 .ad
 209 .RS 25n
 210 Request is \fBNULL\fR.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fBUSB_INVALID_CONTEXT\fR
 217 .ad
 218 .RS 25n
 219 Called from interrupt context with the USB_FLAGS_SLEEP flag set.
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fBUSB_INVALID_REQUEST\fR
 226 .ad
 227 .RS 25n
 228 The request has been freed or otherwise invalidated.
 229 .sp
 230 A set of conflicting attributes was specified. See \fBusb_intr_request\fR(9S).
 231 .sp
 232 The normal and/or  exception callback was NULL, USB_FLAGS_SLEEP was not set and
 233 USB_ATTRS_ONE_XFER was not set.
 234 .sp
 235 An interrupt request was  specified with a NULL data and a non-zero intr_len
 236 value.
 237 .sp
 238 An IN interrupt request was specified with both polling (USB_ATTRS_ONE_XFER
 239 clear in attributes) and non-zero timeout specified.
 240 .sp
 241 An IN interrupt request was specified with a  non-NULL data argument.
 242 .sp
 243 An OUT interrupt request was specified with a NULL data argument.
 244 .RE
 245
 246 .sp
 247 .ne 2
 248 .na
 249 \fBUSB_INVALID_PIPE\fR
 250 .ad
 251 .RS 25n
 252 Pipe handle is NULL or invalid.
 253 .sp
 254 Pipe is closing or closed.
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fBUSB_PIPE_ERROR\fR
 261 .ad
 262 .RS 25n
 263 Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state.
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fBUSB_NO_RESOURCES\fR
 270 .ad
 271 .RS 25n
 272 Memory, descriptors or other resources unavailable.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fBUSB_HC_HARDWARE_ERROR\fR
 279 .ad
 280 .RS 25n
 281 Host controller is in error state.
 282 .RE
 283
 284 .sp
 285 .ne 2
 286 .na
 287 \fBUSB_FAILURE\fR
 288 .ad
 289 .RS 25n
 290 An asynchronous transfer failed or an internal error occurred.
 291 .sp
 292 An intr polling request is made while polling is already in progress.
 293 .sp
 294 The pipe is in an unsuitable state (error, busy, not ready).
 295 .sp
 296 Additional status information may be available in the intr_completion_reason
 297 and intr_cb_flags fields of the request. Please see
 298 \fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more
 299 information.
 300 .RE
 301
 302 .sp
 303 .LP
 304 For \fBusb_pipe_stop_intr_polling()\fR
 305 .sp
 306 .LP
 307 None, but fails if called with USB_FLAGS_SLEEP specified from interrupt
 308 context, pipe handle is invalid, NULL or pertains to a closing or closed pipe,
 309 or the pipe is in an error state. Error messages are logged to the console
 310 logfile.
 311 .sp
 312 .LP
 313 Exception handlers' queued requests which are flushed by these commands before
 314 execution are returned with completion reason of USB_CR_FLUSHED.
 315 .SH CONTEXT
 316 .LP
 317 Both of these functions can be called from kernel or user context without
 318 regard to arguments, and may be called from interrupt context only when the
 319 USB_FLAGS_SLEEP flag is clear.
 320 .SH EXAMPLES
 321 .in +2
 322 .nf
 323  /* Start polling on interrupt-IN pipe. */
 324
 325  usb_intr_req_t intr_req;
 326  void intr_pipe_callback(usb_pipe_handle_t, usb_intr_req_t*);
 327  void intr_pipe_exception_callback(
 328      usb_pipe_handle_t, usb_intr_req_t*);
 329  usb_ep_descr_t *ep_descr;
 330
 331  ep_descr = ...;
 332  intr_req = usb_alloc_intr_req(dip, 0, USB_FLAGS_SLEEP);
 333  ...
 334  ...
 335  intr_req->intr_attributes   = USB_ATTRS_SHORT_XFER_OK;
 336  intr_req->intr_len          = ep_descr->wMaxPacketSize;
 337  ...
 338  ...
 339  intr_req->intr_cb           = intr_pipe_callback;
 340  intr_req->intr_exc_cb       = intr_pipe_exception_callback;
 341
 342  if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_NOSLEEP))
 343      != USB_SUCCESS) {
 344        cmn_err (CE_WARN, "%s%d: Error starting interrupt pipe polling.",
 345            ddi_driver_name(dip), ddi_get_instance(dip));
 346  }
 347
 348  -------
 349
 350  /* Stop polling before setting device idle.  Wait for polling to stop. */
 351
 352  usb_pipe_stop_intr_polling(pipe, USB_FLAGS_SLEEP);
 353  (void) pm_idle_component(dip, 0);
 354
 355  -------
 356
 357  /* Allocate, initialize and issue a synchronous intr-OUT request. */
 358
 359  usb_intr_req_t intr_req;
 360  mblk_t *mblk;
 361  usb_ep_descr_t *ep_descr;
 362
 363  ep_descr = ...;
 364
 365  intr_req =
 366    usb_alloc_intr_req(dip, ep_descr->wMaxPacketSize, USB_FLAGS_SLEEP);
 367
 368  intr_req->intr_attributes   = USB_ATTRS_AUTOCLEARING;
 369  mblk = intr_req->intr_data;
 370  bcopy(buffer, mblk->b_wptr, ep_descr->wMaxPacketSize);
 371  mblk->b_wptr += ep_descr->wMaxPacketSize;
 372
 373  if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_SLEEP))
 374      != USB_SUCCESS) {
 375          cmn_err (CE_WARN, "%s%d: Error writing intr data.",
 376              ddi_driver_name(dip), ddi_get_instance(dip));
 377  }
 378
 379 .fi
 380 .in -2
 381
 382 .SH ATTRIBUTES
 383 .LP
 384 See \fBattributes\fR(5) for descriptions of the following attributes:
 385 .sp
 386
 387 .sp
 388 .TS
 389 box;
 390 c | c
 391 l | l .
 392 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 393 _
 394 Architecture    PCI-based systems
 395 _
 396 Interface stability     Evolving
 397 .TE
 398
 399 .SH SEE ALSO
 400 .LP
 401 \fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F),
 402 \fBusb_get_status\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
 403 \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_get_state\fR(9F),
 404 \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_xopen\fR(9F),
 405 \fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S),
 406 \fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
 407 \fBusb_ctrl_request\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_intr_request\fR(9S),
 408 \fBusb_isoc_request\fR(9S)