'\" te .\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. .TH usb_pipe_bulk_reset_stream 9F "05 February 2013" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME usb_pipe_bulk_reset_stream \- Abort queued requests from a USB stream and reset the stream .SH SYNOPSIS .LP .nf #include .fi .LP .nf \fBint usb_pipe_bulk_reset_stream(usb_pipe_handle_t *\fR\fIpipe_handle\fR, \fBuint16_t\fR \fIstream_id\fR, \fBusb_flag_t\fR \fIusb_flags\fR, \fBvoid (*\fR\fIcallback\fR)(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_opaque_t\fR \fIarg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags\fR, \fBusb_opaque_t\fR \fIcallback_arg\fR); .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI) .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIpipe_handle\fR\fR .ad .RS 16n .rt Bulk pipe to reset the stream. .RE .sp .ne 2 .mk .na \fB\fIstream_id\fR\fR .ad .RS 16n .rt The stream id. .RE .sp .ne 2 .mk .na \fB\fIflags\fR\fR .ad .RS 16n .rt \fBUSB_FLAG_SLEEP\fR is the only flag recognized. Wait for completion. .RE .sp .ne 2 .mk .na \fB\fIcallback\fR\fR .ad .RS 16n .rt Function called on completion if the \fBUSB_FLAGS_SLEEP\fR flag is not specified. If \fBNULL\fR, no notification of completion is provided. .RE .sp .ne 2 .mk .na \fB\fIcallback_arg\fR\fR .ad .RS 16n .rt Second argument to callback function. .RE .SH DESCRIPTION .sp .LP The \fBusb_pipe_bulk_reset_stream()\fR function is used to reset a single stream which is in an error state, or to abort a current request and clear the stream. This function can be only called on the bulk pipe. .sp .LP The \fBusb_pipe_bulk_reset_stream()\fR function resets a stream as follows: .RS +4 .TP 1. All pending requests are removed from the stream. An exception callback, if specified beforehand, is executed for each aborted request. .RE .RS +4 .TP 2. The stream is reset to the idle state. .RE .sp .LP If \fBUSB_FLAGS_SLEEP\fR is specified in flags, this function waits for the action to complete before calling the callback handler and returning the value. If not specified, this function queues the request and returns immediately, and the specified callback is called upon completion. .sp .LP \fBcallback\fR is the callback handler. It takes the following arguments: .sp .ne 2 .mk .na \fB\fBusb_pipe_handle_t cb_pipe_handle\fR\fR .ad .sp .6 .RS 4n Handle of the stream pipe to reset. .RE .sp .ne 2 .mk .na \fB\fBusb_opaque_t callback_arg\fR\fR .ad .sp .6 .RS 4n \fBCallback_arg\fR specified to \fBusb_pipe_bulk_reset_stream()\fR. .RE .sp .ne 2 .mk .na \fB\fBint rval\fR\fR .ad .sp .6 .RS 4n Return value of the reset call. .RE .sp .ne 2 .mk .na \fB\fBusb_cb_flags_t callback_flags\fR\fR .ad .sp .6 .RS 4n The status of the queueing operation can be one of the following value: .sp .ne 2 .mk .na \fB\fBUSB_CB_NO_INFO\fR\fR .ad .RS 27n .rt Callback was uneventful. .RE .sp .ne 2 .mk .na \fB\fBUSB_CB_ASYNC_REQ_FAILED\fR\fR .ad .RS 27n .rt Error starting asynchronous request. .RE .RE .SH RETURN VALUES .sp .LP Status is returned to the caller via the callback handler's \fBrval\fR argument. The possible values of the callback handler \fBrval\fR argument are as follows: .sp .ne 2 .mk .na \fB\fBUSB_SUCCESS\fR\fR .ad .RS 23n .rt Reset successful on a stream. .RE .sp .ne 2 .mk .na \fB\fBUSB_INVALID_PIPE\fR\fR .ad .RS 23n .rt \fBpipe_handle\fR specifies a pipe which is closing or closed. .RE .sp .ne 2 .mk .na \fB\fBUSB_INVALID_ARGS\fR\fR .ad .RS 23n .rt \fBpipe_handle\fR arguments are \fBNULL\fR. \fBUSB_FLAGS_SLEEP\fR is clear and callback is \fBNULL\fR. .RE .sp .ne 2 .mk .na \fB\fBUSB_INVALID_CONTEXT\fR\fR .ad .RS 23n .rt Called from the interrupt context with the \fBUSB_FLAGS_SLEEP\fR flag set. .RE .sp .ne 2 .mk .na \fB\fBUSB_FAILURE\fR\fR .ad .RS 23n .rt Asynchronous resources are unavailable. In this case, \fBUSB_CB_ASYNC_REQ_FAILED\fR is passed in as the \fBcallback_flags\fR argument to the callback handler. .RE .SH CONTEXT .sp .LP The allocation routines can always be called from kernel and user context regardless of arguments. The allocation routine may be called from any callback with the \fBUSB_FLAGS_SLEEP\fR flag is in clear state. They may not be called from a callback executing in interrupt context if the \fBUSB_FLAGS_SLEEP\fR flag is set. .sp .LP If the \fBUSB_CB_ASYNC_REQ_FAILED\fR bit is clear in \fBusb_cb_flags_t\fR, the callback, if supplied, can block because it is executing in kernel context. Otherwise, the callback cannot block. For more information about callbacks, see \fBusb_callback_flags\fR(9S). .SH EXAMPLES .sp .in +2 .nf /* Do a synchronous reset on a Stream. */ usb_pipe_bulk_reset_stream(pipe, USB_FLAGS_SLEEP, NULL, NULL); ------ /* Template callback. */ void reset_stream_callback(usb_pipe_handle_t, usb_opaque_t, usb_cb_flags_t); /* * Do an asynchronous reset on a Stream. * Execute reset_stream_callback when done. */ usb_pipe_bulk_reset_stream(pipe, 0, reset_stream_callback, callback_arg); .fi .in -2 .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ ArchitecturePCI-based systems _ Interface StabilityCommitted _ Availabilitysystem/io/usb .TE .SH SEE ALSO .sp .LP \fBattributes\fR(5), \fBusb_request_attributes\fR(9S), \fBusb_bulk_request\fR(9S), \fBusb_pipe_bulk_alloc_streams\fR(9F), \fBusb_pipe_bulk_free_streams\fR(9F), \fBusb_pipe_open\fR(9F), \fBusb_pipe_close\fR(9F), \fBusb_pipe_reset\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_get_max_bulk_streams\fR(9F), \fBusb_callback_flags\fR(9S)