1usb_isoc_request(9S) Data Structures for Drivers usb_isoc_request(9S)
2
6 usb_isoc_request - USB isochronous request structure
7
9 #include <sys/usb/usba.h>
10
13 Solaris DDI specific (Solaris DDI)
14
16 A request sent through an isochronous pipe is used to transfer large
17 amounts of packetized data with relative unreliability, but with
18 bounded service periods. A packet is guaranteed to be tried within a
19 bounded time period, but is not retried upon failure. Isochronous
20 transfers are supported on both USB 1.1 and USB 2.0 devices. For fur‐
21 ther information, see section 5.6 of the USB 2.0 specification avail‐
22 able at www.usb.org.
23 This section provides information on acceptable combinations of flags
26 and attributes with additional details. The following fields of the
27 usb_isoc_req_t are used to format an isochronous request.
28 usb_frame_number_t
30 isoc_frame_no; /* frame num to start sending req. */
31 ushort_t isoc_pkts_count; /* num USB pkts in this request */
32 /*
33 * The sum of all pkt lengths in an isoc request. Recommend to set it to
34 * zero, so the sum of isoc_pkt_length in the isoc_pkt_descr list will be
35 * used automatically and no check will be apply to this element.
36 */
37 ushort_t isoc_pkts_length;
38 ushort_t isoc_error_count;/* num pkts completed w/errs */
39 usb_req_attrs_t isoc_attributes;/* request-specific attrs */
40 mblk_t *isoc_data; /* data to xfer */
41 /* IN or OUT: alloc. by client. */
42 /* Size=total of all pkt lengths. */
43 usb_opaque_t isoc_client_private; /* for client driver excl use. */
44 struct usb_isoc_pkt_descr /* (see below) */
45 *isoc_pkt_descr;
46 /*
48 * Normal callback function, called upon completion.
49 * This function cannot block as it executes in soft interrupt context.
50 */
51 void (*isoc_cb)(
52 usb_pipe_handle_t ph, struct usb_isoc_req *req);
53 /* Exception callback function, for error handling. */
55 void (*isoc_exc_cb)(
56 usb_pipe_handle_t ph, struct usb_isoc_req *req);
57 usb_cr_t isoc_completion_reason; /* overall completion status */
59 /* set by USBA framework */
60 /* See usb_completion_reason(9S) */
61 usb_cb_flags_t isoc_cb_flags; /* recovery done by callback hndlr */
62 /* set by USBA on exception. */
63 /* See usb_callback_flags(9S) */
64 A usb_isoc_pkt_descr_t describes the status of an isochronous packet
68 transferred within a frame or microframe. The following fields of a
69 usb_isoc_pkt_descr_t packet descriptor are used within an
70 usb_isoc_req_t. The isoc_pkt_length is set by the client driver to the
71 amount of data managed by the packet for input or output. The latter
72 two fields are set by the USBA framework to indicate status. Any pack‐
73 ets with an isoc_completion_reason, other than USB_CR_OK, are reflected
74 in the isoc_error_count of the usb_isoc_req_t.
75 ushort_t isoc_pkt_length; /* number bytes to transfer */
77 ushort_t isoc_pkt_actual_length; /* actual number transferred */
78 usb_cr_t isoc_pkt_status; /* completion status */
79 If two multi-frame isoc requests that both specify the
83 USB_ATTRS_ISOC_XFER_ASAP attribute are scheduled closely together, the
84 first frame of the second request is queued to start after the last
85 frame of the first request.
86 No stalls are seen in isochronous transfer exception callbacks. Because
89 transfers are not retried upon failure, isochronous transfers continue
90 regardless of errors.
91 Request attributes define special handling for transfers. The following
94 attributes are valid for isochronous requests:
95 USB_ATTRS_ISOC_START_FRAME Start transferring at the starting frame
97 number specified in the isoc_frame_no
98 field of the request.
99 USB_ATTRS_ISOC_XFER_ASAP Start transferring as soon as possible.
102 The USBA framework picks an immediate
103 frame number to map to the starting frame
104 number.
105 USB_ATTRS_SHORT_XFER_OK Accept transfers where less data is
108 received than expected.
109 The usb_isoc_req_t contains an array of descriptors that describe
113 isochronous packets. One isochronous packet is sent per frame or
114 microframe. Because packets that comprise a transfer are sent across
115 consecutive frames or microframes, USB_ATTRS_ONE_XFER is invalid.
116 See usb_request_attributes(9S) for more information.
119 Isochronous transfers/requests are subject to the following constraints
122 and caveats:
123 1) The following table indicates combinations of usb_pipe_isoc_xfer
125 flags argument and fields of the usb_isoc_req_t request argument
126 (X = don't care). (Note that attributes considered in this table
127 are ONE_XFER, START_FRAME, XFER_ASAP, and SHORT_XFER, and that
128 some transfer types are characterized by multiple table entries.)
129 Flags Type Attributes Data Semantics
131 ---------------------------------------------------------------
132 X X X NULL illegal
133 X X ONE_XFER X illegal
135 X X ISOC_START_FRAME X illegal
137 & ISOC_XFER_ASAP
138 X X !ISOC_START_FRAME X illegal
140 & !ISOC_XFER_ASAP
141 X OUT SHORT_XFER_OK X illegal
143 X IN X !=NULL See table note (A)
145 X X ISOC_START_FRAME !=NULL See table note (B)
147 X X ISOC_XFER_ASAP !=NULL See table note (C)
149 Table notes:
151 A) continuous polling, new data is returned in
153 cloned request structures via continous callbacks,
154 original request is returned on stop polling
155 B) invalid if the current_frame number is past
157 "isoc_frame_no" or "isoc_frame_no" == 0
158 C)"isoc_frame_no" is ignored. The USBA framework
160 determines which frame to insert and start
161 the transfer.
162 2) USB_FLAGS_SLEEP indicates to wait for resources but
164 not for completion.
165 3) For polled reads:
167 A. The USBA framework accepts a request which
169 specifies the size and number of packets to fill
170 with data. The packets get filled one packet per
171 (1 ms) frame/(125 us) microframe. All requests
172 have an implicit USB_ATTRS_SHORT_XFER_OK attribute
173 set, since transfers continue in spite of any en-
174 countered. The amount of data read per packet will
175 match the isoc_pkt_length field of the packet
176 descriptor unless a short transfer occurs. The
177 actual size is returned in the
178 isoc_pkt_actual_length field of the packet
179 descriptor. When all packets of the request have
180 been processed, a normal callback is done to sig-
181 nal the completion of the original request.
182 B. When continuous polling is stopped, the original
184 request is returned in an exception callback with a
185 completion reason of USB_CR_STOPPED_POLLING.
186 (NOTE: Polling can be restarted from an exception
187 callback corresponding to an original request.
188 Please see usb_pipe_isoc_xfer(9F) for more information.
189 C. Callbacks must be specified.
191 The isoc_completion_reason indicates the status of the transfer. See
193 usb_completion_reason(9s) for usb_cr_t definitions.
194 The isoc_cb_flags are set prior to calling the exception
196 callback handler to summarize recovery actions taken and
197 errors encountered during recovery. See usb_callback_flags(9s)
198 for usb_cb_flags_t definitions.
199 --- Callback handling ---
201 All usb request types share the same callback handling. Please see
202 usb_callback_flags(9s) for a description of use and operation.
203
206 See attributes(5) for descriptions of the following attributes:
207 ┌─────────────────────────────┬─────────────────────────────┐
212 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
213 ├─────────────────────────────┼─────────────────────────────┤
214 │Architecture │PCI-based systems │
215 ├─────────────────────────────┼─────────────────────────────┤
216 │Interface stability │Committed │
217 ├─────────────────────────────┼─────────────────────────────┤
218 │Availability │SUNWusbu │
219 └─────────────────────────────┴─────────────────────────────┘
220
222 attributes(5), usb_alloc_request(9F), usb_get_current_frame_number(9F),
223 usb_get_max_pkts_per_isoc_request(9F), usb_pipe_bulk_xfer(9F),
224 usb_pipe_ctrl_xfer(9F), usb_pipe_intr_xfer(9F), usb_pipe_isoc_xfer(9F),
225 usb_bulk_request(9S), usb_callback_flags(9S), usb_completion_rea‐
226 son(9S), usb_ctrl_request(9S), usb_intr_request(9S),
227 usb_request_attributes(9S)
228SunOS 5.11 28 Dec 2006 usb_isoc_request(9S)