usb_pipe_intr_xfer(9f)

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

NAME

6       usb_pipe_intr_xfer, usb_pipe_stop_intr_polling - USB interrupt transfer
7       and polling functions
8

SYNOPSIS

10       #include <sys/usb/usba.h>
11
12
13
14       int usb_pipe_intr_xfer(usb_pipe_handle_t pipe_handle, usb_intr_req_t *request,
15            usb_flags_t flags);
16
17
18       void usb_pipe_stop_intr_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_intr_xfer():
26
27       pipe_handle    Interrupt pipe handle on which request is made.
28
29
30       request        Pointer to interrupt transfer request.
31
32
33       flags          USB_FLAGS_SLEEP is the only flag  recognized.  Wait  for
34                      needed resources if unavailable. For requests specifying
35                      the USB_ATTRS_ONE_XFER attribute, wait for  the  request
36                      to complete.
37
38
39
40       For usb_pipe_stop_intr_polling():
41
42       pipe_handle    Interrupt pipe handle on which to stop polling for data.
43
44
45       flags          USB_FLAGS_SLEEP  is  the  only flag recognized. Wait for
46                      polling to stop.
47
48

DESCRIPTION

50       The usb_pipe_intr_xfer() function requests the USBA framework  to  per‐
51       form  a transfer through a USB interrupt pipe. The request is passed to
52       the host controller driver (HCD), which performs the necessary transac‐
53       tions to complete the request.
54
55
56       There  are  three categories of interrupt transfers: periodic or polled
57       interrupt-IN,  single-transfer  interrupt-IN,   and   (single-transfer)
58       interrupt-OUT.
59
60   Periodic Interrupt-IN Transfers
61       Periodic  or  polled  interrupt-IN  transfers execute on input requests
62       which do not have the USB_ATTRS_ONE_XFER  attribute  set.  One  request
63       enables  repetitive  transfers at a periodic rate set by the endpoint's
64       bInterval. There can be only one interrupt-IN request  submitted  at  a
65       time.
66
67
68       Periodic  interrupt-IN transfers are always asynchronous. Client driver
69       notification of new data is always via a callback. The  USB_FLAGS_SLEEP
70       flag  is only to wait for resources to become available. Callbacks must
71       always be in place to receive transfer completion notification.  Please
72       see usb_callback_flags(9S) for details on USB callbacks.
73
74
75       Calls  made  to  usb_pipe_intr_xfer()  for  starting input polling need
76       allocate only one request. The USBA framework allocates a  new  request
77       each  time  polling  has  new  data to return.  (Note that each request
78       returned must be freed via usb_free_intr_req(9F). Specify a zero length
79       when  calling  usb_alloc_intr_req()  to  allocate the original request,
80       since it will not be used to return data.   Set  the  intr_len  in  the
81       request to specify how much data can be returned per polling interval.
82
83
84       The  original  request passed to usb_pipe_intr_xfer() is used to return
85       status when polling is terminated, or on an error  condition  when  the
86       USB_ATTRS_AUTOCLEARING  attribute is set for the request. If autoclear‐
87       ing is not set, the  current  (non-original)  request  is  returned  on
88       error. Call usb_pipe_reset(9F) to reset the pipe and get back the orig‐
89       inal request in this case. The USB_CR_STOPPED_POLLING  flag  is  always
90       set for callbacks where the original request is returned.
91
92   Single-transfer Interrupt-IN Transfers
93       Interrupt-IN  requests which have the USB_ATTRS_ONE_XFER attribute per‐
94       form  a  single  transfer.  Such  requests  are  synchronous  when  the
95       USB_FLAGS_SLEEP  flag  is  specified. Calls for synchronous requests do
96       not return until their transaction is complete, and their callbacks are
97       optional.  The  request is returned to the client through the normal or
98       the exception completion callback to signal either normal completion or
99       an error condition.
100
101   Interrupt-OUT Transfers
102       Interrupt-OUT  requests  always  set up for a single transfer. However,
103       multiple requests can be queued and execute in periodic  fashion  until
104       depleted.
105
106
107       Interrupt-OUT  transfers  are synchronous when the USB_FLAGS_SLEEP flag
108       is set in the request's flags. Calls for synchronous transfers will not
109       return  until  their  transaction has completed. Calls for asynchronous
110       transfers notify the client driver of transaction completion via a nor‐
111       mal callback, or error completion via an exception callback.
112
113
114       The  usb_pipe_stop_intr_polling() function terminates polling on inter‐
115       rupt-IN pipes and does the following:
116         1. Cease polling.
117         2. Allow any requests-in-progress to complete and be returned to  the
118         client driver through the normal callback mechanism.
119         3. Idle the pipe.
120         4.  Return  the original polling request to the client driver through
121         an   exception    callback    with    a    completion    reason    of
122         USB_CR_STOPPED_POLLING.
123
124
125       The  client  driver may restart polling from an exception callback only
126       if the callback corresponds to an original request. The  callback  han‐
127       dler checks for the following completion reasons to ensure that a call‐
128       back corresponds to an original request:
129
130                 USB_CR_STOPPED_POLLING,
131                 USB_CR_PIPE_RESET,
132                 USB_CR_PIPE_CLOSING,
133                 USB_CR_NOT_SUPPORTED
134
135
136
137       The callback handler also checks the request's intr_data field to  mark
138       original  polling  requests,  when the requests are created with a zero
139       len argument. In this case, a  NULL  intr_data  field  distinguishes  a
140       returned  original  request  from  a request allocated by the framework
141       during polling.
142
143
144       Mblks for data for interrupt-OUT requests are allocated when a  request
145       is allocated via usb_alloc_intr_req(9F) by passing a non-negative value
146       for the len argument.
147

RETURN VALUES

149       For usb_pipe_intr_xfer()
150
151       USB_SUCCESS              Transfer was successful.
152
153
154       USB_INVALID_ARGS         Request is NULL.
155
156
157       USB_INVALID_CONTEXT      Called  from  interrupt   context   with   the
158                                USB_FLAGS_SLEEP flag set.
159
160
161       USB_INVALID_REQUEST      The request has been freed or otherwise inval‐
162                                idated.
163
164                                A set of conflicting attributes was specified.
165                                See usb_intr_request(9S).
166
167                                The  normal  and/or   exception  callback  was
168                                NULL,  USB_FLAGS_SLEEP   was   not   set   and
169                                USB_ATTRS_ONE_XFER was not set.
170
171                                An  interrupt  request  was   specified with a
172                                NULL data and a non-zero intr_len value.
173
174                                An IN interrupt  request  was  specified  with
175                                both  polling  (USB_ATTRS_ONE_XFER   clear  in
176                                attributes) and non-zero timeout specified.
177
178                                An IN interrupt request was specified  with  a
179                                non-NULL data argument.
180
181                                An  OUT interrupt request was specified with a
182                                NULL data argument.
183
184
185       USB_INVALID_PIPE         Pipe handle is NULL or invalid.
186
187                                Pipe is closing or closed.
188
189
190       USB_PIPE_ERROR           Pipe handle refers to a pipe which is  in  the
191                                USB_PIPE_STATE_ERROR state.
192
193
194       USB_NO_RESOURCES         Memory,   descriptors   or   other   resources
195                                unavailable.
196
197
198       USB_HC_HARDWARE_ERROR    Host controller is in error state.
199
200
201       USB_FAILURE              An asynchronous transfer failed or an internal
202                                error occurred.
203
204                                An  intr polling request is made while polling
205                                is already in progress.
206
207                                The pipe is in  an  unsuitable  state  (error,
208                                busy, not ready).
209
210                                Additional status information may be available
211                                in     the     intr_completion_reason      and
212                                intr_cb_flags  fields  of  the request. Please
213                                see  usb_completion_reason(9S)  and  usb_call‐
214                                back_flags(9S) for more information.
215
216
217
218       For usb_pipe_stop_intr_polling()
219
220
221       None, but fails if called with USB_FLAGS_SLEEP specified from interrupt
222       context, pipe handle is invalid, NULL  or  pertains  to  a  closing  or
223       closed  pipe,  or  the  pipe  is  in an error state. Error messages are
224       logged to the console logfile.
225
226
227       Exception handlers' queued requests which are flushed by these commands
228       before execution are returned with completion reason of USB_CR_FLUSHED.
229

CONTEXT

231       Both of these functions can be called from kernel or user context with‐
232       out regard to arguments, and may be called from interrupt context  only
233       when the USB_FLAGS_SLEEP flag is clear.
234

EXAMPLES

236          /* Start polling on interrupt-IN pipe. */
237
238          usb_intr_req_t intr_req;
239          void intr_pipe_callback(usb_pipe_handle_t, usb_intr_req_t*);
240          void intr_pipe_exception_callback(
241              usb_pipe_handle_t, usb_intr_req_t*);
242          usb_ep_descr_t *ep_descr;
243
244          ep_descr = ...;
245          intr_req = usb_alloc_intr_req(dip, 0, USB_FLAGS_SLEEP);
246          ...
247          ...
248          intr_req->intr_attributes   = USB_ATTRS_SHORT_XFER_OK;
249          intr_req->intr_len          = ep_descr->wMaxPacketSize;
250          ...
251          ...
252          intr_req->intr_cb           = intr_pipe_callback;
253          intr_req->intr_exc_cb       = intr_pipe_exception_callback;
254
255          if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_NOSLEEP))
256              != USB_SUCCESS) {
257                cmn_err (CE_WARN, "%s%d: Error starting interrupt pipe polling.",
258                    ddi_driver_name(dip), ddi_get_instance(dip));
259          }
260
261          -------
262
263          /* Stop polling before setting device idle.  Wait for polling to stop. */
264
265          usb_pipe_stop_intr_polling(pipe, USB_FLAGS_SLEEP);
266          (void) pm_idle_component(dip, 0);
267
268          -------
269
270          /* Allocate, initialize and issue a synchronous intr-OUT request. */
271
272          usb_intr_req_t intr_req;
273          mblk_t *mblk;
274          usb_ep_descr_t *ep_descr;
275
276          ep_descr = ...;
277
278          intr_req =
279            usb_alloc_intr_req(dip, ep_descr->wMaxPacketSize, USB_FLAGS_SLEEP);
280
281          intr_req->intr_attributes   = USB_ATTRS_AUTOCLEARING;
282          mblk = intr_req->intr_data;
283          bcopy(buffer, mblk->b_wptr, ep_descr->wMaxPacketSize);
284          mblk->b_wptr += ep_descr->wMaxPacketSize;
285
286          if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_SLEEP))
287              != USB_SUCCESS) {
288                  cmn_err (CE_WARN, "%s%d: Error writing intr data.",
289                      ddi_driver_name(dip), ddi_get_instance(dip));
290          }
291
292
293

ATTRIBUTES

295       See attributes(5) for descriptions of the following attributes:
296
297
298
299
300       ┌─────────────────────────────┬─────────────────────────────┐
301       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
302       ├─────────────────────────────┼─────────────────────────────┤
303       │Architecture                 │PCI-based systems            │
304       ├─────────────────────────────┼─────────────────────────────┤
305       │Interface stability          │Evolving                     │
306       ├─────────────────────────────┼─────────────────────────────┤
307       │Availability                 │SUNWusb                      │
308       └─────────────────────────────┴─────────────────────────────┘
309