usr/src/man/man9f/usb_pipe_isoc_xfer.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_PIPE_ISOC_XFER 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_pipe_isoc_xfer, usb_pipe_stop_isoc_polling \- USB isochronous 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_isoc_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_isoc_req_t *\fR\fIrequest\fR,
  18      \fBusb_flags_t\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fB\fR
  24
  25 \fBvoid \fR\fBusb_pipe_stop_isoc_polling\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \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_isoc_xfer()\fR:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIpipe_handle\fR\fR
  38 .ad
  39 .RS 15n
  40 Isochronous 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 isochronous 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 needed resources if
  59 unavailable.
  60 .RE
  61
  62 .sp
  63 .LP
  64 For \fBusb_pipe_stop_isoc_polling()\fR:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIpipe_handle\fR\fR
  69 .ad
  70 .RS 15n
  71 Isochronous pipe handle on which to stop polling for input.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIflags\fR\fR
  78 .ad
  79 .RS 15n
  80 USB_FLAGS_SLEEP is the only flag recognized. Wait for polling to stop.
  81 .RE
  82
  83 .SH DESCRIPTION
  84 .LP
  85 The \fBusb_pipe_isoc_xfer()\fR function requests the USBA framework to perform
  86 a transfer     through a USB isochronous pipe. The request is passed to the
  87 host controller driver (HCD), which performs the necessary transactions to
  88 complete the request.
  89 .sp
  90 .LP
  91 By their nature, isochronous transfers require several transactions for
  92 completion. Each request may contain several packet descriptors. Descriptors
  93 correspond to subtransfers to be made in different frames. A request is deemed
  94 completed once all packets of that request have been processed.  It is illegal
  95 to specify the USB_ATTRS_ONE_XFER attribute in an isochronous request.  The
  96 isochronous polling interval is always one millisecond, the period of a
  97 full-speed frame.
  98 .sp
  99 .LP
 100 All isochronous requests are asynchronous, and will notify the caller of
 101 their completion via a callback function.  All isochronous requests must
 102 specify normal and exception callback handlers.
 103 .sp
 104 .LP
 105 Requests will wait for needed, unavailable resources when USB_FLAGS_SLEEP has
 106 been specified in flags.  Requests made without USB_FLAGS_SLEEP set will fail
 107 if needed resources are not readily available.
 108 .sp
 109 .LP
 110 No errors seen during request processing will result in aborted transfers or
 111 exception callbacks. Such errors will instead be logged in the packet
 112 descriptor's isoc_pkt_status field. These errors can be examined when the
 113 completed request is returned through a normal callback.
 114 .SS "Isochronous-OUT TRANSFERS"
 115 .LP
 116 Allocate room for data when allocating isochronous-OUT requests via
 117 usb_alloc_isoc_req(9F), by passing a positive value for     the \fIlen\fR
 118 argument. The data will be divided among the request transactions, each
 119 transaction represented by a packet descriptor.  (See usb_isoc_request(9F).
 120 When all of the data has been sent, regardless of any errors encountered, a
 121 normal transfer callback will be     made to notify the client driver of
 122 completion.
 123 .sp
 124 .LP
 125 If a request is submitted while other requests are active or queued, and the
 126 new request has its USB_ATTRS_ISOC_XFER_ASAP attribute set, the host controller
 127 driver will queue the request to start on a frame which immediately follows the
 128 last frame of the last queued request.
 129 .SS "Isochronous-IN TRANSFERS"
 130 .LP
 131 All isochronous-IN transfers start background polling, and require only a
 132 single (original) request.  The USBA framework will allocate a new request each
 133 time polling has new data to return. Specify a zero length when calling
 134 usb_alloc_isoc_req() to allocate the original request, since it will not be
 135 used to return data.  Set the isoc_pkts_length in the request to specify how
 136 much data to poll per interval (the length of one packet in the request).
 137 .sp
 138 .LP
 139 The original request passed to \fBusb_pipe_isoc_xfer()\fR will be used to
 140 return status when polling termination is requested, or for error condition
 141 notification. There can be only one isochronous-IN request submitted at a time.
 142 .SS "CALLBACKS"
 143 .LP
 144 Isochronous transfer normal-completion callbacks cannot block for any reason
 145 since they are called from interrupt context.  They will have
 146 USB_CB_INTR_CONTEXT set in their callback flags to note this.
 147 .sp
 148 .LP
 149 Isochronous exception callbacks have the following restrictions for blocking:
 150 .RS +4
 151 .TP
 152 1.
 153 They can block for resources (for example to allocate memory).
 154 .RE
 155 .RS +4
 156 .TP
 157 2.
 158 They cannot block for synchronous completion of a command (for example
 159 usb_pipe_close(9F)) done on the same pipe.  Asynchronous commands can be
 160 started, when the pipe's policy pp_max_async_reqs field is initialized to
 161 accommodate them.
 162 .RE
 163 .RS +4
 164 .TP
 165 3.
 166 They cannot block waiting for another callback to complete.
 167 .RE
 168 .RS +4
 169 .TP
 170 4.
 171  They cannot block waiting for a synchronous transfer request to complete.
 172 They can, however, make an asynchronous request (such as restarting polling
 173 with a new isochronous-IN transfer).
 174 .RE
 175 .sp
 176 .LP
 177 Please see the section on callbacks in \fBusb_callback_flags\fR(9S) for more
 178 information.
 179 .sp
 180 .LP
 181 All isochronous transfer exception callbacks signify that polling has stopped.
 182 Polling requests are returned with the following completion reasons:
 183 .sp
 184 .in +2
 185 .nf
 186         USB_CR_STOPPED_POLLING
 187         USB_CR_PIPE_CLOSING
 188 .fi
 189 .in -2
 190
 191 .sp
 192 .LP
 193 Note: There are no exception callbacks for error conditions.
 194 .sp
 195 .LP
 196 The \fBusb_pipe_stop_isoc_polling()\fR function terminates polling on an
 197 isochronous-IN pipe. The \fBusb_pipe_stop_isoc_polling()\fR function does the
 198 following:
 199 .RS +4
 200 .TP
 201 1.
 202 Cease polling.
 203 .RE
 204 .RS +4
 205 .TP
 206 2.
 207 Allow any requests-in-progress to complete and be returned to the client
 208 driver through the normal callback mechanism.
 209 .RE
 210 .RS +4
 211 .TP
 212 3.
 213 Idle the pipe.
 214 .RE
 215 .RS +4
 216 .TP
 217 4.
 218 Return the original polling request to the client driver through an
 219 exception callback with a completion reason of
 220 USB_CR_STOPPED_POLLING.
 221 .RE
 222 .SH RETURN VALUES
 223 .LP
 224 For \fBusb_pipe_isoc_xfer()\fR:
 225 .sp
 226 .ne 2
 227 .na
 228 \fBUSB_SUCCESS\fR
 229 .ad
 230 .RS 27n
 231 Transfer was successful.
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fBUSB_INVALID_ARGS\fR
 238 .ad
 239 .RS 27n
 240 Request is \fBNULL\fR.
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fBUSB_INVALID_CONTEXT\fR
 247 .ad
 248 .RS 27n
 249 Called from interrupt context with the USB_FLAGS_SLEEP flag set.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fBUSB_INVALID_REQUEST\fR
 256 .ad
 257 .RS 27n
 258 The request has been freed or otherwise invalidated.
 259 .sp
 260 A set of conflicting  attributes were specified. See
 261 \fBusb_isoc_request\fR(9S).
 262 .sp
 263 The normal   and/or exception callback was NULL, USB_FLAGS_SLEEP  was  not set
 264 and USB_ATTRS_ONE_XFER was not set.
 265 .sp
 266 An isochronous request was specified with a zeroed isoc_pkt_descr, a NULL
 267 isoc_pkt_descr, or a NULL data argument.
 268 .sp
 269 An isochronous request was specified with USB_ATTRS_ISOC_XFER_ASAP and a
 270 nonzero isoc_frame_no.
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fBUSB_NO_FRAME_NUMBER\fR
 277 .ad
 278 .RS 27n
 279 An isochronous request was not specified with one and only one   of
 280 USB_ATTRS_ISOC_START_FRAME or USB_ATTRS_ISOC_XFER_ASAP specified.
 281 .sp
 282 An  isochronous request was specified with USB_ATTRS_ISOC_START_FRAME and a
 283 zero isoc_frame_no.
 284 .RE
 285
 286 .sp
 287 .ne 2
 288 .na
 289 \fBUSB_INVALID_START_FRAME\fR
 290 .ad
 291 .RS 27n
 292 An isochronous request was specified with an invalid starting frame number
 293 (less than current frame number, or zero) and USB_ATTRS_ISOC_START_FRAME
 294 specified.
 295 .RE
 296
 297 .sp
 298 .ne 2
 299 .na
 300 \fBUSB_INVALID_PIPE\fR
 301 .ad
 302 .RS 27n
 303 Pipe handle is NULL or invalid.
 304 .sp
 305  Pipe is closing or closed.
 306 .RE
 307
 308 .sp
 309 .ne 2
 310 .na
 311 \fBUSB_PIPE_ERROR\fR
 312 .ad
 313 .RS 27n
 314 Pipe  handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state.
 315 .RE
 316
 317 .sp
 318 .ne 2
 319 .na
 320 \fBUSB_NO_RESOURCES\fR
 321 .ad
 322 .RS 27n
 323 Memory, descriptors or other resources unavailable.
 324 .RE
 325
 326 .sp
 327 .ne 2
 328 .na
 329 \fBUSB_HC_HARDWARE_ERROR\fR
 330 .ad
 331 .RS 27n
 332 Host controller is in error state.
 333 .RE
 334
 335 .sp
 336 .ne 2
 337 .na
 338 \fBUSB_FAILURE\fR
 339 .ad
 340 .RS 27n
 341 An asynchronous transfer failed or an internal error occurred.
 342 .sp
 343 .in +2
 344 .nf
 345 An isoch request requested too much data:
 346     (length   >  (usb_get_max_pkts_per_isoc_request()  *
 347      endpoint's  wMaxPacketSize))
 348 .fi
 349 .in -2
 350
 351 The pipe is in an unsuitable state (error, busy, not ready).
 352 .RE
 353
 354 .sp
 355 .LP
 356 Additional status information may be available in the isoc_completion_reason
 357 and isoc_cb_flags fields of the request. Please see
 358 \fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more
 359 information.
 360 .sp
 361 .LP
 362 For \fBusb_pipe_stop_isoc_polling()\fR:
 363 .sp
 364 .LP
 365 None, but will fail if called with USB_FLAGS_SLEEP specified from interrupt
 366 context; the pipe handle is invalid, NULL or pertains to a closing or closed
 367 pipe; or the pipe is in an error state. Messages regarding these errors will be
 368 logged to the console logfile.
 369 .SH CONTEXT
 370 .LP
 371 Both of these functions may be called from kernel or user context without
 372 regard to arguments. May be called from interrupt context only when the
 373 USB_FLAGS_SLEEP flag is clear.
 374 .SH EXAMPLES
 375 .in +2
 376 .nf
 377 /* Start polling on an isochronous-IN pipe. */
 378
 379     usb_isoc_req_t isoc_req;
 380     void isoc_pipe_callback(usb_pipe_handle_t, usb_isoc_req_t*);
 381     void isoc_pipe_exception_callback(
 382         usb_pipe_handle_t, usb_isoc_req_t*);
 383     uint_t pkt_size;
 384     usb_ep_data_t *isoc_ep_tree_node;
 385     usb_ep_descr_t *isoc_ep_descr = ...;   /* From usb_lookup_ep_data() */
 386
 387     isoc_ep_descr = &isoc_ep_tree_node->ep_descr;
 388     pkt_size = isoc_ep_descr->wMaxPacketSize;
 389
 390     isoc_req = usb_alloc_isoc_req(
 391         dip, num_pkts, NUM_PKTS * pkt_size, USB_FLAGS_SLEEP);
 392     ...
 393     ...
 394     isoc_req->isoc_attributes = USB_ATTRS_ISOC_XFER_ASAP;
 395     ...
 396     ...
 397     isoc_req->isoc_cb         = isoc_pipe_callback;
 398     isoc_req->isoc_exc_cb     = isoc_pipe_exception_callback;
 399     ...
 400     ...
 401     isoc_req->isoc_pkts_length  = pkt_size;
 402     isoc_req->isoc_pkts_count   = NUM_PKTS;
 403     for (pkt = 0; pkt < NUM_PKTS; pkt++) {
 404             isoc_req->isoc_pkt_descr[pkt].isoc_pkt_length = pkt_size;
 405     }
 406
 407     if ((rval = usb_pipe_isoc_xfer(pipe, isoc_req, USB_FLAGS_NOSLEEP))
 408         != USB_SUCCESS) {
 409             cmn_err (CE_WARN,"%s%d: Error starting isochronous pipe polling.",
 410                 ddi_driver_name(dip), ddi_get_instance(dip));
 411     }
 412
 413     -------
 414
 415     /* Stop polling before powering off device. Wait for polling to stop. */
 416
 417     usb_pipe_stop_isoc_polling(pipe, USB_FLAGS_SLEEP);
 418     pm_idle_component(dip, 0);
 419
 420 .fi
 421 .in -2
 422
 423 .SH ATTRIBUTES
 424 .LP
 425 See \fBattributes\fR(5) for descriptions of the following attributes:
 426 .sp
 427
 428 .sp
 429 .TS
 430 box;
 431 c | c
 432 l | l .
 433 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 434 _
 435 Architecture    PCI-based systems
 436 _
 437 Interface stability     Evolving
 438 .TE
 439
 440 .SH SEE ALSO
 441 .LP
 442 \fBattributes\fR(5), \fBusb_alloc_request\fR(9F),
 443 \fBusb_get_current_frame_number\fR(9F), \fBusb_get_cfg\fR(9F),
 444 \fBusb_get_max_pkts_per_isoc_request\fR(9F), \fBusb_get_status\fR(9F),
 445 \fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F),
 446 \fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
 447 \fBusb_pipe_xopen\fR(9F), \fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S),
 448 \fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
 449 \fBusb_ctrl_request\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_intr_request\fR(9S),
 450 \fBusb_isoc_request\fR(9S)