| blob | 7de6946a77471ea88b19159f85be108b12ade124 |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2016 Joyent, Inc.
13 .\"
14 .Dd Dec 22, 2016
15 .Dt USBA_HCDI_PIPE_ISOC_XFER 9E
16 .Os
17 .Sh NAME
18 .Nm usba_hcdi_pipe_isoc_xfer
19 .Nd perform a USB isochronous transfer
20 .Sh SYNOPSIS
21 .In sys/usb/usba/hcdi.h
22 .Ft int
23 .Fo prefix_hcdi_pipe_isoc_xfer
24 .Fa "usba_pipe_handle_data_t *ph"
25 .Fa "usb_isoc_req_t *usrp"
26 .Fa "usb_flags_t usb_flags"
27 .Fc
28 .Sh INTERFACE LEVEL
29 .Sy Volatile -
30 illumos USB HCD private function
31 .Pp
32 This is a private function that is not part of the stable DDI. It may be
33 removed or changed at any time.
34 .Sh PARAMETERS
35 .Bl -tag -width Fa
36 .It Fa ph
37 A pointer to a USB pipe handle as defined in
38 .Xr usba_pipe_handle_data 9S .
39 .It Fa usrp
40 A pointer to a USB isochronous transfer request. The structure's members
41 are documented in
42 .Xr usb_isoc_req 9S .
43 .It Fa usb_flags
44 Flags which describe how allocations should be performed. Valid flags
45 are:
46 .Bl -tag -width Sy
47 .It Sy USB_FLAGS_NOSLEEP
48 Do not block waiting for memory. If memory is not available the allocation
49 will fail.
50 .It Sy USB_FLAGS_SLEEP
51 Perform a blocking allocation. If memory is not available, the function
52 will wait until memory is made available.
53 .Pp
54 Note, the request may still fail even if
55 .Sy USB_FLAGS_SLEEP
56 is specified.
57 .El
58 .El
59 .Sh DESCRIPTION
60 The
61 .Fn usba_hcdi_pipe_isoc_xfer
62 entry point is used to initiate an
63 .Em asynchronous
64 USB isochronous transfer on the pipe
65 .Fa ph .
66 The specific USB interrupt transfer is provided in
67 .Fa uirp .
68 For more background on transfer types, see
69 .Xr usba_hcdi 9E .
70 .Pp
71 The host controller driver should first check the USB address of the
72 pipe handle. It may correspond to the root hub. If it does, the driver
73 should return
74 .Sy USB_NOT_SUPPORTED .
75 .Pp
76 Isochronous transfers happen once a period. Isochronous transfers may
77 just be told to start as son as possible or to line up to a specific
78 frame. At this time, nothing in the system uses the later behavior. It
79 is reasonable for a new driver to require that the
80 .Sy USB_ATTRS_ISOC_XFER_ASAP
81 flag be set in the
82 .Sy isoc_attributes
83 member of the
84 .Fa usrp
85 argument. In the case where it's not set and the controller driver does
86 not support setting the frame, it should return
87 .Sy USB_NOT_SUPPORTED .
88 .Pp
89 Isochronous-IN transfers are
90 .Em always periodic .
91 Isochronous-OUT transfers are one shot transfers. Periodic transfers
92 have slightly different handling and behavior.
93 .Pp
94 Isochronous transfers may send data to the device or receive data from
95 the device. A given isochronous endpoint is uni-directional. The
96 direction can be determined from the endpoint address based on the
97 .Sy p_ep
98 member of
99 .Fa ubrp .
100 See
101 .Xr usb_ep_descr 9S
102 for more information on how to determine the direction of the endpoint.
103 .Pp
104 Isochronous transfers are a little bit different from other transfers.
105 While there is still a single
106 .Xr mblk 9S
107 structure that all the data goes to or from, the transfer may be broken
108 up into multiple packets. All of these packets make up a single transfer
109 request and each one represents the data that is transferred during a
110 single portion of a frame. For the description of them, see
111 .Xr usb_isoc_req 9S .
112 Because of these data structures, the way that transfers are recorded is
113 different and will be discussed later on.
114 .Pp
115 The device driver should allocate memory, whether memory suitable for a
116 DMA transfer or otherwise, to perform the transfer. For all memory
117 allocated, it should honor the values in
118 .Fa usb_flags
119 to determine whether or not it should block for allocations.
120 .Pp
121 For isochronous-out transfers which are one-shot transfers, the driver
122 should verify that the sum of all of the individual packet counts
123 matches the message block length of the data. If it does not, then the
124 driver should return
125 .Sy USB_INVALID_ARGS .
126 .Pp
127 If the driver successfully schedules the I/O, then it should return
128 .Sy USB_SUCCESS .
129 When the I/O completes, it must call
130 .Xr usba_hcdi_cb 9F
131 with
132 .Fa usrp .
133 If the transfer fails, but the driver returned
134 .Sy USB_SUCCESS ,
135 it still must call
136 .Xr usba_hcdi_cb 9F
137 and should specify an error there.
138 .Pp
139 The driver is responsible for timing out all one-shot outgoing requests.
140 As there is no timeout member in the isochronous request structure, then
141 the timeout should be set to
142 .Sy HCDI_DEFAULT_TIMEOUT .
143 .Ss Periodic Transfers
144 All isochronous-in transfers are periodic transfers. Once a periodic
145 transfer is initiated, every time data is received the driver should
146 call the
147 .Xr usba_hcdi_cb 9F
148 function with updated data.
149 .Pp
150 When a periodic transfer is initiated, many controller drivers will
151 allocate multiple transfers up front and schedule them all. Many drivers
152 do this to ensure that data isn't lost between servicing the first
153 transfer and scheduling the next. The number of such transfers used
154 depends on the polling frequency specified in the endpoint descriptor.
155 .Pp
156 Unless an error occurs, the driver must not use the original isochronous
157 request,
158 .Fa usrp .
159 Instead, it should duplicate the request through the
160 .Xr usba_hcdi_dup_isoc_req 9F
161 function before calling
162 .Xr usba_hcdi_cb 9F .
163 .Pp
164 The driver should return the original transfer in one of the following
165 conditions:
166 .Bl -bullet
167 .It
168 A pipe reset request came in from the
169 .Xr usba_hcdi_pipe_rest 9E
170 entry point.
171 .It
172 A request to stop polling came in from the
173 .Xr usba_hcdi_pipe_stop_isoc_polling 9E
174 entry point.
175 .It
176 A request to close the pipe came in from the
177 .Xr usba_hcdi_pipe_close 9E
178 entry point.
179 .It
180 An out of memory condition occurred. The caller should call
181 .Xr usba_hcdi_cb 9F
182 with the code
183 .Sy USB_CR_NO_RESOURCES .
184 .It
185 Some other transfer error occurred.
186 .El
187 .Ss Callback Handling
188 When the isochronous transfer completes, the driver should consider the
189 following items to determine what actions it should take on the
190 callback:
191 .Sy USB_SUCCESS .
192 Otherwise, it should return the appropriate USB error. If uncertain, use
193 .Sy USB_FAILURE .
194 .Bl -bullet
195 .It
196 If the transfer timed out, it should remove the transfer from the
197 outstanding list, queue the next transfer, and return the transfer back
198 to the OS with the error code
199 .Sy USB_CR_TIMEOUT
200 with
201 .Xr usba_hcdi_cb 9F .
202 .It
203 If the transfer failed, it should find the appropriate error and call
204 .Xr usba_hcdi_cb 9F
205 with that error.
206 .It
207 If the transfer succeeded, but less data was transferred than expected,
208 consult the
209 .Sy isoc_attributes
210 member of the
211 .Fa usrp .
212 If the
213 .Sy USB_ATTRS_SHORT_XFER_OK
214 flag is not present, then the driver should call
215 .Xr usba_hcdi_cb 9F
216 with the error
217 .Sy USB_CR_DATA_UNDERRUN .
218 .It
219 If the transfer was going to the host, then the driver should copy the
220 data into the transfer's message block and update the
221 .Sy b_wptr
222 member of the
223 .Xr mblk 9S .
224 .It
225 The driver should update the
226 .Sy isoc_pkt_actual_length
227 member of the
228 .Sy isoc_pkt_descr
229 array of the
230 .Xr usb_isoc_req 9S
231 structure with the actual transfer amounts.
232 .It
233 If everything was successful, call
234 .Xr usba_hcdi_cb 9F
235 with the code
236 .Sy USB_CR_OK .
237 .It
238 If this was a periodic transfer, it should reschedule the transfer.
239 .El
240 .Sh RETURN VALUES
241 Upon successful completion, the
242 .Fn usba_hcdi_pipe_isoc_xfer
243 function should return
244 function should return
245 .Sy USB_SUCCESS .
246 Otherwise, it should return the appropriate USB error. If uncertain, use
247 .Sy USB_FAILURE .
248 .Sh SEE ALSO
249 .Xr usba_hcdi 9E ,
250 .Xr usba_hcdi_pipe_close 9E ,
251 .Xr usba_hcdi_pipe_rest 9E ,
252 .Xr usba_hcdi_pipe_stop_isoc_polling 9E ,
253 .Xr usba_hcdi_cb 9F ,
254 .Xr usba_hcdi_dup_isoc_req 9F ,
255 .Xr mblk 9S ,
256 .Xr usb_ep_descr 9S ,
257 .Xr usb_isoc_req 9S ,
258 .Xr usba_pipe_handle_data 9S