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

NAME

6       usb_pipe_close - Close and cleanup a USB device pipe
7

SYNOPSIS

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

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  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

DESCRIPTION

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

RETURN VALUES

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

CONTEXT

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

EXAMPLES

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

ATTRIBUTES

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

SEE ALSO

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)
Impressum