usb_pipe_drain_reqs(9f)

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

NAME

6       usb_pipe_drain_reqs - Allow completion of pending pipe requests
7

SYNOPSIS

9       #include <sys/usb/usba.h>
10
11
12
13       int usb_pipe_drain_reqs(dev_info_t *dip, usb_pipe_handle_t pipe_handle,
14            uint_t timeout, usb_flags_t usb_flags,
15            void (*callback)(usb_pipe_handle_t pipe_handle,
16            usb_opaque_t callback_arg, int rval, usb_cb_flags_t flags),
17            usb_opaque_t callback_arg);
18
19

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI)
22

PARAMETERS

24       dip             Pointer to the device's dev_info structure.
25
26
27       pipe_handle     Handle of the pipe containing pending requests.
28
29
30       timeout         Maximum wait time for requests to drain. Must be a non-
31                       negative value in seconds. Zero specifies no timeout.
32
33
34       flags           USB_FLAGS_SLEEP is the only flag recognized.  Wait  for
35                       completion and do not call callback.
36
37
38       callback        Callback handler to notify of asynchronous completion.
39
40
41       callback_arg    Second argument passed to callback function.
42
43

DESCRIPTION

45       The  usb_pipe_drain_reqs() function provides waits for pending requests
46       to complete and then provides synchronous or asynchronous  notification
47       that all pending requests on a non-shared pipe indicated by pipe_handle
48       have completed. For a shared pipe (such as  the  default  control  pipe
49       used by multiple drivers each managing one interface of a device), this
50       function provides notification that all pending requests on  that  pipe
51       that are associated with a given dip are completed.
52
53
54       The usb_pipe_drain_reqs() function can be used to notify a close proce‐
55       dure when the default control pipe  is  clear  during  device  closure,
56       thereby  allowing  the  close procedure to continue safely. Normally, a
57       synchronous call to usb_pipe_close(9F) allows all requests in a pipe to
58       finish  before  returning.  However,  a  client driver cannot close the
59       default control pipe.
60
61
62       If USB_FLAGS_SLEEP is set in flags, block until  all  pending  requests
63       are completed. Otherwise, return immediately and call the callback han‐
64       dler when all pending requests are completed.
65
66
67       The callback parameter accepts the asynchronous callback handler, which
68       takes the following arguments:
69
70       usb_pipe_handle_t default_pipe_handle
71
72           Handle of the pipe to drain.
73
74
75       usb_opaque_t callback_arg
76
77           callback_arg specified to usb_pipe_drain_reqs().
78
79
80       int rval
81
82           Request status.
83
84
85       usb_cb_flags_t callback_flags
86
87           Status of the queueing operation. Can be:
88
89           USB_CB_NO_INFO             Callback was uneventful.
90
91
92           USB_CB_ASYNC_REQ_FAILED    Error starting asynchronous request.
93
94
95

RETURN VALUES

97       USB_SUCCESS            Request is successful.
98
99
100       USB_INVALID_ARGS       dip  argument  is NULL. USB_FLAGS_SLEEP is clear
101                              and callback is NULL.
102
103
104       USB_INVALID_CONTEXT    Called   from   callback   context   with    the
105                              USB_FLAGS_SLEEP flag set.
106
107
108       USB_INVALID_PIPE       Pipe is not open, is closing or is closed.
109
110

CONTEXT

112       May be called from user or kernel context.
113
114
115       If  the  USB_CB_ASYNC_REQ_FAILED  bit  is  clear in usb_cb_flags_t, the
116       callback, if supplied, can block because it is executing in kernel con‐
117       text.  Otherwise  the  callback  cannot  block.  Please  see  usb_call‐
118       back_flags(9S) for more information on callbacks.
119

EXAMPLES

121           mydev_detach(dev_info_t *dip, ddi_detach_cmd_t cmd)
122          {
123
124               ...
125               ...
126
127               mydev_state->pipe_state = CLOSED;
128
129               /* Wait for pending requests of a pipe to finish.  Don't timeout. */
130               (void) usb_pipe_drain_reqs(
131                   dip, pipe_handle, 0, USB_FLAGS_SLEEP, NULL, 0);
132
133               /*
134                * Dismantle streams and tear down this instance,
135                * now that all requests have been sent.
136                */
137               qprocsoff(q);
138               ...
139               ...
140               ddi_remove_minor_node(dip, NULL);
141               ...
142               ...
143          }
144
145
146

NOTES

148       For pipes other than the default control pipe,  it  is  recommended  to
149       close  the  pipe using a synchronous usb_pipe_close(). usb_pipe_close()
150       with the USB_FLAGS_SLEEP flag allows any pending requests in that  pipe
151       to complete before returning.
152
153
154       Do  not  call usb_pipe_drain_reqs() while additional requests are being
155       submitted by a different thread. This  action  can  stall  the  calling
156       thread of usb_pipe_drain_reqs() unnecessarily.
157

ATTRIBUTES

159       See attributes(5) for descriptions of the following attributes:
160
161
162
163
164       ┌─────────────────────────────┬─────────────────────────────┐
165       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
166       ├─────────────────────────────┼─────────────────────────────┤
167       │Architecture                 │PCI-based systems            │
168       ├─────────────────────────────┼─────────────────────────────┤
169       │Interface stability          │Committed                    │
170       ├─────────────────────────────┼─────────────────────────────┤
171       │Availability                 │SUNWusb                      │
172       └─────────────────────────────┴─────────────────────────────┘
173