usr/src/man/man9f/usb_pipe_reset.9f

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USB_PIPE_RESET 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_pipe_reset \- Abort queued requests from a USB pipe and reset the pipe
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h>
  13
  14 \fBvoid\fR \fB\fR\fBusb_pipe_reset\fR(\fBdev_info_t *\fR\fIdip\fR,
  15      \fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_flags_t\fR \fIusb_flags\fR,
  16      \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIcb_pipe_handle\fR,
  17      \fBusb_opaque_t\fR \fIarg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR,
  18      \fBusb_opaque_t\fR \fIcallback_arg\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .LP
  23 Solaris DDI specific (Solaris DDI)
  24 .SH PARAMETERS
  25 .ne 2
  26 .na
  27 \fB\fIdip\fR\fR
  28 .ad
  29 .RS 16n
  30 Pointer to the device's \fBdev_info\fR structure.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIpipe_handle\fR\fR
  37 .ad
  38 .RS 16n
  39 Handle of the pipe to reset. Cannot be the handle to the default control pipe.
  40 .RE
  41
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIusb_flags\fR\fR
  46 .ad
  47 .RS 16n
  48 USB_FLAGS_SLEEP is the only flag recognized. Wait for completion.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fIcallback\fR\fR
  55 .ad
  56 .RS 16n
  57 Function called on completion if the USB_FLAGS_SLEEP flag is not specified. If
  58 NULL, no notification of completion is provided.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIcallback_arg\fR\fR
  65 .ad
  66 .RS 16n
  67 Second argument to callback function.
  68 .RE
  69
  70 .SH DESCRIPTION
  71 .LP
  72 Call \fBusb_pipe_reset()\fR to reset a pipe which is in an error state, or to
  73 abort a current request and clear the pipe. The \fBusb_pipe_reset()\fR function
  74 can be called on any pipe other than the default control pipe.
  75 .sp
  76 .LP
  77 A pipe can be reset automatically when requests sent to the pipe have the
  78 USB_ATTRS_AUTOCLEARING attribute specified. Client drivers see an exception
  79 callback with the USB_CB_STALL_CLEARED callback flag set in such cases.
  80 .sp
  81 .LP
  82 Stalls on pipes executing requests without the USB_ATTRS_AUTOCLEARING attribute
  83 set must be cleared by the client driver. The client driver is notified of the
  84 stall via an exception callback. The client driver must then call
  85 \fBusb_pipe_reset()\fR to clear the stall.
  86 .sp
  87 .LP
  88 The \fBusb_pipe_reset()\fR function resets a pipe as follows:
  89 .br
  90 .in +2
  91 1. Any polling activity is stopped if the pipe being reset is an interrupt or
  92 isochronous pipe.
  93 .in -2
  94 .br
  95 .in +2
  96 2. All pending requests are removed from the pipe. An exception callback, if
  97 specified beforehand, is executed for each aborted request.
  98 .in -2
  99 .br
 100 .in +2
 101 3. The pipe is reset to the idle state.
 102 .in -2
 103 .sp
 104 .LP
 105 Requests to reset the default control pipe are not allowed. No action is taken
 106 on a pipe which is closing.
 107 .sp
 108 .LP
 109 If USB_FLAGS_SLEEP is specified in \fIflags\fR, this function waits for the
 110 action to complete before calling the callback handler and returning. If not
 111 specified, this function queues the request and returns immediately, and the
 112 specified callback is called upon completion.
 113 .sp
 114 .LP
 115 \fIcallback\fR is the callback handler. It takes the following arguments:
 116 .sp
 117 .ne 2
 118 .na
 119 \fBusb_pipe_handle_t cb_pipe_handle\fR
 120 .ad
 121 .sp .6
 122 .RS 4n
 123 Handle of the pipe to reset.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fBusb_opaque_t callback_arg\fR
 130 .ad
 131 .sp .6
 132 .RS 4n
 133 Callback_arg specified to \fBusb_pipe_reset()\fR.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fBint rval\fR
 140 .ad
 141 .sp .6
 142 .RS 4n
 143 Return value of the reset call.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fBusb_cb_flags_t callback_flags\fR
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 Status of the queueing operation. Can be:
 154 .sp
 155 USB_CB_NO_INFO \(em Callback was uneventful.
 156 .sp
 157 USB_CB_ASYNC_REQ_FAILED \(em Error starting asynchronous request.
 158 .RE
 159
 160 .SH RETURN VALUES
 161 .LP
 162 Status is returned to the caller via the callback handler's rval argument.
 163 Possible callback hander rval argument values are:
 164 .sp
 165 .ne 2
 166 .na
 167 \fBUSB_SUCCESS\fR
 168 .ad
 169 .RS 23n
 170 Pipe successfully reset.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fBUSB_INVALID_PIPE\fR
 177 .ad
 178 .RS 23n
 179 \fIpipe_handle\fR specifies a pipe which is closed or closing.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fBUSB_INVALID_ARGS\fR
 186 .ad
 187 .RS 23n
 188 \fIdip\fR or \fIpipe_handle\fR arguments are \fBNULL\fR. USB_FLAGS_SLEEP is
 189 clear and callback is NULL.
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fBUSB_INVALID_CONTEXT\fR
 196 .ad
 197 .RS 23n
 198 Called from interrupt context with the USB_FLAGS_SLEEP flag set.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fBUSB_INVALID_PERM\fR
 205 .ad
 206 .RS 23n
 207 \fIpipe_handle\fR specifies the default control pipe.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fBUSB_FAILURE\fR
 214 .ad
 215 .RS 23n
 216 Asynchronous resources are unavailable. In this case, USB_CB_ASYNC_REQ_FAILED
 217 is passed in as the \fIcallback_flags\fR arg to the callback hander.
 218 .RE
 219
 220 .sp
 221 .LP
 222 Exception callback handlers of interrupt-IN and isochronous-IN requests which
 223 are terminated by these commands are called with a completion reason of
 224 USB_CR_STOPPED_POLLING.
 225 .sp
 226 .LP
 227 Exception handlers of incomplete bulk requests are called with a completion
 228 reason of USB_CR_FLUSHED.
 229 .sp
 230 .LP
 231 Exception handlers of unstarted requests are called with USB_CR_PIPE_RESET.
 232 .sp
 233 .LP
 234 Note that messages mirroring the above errors are logged to the console logfile
 235 on error. This provides status for calls which could not otherwise provide
 236 status.
 237 .SH CONTEXT
 238 .LP
 239 May be called from user or kernel context regardless of arguments. May be
 240 called from any callback with the USB_FLAGS_SLEEP clear. May not be called from
 241 a callback executing in interrupt context if the USB_FLAGS_SLEEP flag is set.
 242 .sp
 243 .LP
 244 If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if
 245 supplied, can block because it is executing in kernel context. Otherwise the
 246 callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more
 247 information on callbacks.
 248 .SH EXAMPLES
 249 .in +2
 250 .nf
 251 void post_reset_handler(
 252     usb_pipe_handle_t, usb_opaque_t, int, usb_cb_flags_t);
 253
 254 /*
 255  * Do an asynchronous reset on bulk_pipe.
 256  * Execute post_reset_handler when done.
 257  */
 258 usb_pipe_reset(dip, bulk_pipe, 0, post_reset_handler, arg);
 259
 260 /* Do a synchronous reset on bulk_pipe. */
 261 usb_pipe_reset(dip, bulk_pipe, USB_FLAGS_SLEEP, NULL, NULL);
 262
 263 .fi
 264 .in -2
 265
 266 .SH ATTRIBUTES
 267 .LP
 268 See \fBattributes\fR(5) for descriptions of the following attributes:
 269 .sp
 270
 271 .sp
 272 .TS
 273 box;
 274 c | c
 275 l | l .
 276 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 277 _
 278 Architecture    PCI-based systems
 279 _
 280 Interface stability     Committed
 281 .TE
 282
 283 .SH SEE ALSO
 284 .LP
 285 \fBattributes\fR(5), \fBusb_get_cfg\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
 286 \fBusb_pipe_close\fR(9F), \fBusb_get_status\fR(9F),
 287 \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_drain_reqs\fR(9F),
 288 \fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
 289 \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_xopen\fR(9F),
 290 \fBusb_pipe_stop_intr_polling\fR(9F), \fBusb_pipe_stop_isoc_polling\fR(9F),
 291 \fBusb_callback_flags\fR(9S)