8322 nl: misleading-indentation
[unleashed/tickless.git] / usr / src / man / man9s / usb_isoc_req.9s
blob83d4b7e17c7e17b744c079dae8eef9d8833d2871
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_ISOC_REQUEST 9S "April 9, 2016"
7 .SH NAME
8 usb_isoc_req, usb_isoc_req_t, usb_isoc_request \- USB isochronous request structure
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/usb/usba.h>
13 .fi
15 .SH INTERFACE LEVEL
16 .LP
17 Solaris DDI specific (Solaris DDI)
18 .SH DESCRIPTION
19 .LP
20 A request sent through an isochronous pipe is used to transfer large amounts of
21 packetized data with relative unreliability, but with bounded service periods.
22 A packet is guaranteed to be tried within a bounded time period, but is not
23 retried upon failure. Isochronous transfers are supported on both USB 1.1 and
24 USB 2.0 devices. For further information, see section \fI5.6\fR of the \fIUSB
25 2.0\fR specification available at \fIwww.usb.org\fR.
26 .sp
27 .LP
28 This section provides information on acceptable combinations of flags and
29 attributes with additional details. The following fields of the usb_isoc_req_t
30 are used to format an isochronous request.
31 .sp
32 .in +2
33 .nf
34 usb_frame_number_t
35                 isoc_frame_no;   /* frame num to start sending req. */
36 ushort_t       isoc_pkts_count; /* num USB pkts in this request */
38  * The sum of all pkt lengths in an isoc request. Recommend to set it to
39  * zero, so the sum of isoc_pkt_length in the isoc_pkt_descr list will be
40  * used automatically and no check will be apply to this element.
41  */
42 ushort_t       isoc_pkts_length;
43 ushort_t       isoc_error_count;/* num pkts completed w/errs */
44 usb_req_attrs_t isoc_attributes;/* request-specific attrs */
45 mblk_t          *isoc_data;     /* data to xfer */
46                                  /* IN or OUT: alloc. by client. */
47                                  /* Size=total of all pkt lengths. */
48 usb_opaque_t     isoc_client_private; /* for client driver excl use. */
49 struct usb_isoc_pkt_descr       /* (see below) */
50                  *isoc_pkt_descr;
53  * Normal callback function, called upon completion.
54  * This function cannot block as it executes in soft interrupt context.
55  */
56 void       (*isoc_cb)(
57                 usb_pipe_handle_t ph, struct usb_isoc_req *req);
59 /* Exception callback function, for error handling. */
60 void       (*isoc_exc_cb)(
61                usb_pipe_handle_t ph, struct usb_isoc_req *req);
63 usb_cr_t  isoc_completion_reason; /* overall completion status */
64                                    /* set by USBA framework */
65                                    /* See usb_completion_reason(9S) */
66 usb_cb_flags_t  isoc_cb_flags;    /* recovery done by callback hndlr */
67                                    /* set by USBA on exception. */
68                                    /* See usb_callback_flags(9S) */
69 .fi
70 .in -2
72 .sp
73 .LP
74 A \fBusb_isoc_pkt_descr_t\fR describes the status of an isochronous packet
75 transferred within a frame or microframe. The following fields of a
76 \fBusb_isoc_pkt_descr_t\fR packet descriptor are used within an
77 \fBusb_isoc_req_t\fR. The \fBisoc_pkt_length\fR is set by the client driver to
78 the amount of data managed by the packet for input or output. The latter two
79 fields are set by the \fBUSBA\fR framework to indicate status. Any packets with
80 an \fBisoc_completion_reason\fR, other than \fBUSB_CR_OK\fR, are reflected in
81 the \fBisoc_error_count\fR of the \fBusb_isoc_req_t\fR.
82 .sp
83 .in +2
84 .nf
85      ushort_t    isoc_pkt_length;        /* number bytes to transfer */
86       ushort_t    isoc_pkt_actual_length; /* actual number transferred */
87       usb_cr_t    isoc_pkt_status;        /* completion status */
88 .fi
89 .in -2
91 .sp
92 .LP
93 If two multi-frame \fBisoc\fR requests that both specify the
94 \fBUSB_ATTRS_ISOC_XFER_ASAP\fR attribute are scheduled closely together, the
95 first frame of the second request is queued to start after the last frame of
96 the first request.
97 .sp
98 .LP
99 No stalls are seen in isochronous transfer exception callbacks. Because
100 transfers are not retried upon failure, isochronous transfers continue
101 regardless of errors.
104 Request attributes define special handling for transfers. The following
105 attributes are valid for isochronous requests:
107 .ne 2
109 \fB\fBUSB_ATTRS_ISOC_START_FRAME\fR\fR
111 .RS 30n
112 Start transferring at the starting frame number specified in the
113 \fBisoc_frame_no\fR field of the request.
117 .ne 2
119 \fB\fBUSB_ATTRS_ISOC_XFER_ASAP\fR\fR
121 .RS 30n
122 Start transferring as soon as possible. The \fBUSBA\fR framework picks an
123 immediate frame number to map to the starting frame number.
127 .ne 2
129 \fB\fBUSB_ATTRS_SHORT_XFER_OK\fR\fR
131 .RS 30n
132 Accept transfers where less data is received than expected.
137 The \fBusb_isoc_req_t\fR contains an array of descriptors that describe
138 isochronous packets. One isochronous packet is sent per frame or microframe.
139 Because packets that comprise a transfer are sent across consecutive frames or
140 microframes, \fBUSB_ATTRS_ONE_XFER\fR is invalid.
143 See \fBusb_request_attributes\fR(9S) for more information.
146 Isochronous transfers/requests are subject to the following constraints and
147 caveats:
149 .in +2
151 1) The following table indicates combinations of usb_pipe_isoc_xfer
152    flags argument and fields of the usb_isoc_req_t request argument
153    (X = don't care). (Note that attributes considered in this table
154    are ONE_XFER, START_FRAME, XFER_ASAP, and SHORT_XFER, and that
155    some transfer types are characterized by multiple table entries.)
157 Flags Type     Attributes          Data    Semantics
158 ---------------------------------------------------------------
159 X      X      X                    NULL    illegal
161 X      X      ONE_XFER             X       illegal
163 X      X      ISOC_START_FRAME     X       illegal
164               & ISOC_XFER_ASAP
166 X      X      !ISOC_START_FRAME    X       illegal
167               & !ISOC_XFER_ASAP
169 X      OUT    SHORT_XFER_OK        X       illegal
171 X      IN     X                    !=NULL  See table note (A)
173 X      X      ISOC_START_FRAME     !=NULL  See table note (B)
175 X      X      ISOC_XFER_ASAP       !=NULL  See table note (C)
177 Table notes:
179     A) continuous polling, new data is returned in
180        cloned request structures via continuous callbacks,
181        original request is returned on stop polling
183     B) invalid if the current_frame number is past
184        "isoc_frame_no" or "isoc_frame_no" == 0
186     C)"isoc_frame_no" is ignored. The USBA framework
187        determines which frame to insert and start
188        the transfer.
190 2) USB_FLAGS_SLEEP indicates to wait for resources but
191    not for completion.
193 3) For polled reads:
195   A. The USBA  framework  accepts  a  request  which
196      specifies  the  size and number of packets to fill
197      with data. The packets get filled one  packet  per
198      (1  ms)  frame/(125 us) microframe.  All  requests
199      have an implicit USB_ATTRS_SHORT_XFER_OK attribute
200      set, since transfers  continue in spite of any en-
201      countered. The amount of data read per packet  will
202      match  the  isoc_pkt_length  field  of  the packet
203      descriptor unless a  short  transfer  occurs.  The
204      actual     size     is     returned     in     the
205      isoc_pkt_actual_length   field   of   the   packet
206      descriptor.  When  all packets of the request have
207      been processed, a normal callback is done to  sig-
208      nal the completion of the original request.
210   B. When continuous polling is stopped, the original
211      request is returned in an exception callback with a
212      completion reason of USB_CR_STOPPED_POLLING.
213      (NOTE: Polling can be restarted from  an exception
214      callback corresponding to an original request.
215      Please see usb_pipe_isoc_xfer(9F) for more information.
217   C. Callbacks must be specified.
219   The isoc_completion_reason indicates the status of the transfer. See
220   usb_completion_reason(9s) for usb_cr_t definitions.
222   The isoc_cb_flags are set prior to calling the exception
223   callback handler to summarize recovery actions taken and
224   errors encountered during recovery. See usb_callback_flags(9s)
225   for usb_cb_flags_t definitions.
227 --- Callback handling ---
228 All usb request types share the same callback handling. Please see
229 usb_callback_flags(9s) for a description of use and operation.
231 .in -2
233 .SH ATTRIBUTES
235 See attributes(5) for descriptions of the following attributes:
240 box;
241 c | c
242 l | l .
243 ATTRIBUTE TYPE  ATTRIBUTE VALUE
245 Architecture    PCI-based systems
247 Interface stability     Committed
250 .SH SEE ALSO
252 \fBattributes\fR(5), \fBusb_alloc_request\fR(9F),
253 \fBusb_get_current_frame_number\fR(9F),
254 \fBusb_get_max_pkts_per_isoc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
255 \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
256 \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S),
257 \fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S),
258 \fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S),
259 \fBusb_request_attributes\fR(9S)