1usb_pipe_close(9F) Kernel Functions for Drivers usb_pipe_close(9F)
2
3
4
6 usb_pipe_close - Close and cleanup a USB device pipe
7
9 #include <sys/usb/usba.h>
10
11
12
13 void usb_pipe_close(dev_info_t *dip, usb_pipe_handle_t pipe_handle,
14 usb_flags_t flags,
15 void (*callback)(usb_pipe_handle_t pipe_handle,
16 usb_opaque_t arg, int rval,
17 usb_cb_flags_t flags), usb_opaque_t callback_arg);
18
19
21 Solaris DDI specific (Solaris DDI)
22
24 dip Pointer to the device's dev_info structure.
25
26
27 pipe_handle Handle of pipe to close. Cannot be a handle to the
28 default control pipe.
29
30
31 flags USB_FLAGS_SLEEP is the only flag recognized. Set it to
32 wait for resources, for pipe to become free, and for
33 all pending request callbacks to complete.
34
35
36 callback This function is called on completion if the
37 USB_FLAGS_SLEEP flag is not specified. Mandatory if the
38 USB_FLAGS_SLEEP flag has not been specified.
39
40
41 callback_arg Second argument to callback function.
42
43
45 The usb_pipe_close() function closes the pipe pointed to by pipe_han‐
46 dle, releases all related resources and then frees the pipe handle.
47 This function stops polling if the pipe to be closed is an interrupt-IN
48 or isochronous-IN pipe. The default control pipe cannot be closed.
49
50
51 Pipe cleanup includes waiting for the all pending requests in the pipe
52 to finish, and then flushing residual requests remaining after waiting
53 for several seconds. Exception handlers of flushed requests are called
54 with a completion reason of USB_CR_FLUSHED.
55
56
57 If USB_FLAGS_SLEEP is specified in flags, wait for all cleanup opera‐
58 tions to complete before calling the callback handler and returning.
59
60
61 If USB_FLAGS_SLEEP is not specified in flags, an asynchronous close (to
62 be done in a separate thread) is requested. Return immediately. The
63 callback handler is called after all pending operations are completed.
64
65
66 The callback parameter is the callback handler and takes the following
67 arguments:
68
69 usb_pipe_handle_t pipe_handle
70
71 Handle of the pipe to close.
72
73
74 usb_opaque_t callback_arg
75
76 Callback_arg specified to usb_pipe_close().
77
78
79 int rval
80
81 Return value of close operation
82
83
84 usb_cb_flags_t callback_flags
85
86 Status of queueing operation. Can be:
87
88 USB_CB_NO_INFO Callback was uneventful.
89
90
91 USB_CB_ASYNC_REQ_FAILED Error starting asynchronous request.
92
93
94
96 Status is returned to the caller via the callback handler's rval argu‐
97 ment. Possible callback hander rval argument values are:
98
99 USB_INVALID_PIPE Pipe handle specifies a pipe which is closed or
100 closing.
101
102
103 USB_INVALID_ARGS dip or pipe_handle arguments are NULL.
104
105
106 USB_INVALID_CONTEXT Called from interrupt context.
107
108
109 USB_INVALID_PERM Pipe handle specifies the default control pipe.
110
111
112 USB_FAILURE Asynchronous resources are unavailable. In this
113 case, USB_CB_ASYNC_REQ_FAILED is passed in as
114 the callback_flags arg to the callback hander.
115
116
117
118 Exception handlers of any queued requests which were flushed are called
119 with a completion reason of USB_CR_FLUSHED. Exception handlers of peri‐
120 odic pipe requests which were terminated are called with
121 USB_CR_PIPE_CLOSING.
122
123
124 Note that messages mirroring the above errors are logged to the console
125 logfile on error. (This provides status for calls which otherwise could
126 provide status).
127
129 May be called from user or kernel context regardless of arguments. May
130 not be called from a callback executing in interrupt context.
131 Please see usb_callback_flags(9S) for more information on callbacks.
132
133
134 If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the
135 callback, if supplied, can block because it is executing in kernel con‐
136 text. Otherwise the callback cannot block. Please see usb_call‐
137 back_flags(9S) for more information on callbacks.
138
140 /* Synchronous close of pipe. */
141 usb_pipe_close(dip, pipe, USB_FLAGS_SLEEP, NULL, NULL);
142
143 --------
144
145 /* Template callback. */
146 void close_callback(usb_pipe_handle_t, usb_opaque_t, usb_cb_flags_t);
147
148 /* Asynchronous close of pipe. */
149 usb_pipe_close(dip, pipe, 0, close_callback, callback_arg);
150
151
152
154 See attributes(5) for descriptions of the following attributes:
155
156
157
158
159 ┌─────────────────────────────┬─────────────────────────────┐
160 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
161 ├─────────────────────────────┼─────────────────────────────┤
162 │Architecture │PCI-based systems │
163 ├─────────────────────────────┼─────────────────────────────┤
164 │Interface stability │Committed │
165 ├─────────────────────────────┼─────────────────────────────┤
166 │Availability │SUNWusb │
167 └─────────────────────────────┴─────────────────────────────┘
168
170 attributes(5), usb_get_status(9F), usb_pipe_drain_reqs(9F),
171 usb_pipe_get_state(9F), usb_pipe_open(9F), usb_pipe_reset(9F),
172 usb_callback_flags(9S)
173
174
175
176SunOS 5.11 5 Jan 2004 usb_pipe_close(9F)