| blob | 137a3f7a8729bc1b6f28f26720803f4a9bf4ff53 |
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>
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
21 .LP
22 .nf
23 \fB\fR
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
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
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
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
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
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
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(9S).
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
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
234 .sp
235 .ne 2
236 .na
237 \fBUSB_INVALID_ARGS\fR
238 .ad
239 .RS 27n
240 Request is \fBNULL\fR.
241 .RE
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
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
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
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
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
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
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
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
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
351 The pipe is in an unsuitable state (error, busy, not ready).
352 .RE
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. */
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() */
387 isoc_ep_descr = &isoc_ep_tree_node->ep_descr;
388 pkt_size = isoc_ep_descr->wMaxPacketSize;
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 }
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 }
413 -------
415 /* Stop polling before powering off device. Wait for polling to stop. */
417 usb_pipe_stop_isoc_polling(pipe, USB_FLAGS_SLEEP);
418 pm_idle_component(dip, 0);
420 .fi
421 .in -2
423 .SH ATTRIBUTES
424 .LP
425 See \fBattributes\fR(5) for descriptions of the following attributes:
426 .sp
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
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)