usb_pipe_stop_isoc_polling(9f)

1usb_pipe_isoc_xfer(9F)   Kernel Functions for Drivers   usb_pipe_isoc_xfer(9F)
2
3
4

NAME

6       usb_pipe_isoc_xfer, usb_pipe_stop_isoc_polling - USB isochronous trans‐
7       fer and polling functions
8

SYNOPSIS

10       #include <sys/usb/usba.h>
11
12
13
14       int usb_pipe_isoc_xfer(usb_pipe_handle_t pipe_handle, usb_isoc_req_t *request,
15            usb_flags_t flags);
16
17
18       void usb_pipe_stop_isoc_polling(usb_pipe_handle_t pipe_handle, usb__flags_t flags);
19
20

INTERFACE LEVEL

22       Solaris DDI specific (Solaris DDI)
23

PARAMETERS

25       For usb_pipe_isoc_xfer():
26
27       pipe_handle    Isochronous pipe handle on which request is made.
28
29
30       request        Pointer to isochronous transfer request.
31
32
33       flags          USB_FLAGS_SLEEP is the only flag  recognized.  Wait  for
34                      needed resources if unavailable.
35
36
37
38       For usb_pipe_stop_isoc_polling():
39
40       pipe_handle    Isochronous  pipe  handle  on  which to stop polling for
41                      input.
42
43
44       flags          USB_FLAGS_SLEEP is the only flag  recognized.  Wait  for
45                      polling to stop.
46
47

DESCRIPTION

49       The  usb_pipe_isoc_xfer()  function requests the USBA framework to per‐
50       form a transfer     through a USB  isochronous  pipe.  The  request  is
51       passed  to  the host controller driver (HCD), which performs the neces‐
52       sary transactions to complete the request.
53
54
55       By their nature, isochronous transfers require several transactions for
56       completion.  Each  request  may  contain  several  packet  descriptors.
57       Descriptors correspond to subtransfers to be made in different  frames.
58       A  request  is  deemed  completed once all packets of that request have
59       been processed.   It  is  illegal  to  specify  the  USB_ATTRS_ONE_XFER
60       attribute  in an isochronous request.  The isochronous polling interval
61       is always one millisecond, the period of a full-speed frame.
62
63
64       All isochronous requests are asynchronous, and will notify  the  caller
65       of      their  completion  via  a  callback  function.  All isochronous
66       requests must specify normal and exception callback handlers.
67
68
69       Requests   will   wait   for   needed,   unavailable   resources   when
70       USB_FLAGS_SLEEP  has  been  specified  in flags.  Requests made without
71       USB_FLAGS_SLEEP set will fail  if  needed  resources  are  not  readily
72       available.
73
74
75       No  errors seen during request processing will result in aborted trans‐
76       fers or exception callbacks. Such errors will instead be logged in  the
77       packet descriptor's isoc_pkt_status field. These errors can be examined
78       when the completed request is returned through a normal callback.
79
80   Isochronous-OUT TRANSFERS
81       Allocate room for data when  allocating  isochronous-OUT  requests  via
82       usb_alloc_isoc_req(9F),  by  passing  a  positive value for     the len
83       argument. The data will be divided among the request transactions, each
84       transaction    represented    by    a    packet    descriptor.     (See
85       usb_isoc_request(9F). When all of the data has been sent, regardless of
86       any  errors encountered, a normal transfer callback will be     made to
87       notify the client driver of completion.
88
89
90       If a request is submitted while other requests are  active  or  queued,
91       and the new request has its USB_ATTRS_ISOC_XFER_ASAP attribute set, the
92       host controller driver will queue the request to start on a frame which
93       immediately follows the last frame of the last queued request.
94
95   Isochronous-IN TRANSFERS
96       All isochronous-IN transfers start background polling, and require only
97       a single (original) request.  The USBA framework will  allocate  a  new
98       request each time polling has new data to return. Specify a zero length
99       when calling usb_alloc_isoc_req() to  allocate  the  original  request,
100       since  it will not be used to return data.  Set the isoc_pkts_length in
101       the request to specify how much data to poll per interval  (the  length
102       of one packet in the request).
103
104
105       The  original  request  passed  to usb_pipe_isoc_xfer() will be used to
106       return status when polling termination is requested, or for error  con‐
107       dition  notification. There can be only one isochronous-IN request sub‐
108       mitted at a time.
109
110   CALLBACKS
111       Isochronous transfer normal-completion callbacks cannot block  for  any
112       reason  since  they  are called from interrupt context.  They will have
113       USB_CB_INTR_CONTEXT set in their callback flags to note this.
114
115
116       Isochronous exception callbacks have  the  following  restrictions  for
117       blocking:
118
119           1.     They  can  block for resources (for example to allocate mem‐
120                  ory).
121
122           2.     They cannot block for synchronous completion  of  a  command
123                  (for  example  usb_pipe_close(9F))  done  on  the same pipe.
124                  Asynchronous commands can be started, when the pipe's policy
125                  pp_max_async_reqs field is initialized to accommodate them.
126
127           3.     They cannot block waiting for another callback to complete.
128
129           4.
130                   They  cannot  block  waiting  for  a  synchronous  transfer
131                  request to complete.  They can, however, make  an  asynchro‐
132                  nous   request  (such  as  restarting  polling  with  a  new
133                  isochronous-IN transfer).
134
135
136       Please see the section on callbacks in usb_callback_flags(9S) for  more
137       information.
138
139
140       All  isochronous  transfer exception callbacks signify that polling has
141       stopped.  Polling requests are returned with the  following  completion
142       reasons:
143
144                 USB_CR_STOPPED_POLLING
145                 USB_CR_PIPE_CLOSING
146
147
148
149       Note: There are no exception callbacks for error conditions.
150
151
152       The  usb_pipe_stop_isoc_polling()  function  terminates  polling  on an
153       isochronous-IN pipe. The usb_pipe_stop_isoc_polling() function does the
154       following:
155
156           1.     Cease polling.
157
158           2.     Allow  any  requests-in-progress to complete and be returned
159                  to the client driver through the normal callback mechanism.
160
161           3.     Idle the pipe.
162
163           4.     Return the original polling request  to  the  client  driver
164                  through  an  exception  callback with a completion reason of
165                  USB_CR_STOPPED_POLLING.
166

RETURN VALUES

168       For usb_pipe_isoc_xfer():
169
170       USB_SUCCESS                Transfer was successful.
171
172
173       USB_INVALID_ARGS           Request is NULL.
174
175
176       USB_INVALID_CONTEXT        Called  from  interrupt  context  with   the
177                                  USB_FLAGS_SLEEP flag set.
178
179
180       USB_INVALID_REQUEST        The  request  has  been  freed  or otherwise
181                                  invalidated.
182
183                                  A set of conflicting  attributes were speci‐
184                                  fied. See usb_isoc_request(9S).
185
186                                  The  normal    and/or exception callback was
187                                  NULL,  USB_FLAGS_SLEEP   was   not  set  and
188                                  USB_ATTRS_ONE_XFER was not set.
189
190                                  An  isochronous request was specified with a
191                                  zeroed      isoc_pkt_descr,      a      NULL
192                                  isoc_pkt_descr, or a NULL data argument.
193
194                                  An  isochronous  request  was specified with
195                                  USB_ATTRS_ISOC_XFER_ASAP   and   a   nonzero
196                                  isoc_frame_no.
197
198
199       USB_NO_FRAME_NUMBER        An  isochronous  request  was  not specified
200                                  with    one    and     only     one       of
201                                  USB_ATTRS_ISOC_START_FRAME                or
202                                  USB_ATTRS_ISOC_XFER_ASAP specified.
203
204                                  An  isochronous request was  specified  with
205                                  USB_ATTRS_ISOC_START_FRAME    and   a   zero
206                                  isoc_frame_no.
207
208
209       USB_INVALID_START_FRAME    An isochronous request was specified with an
210                                  invalid  starting  frame  number  (less than
211                                  current   frame   number,   or   zero)   and
212                                  USB_ATTRS_ISOC_START_FRAME specified.
213
214
215       USB_INVALID_PIPE           Pipe handle is NULL or invalid.
216
217                                   Pipe is closing or closed.
218
219
220       USB_PIPE_ERROR             Pipe   handle  refers  to a pipe which is in
221                                  the USB_PIPE_STATE_ERROR state.
222
223
224       USB_NO_RESOURCES           Memory,  descriptors  or   other   resources
225                                  unavailable.
226
227
228       USB_HC_HARDWARE_ERROR      Host controller is in error state.
229
230
231       USB_FAILURE                An asynchronous transfer failed or an inter‐
232                                  nal error occurred.
233
234                                    An isoch request requested too much data:
235                                        (length   >  (usb_get_max_pkts_per_isoc_request()  *
236                                         endpoint's  wMaxPacketSize))
237
238                                  The pipe is in an unsuitable  state  (error,
239                                  busy, not ready).
240
241
242
243       Additional  status  information  may  be  available in the isoc_comple‐
244       tion_reason  and  isoc_cb_flags  fields  of  the  request.  Please  see
245       usb_completion_reason(9S)  and usb_callback_flags(9S) for more informa‐
246       tion.
247
248
249       For usb_pipe_stop_isoc_polling():
250
251
252       None, but will fail  if  called  with  USB_FLAGS_SLEEP  specified  from
253       interrupt  context;  the  pipe handle is invalid, NULL or pertains to a
254       closing or closed pipe; or the pipe is  in  an  error  state.  Messages
255       regarding these errors will be logged to the console logfile.
256

CONTEXT

258       Both of these functions may be called from kernel or user context with‐
259       out regard to arguments. May be called from interrupt context only when
260       the USB_FLAGS_SLEEP flag is clear.
261

EXAMPLES

263         /* Start polling on an isochronous-IN pipe. */
264
265             usb_isoc_req_t isoc_req;
266             void isoc_pipe_callback(usb_pipe_handle_t, usb_isoc_req_t*);
267             void isoc_pipe_exception_callback(
268                 usb_pipe_handle_t, usb_isoc_req_t*);
269             uint_t pkt_size;
270             usb_ep_data_t *isoc_ep_tree_node;
271             usb_ep_descr_t *isoc_ep_descr = ...;   /* From usb_lookup_ep_data() */
272
273             isoc_ep_descr = &isoc_ep_tree_node->ep_descr;
274             pkt_size = isoc_ep_descr->wMaxPacketSize;
275
276             isoc_req = usb_alloc_isoc_req(
277                 dip, num_pkts, NUM_PKTS * pkt_size, USB_FLAGS_SLEEP);
278             ...
279             ...
280             isoc_req->isoc_attributes = USB_ATTRS_ISOC_XFER_ASAP;
281             ...
282             ...
283             isoc_req->isoc_cb         = isoc_pipe_callback;
284             isoc_req->isoc_exc_cb     = isoc_pipe_exception_callback;
285             ...
286             ...
287             isoc_req->isoc_pkts_length  = pkt_size;
288             isoc_req->isoc_pkts_count   = NUM_PKTS;
289             for (pkt = 0; pkt < NUM_PKTS; pkt++) {
290                     isoc_req->isoc_pkt_descr[pkt].isoc_pkt_length = pkt_size;
291             }
292
293             if ((rval = usb_pipe_isoc_xfer(pipe, isoc_req, USB_FLAGS_NOSLEEP))
294                 != USB_SUCCESS) {
295                     cmn_err (CE_WARN,"%s%d: Error starting isochronous pipe polling.",
296                         ddi_driver_name(dip), ddi_get_instance(dip));
297             }
298
299             -------
300
301             /* Stop polling before powering off device. Wait for polling to stop. */
302
303             usb_pipe_stop_isoc_polling(pipe, USB_FLAGS_SLEEP);
304             pm_idle_component(dip, 0);
305
306
307

ATTRIBUTES

309       See attributes(5) for descriptions of the following attributes:
310
311
312
313
314       ┌─────────────────────────────┬─────────────────────────────┐
315       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
316       ├─────────────────────────────┼─────────────────────────────┤
317       │Architecture                 │PCI-based systems            │
318       ├─────────────────────────────┼─────────────────────────────┤
319       │Interface stability          │Evolving                     │
320       ├─────────────────────────────┼─────────────────────────────┤
321       │Availability                 │SUNWusb                      │
322       └─────────────────────────────┴─────────────────────────────┘
323