'\" te .\" Copyright (c) 2009, 2013, Oracle and/or its affiliates. All rights reserved. .TH usb_pipe_bulk_free_streams 9F "05 February 2013" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME usb_pipe_bulk_free_streams \- Release streams resource .SH SYNOPSIS .LP .nf #include .fi .LP .nf \fBint usb_pipe_bulk_free_streams(usb_pipe_handle_t *\fR\fIpipe_handle\fR, \fBusb_flag_t usb_flags, void\fR (\fB*\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 Pointer to a usb bulk pipe handle to release streams resource. .RE .sp .ne 2 .mk .na \fB\fIflags\fR\fR .ad .RS 16n .rt \fBUSB_FLAGS_SLEEP\fR is the only flag recognized. Set it to wait for resources, streams to become free, and for all pending request callbacks to complete. .RE .sp .ne 2 .mk .na \fB\fIcallback\fR\fR .ad .RS 16n .rt This function is called on completion if the \fBUSB_FLAGS_SLEEP\fR flag is not specified. Mandatory if the \fBUSB_FLAGS_SLEEP\fR flag has not been specified. .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_free_streams()\fR function releases streams resource on a USB bulk pipe. It is recommended that the function be called before \fBusb_pipe_close\fR(9F). .sp .LP Streams cleanup include waiting for all pending requests in the streams pipe to finish, and then flushing residual requests remaining after waiting for several seconds. Exception handlers of flushed requests are called with a completion reason of \fBUSB_CR_FLUSHED\fR. .sp .LP If \fBUSB_FLAGS_SLEEP\fR is specified in flags, wait for all cleanup operations to complete before calling the callback handler and returning the value. .sp .LP If \fBUSB_FLAGS_SLEEP\fR is not specified in flags, an asynchronous release (to be done in a separate thread) is requested and returned immediately. The callback handler is called after all pending operations are completed. .sp .LP The callback parameter is the callback handler and takes the following arguments: .sp .ne 2 .mk .na \fB\fBusb_pipe_handle_t pipe_handle\fR\fR .ad .sp .6 .RS 4n Handle of the pipe to release streams resource. .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_free_streams()\fR. .RE .sp .ne 2 .mk .na \fB\fBint rval\fR\fR .ad .sp .6 .RS 4n Return value of the streams release. .RE .sp .ne 2 .mk .na \fB\fBusb_cb_flags_t callback_flags\fR\fR .ad .sp .6 .RS 4n Status of the queueing operation can be one of the following: .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 for the callback handler \fBrval\fR argument are: .sp .ne 2 .mk .na \fB\fBUSB_INVALID_PIPE\fR\fR .ad .RS 23n .rt Pipe handle specifies a pipe which is closed or closing. .RE .sp .ne 2 .mk .na \fB\fBUSB_INVALID_CONTEXT\fR\fR .ad .RS 23n .rt Called from interrupt context. .RE .sp .ne 2 .mk .na \fB\fBUSB_INVALID_ARGS\fR\fR .ad .RS 23n .rt \fBpipe_handle\fR arguments are \fBNULL\fR. .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 .sp .LP Exception handlers of any queued requests which were flushed are called with a completion reason of \fBUSB_CR_FLUSHED\fR. .SH CONTEXT .sp .LP The allocation routines can always be called from kernel and user context regardless of arguments. They may not be called from a callback function executing in interrupt context. For more information about callbacks, see \fBusb_callback_flags\fR(9S). .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 /* Synchronous release of streams. */ usb_pipe_bulk_free_streams(pipe, USB_FLAGS_SLEEP, NULL, NULL); ------ /* Template callback. */ void free_stream_callback(usb_pipe_handle_t, usb_opaque_t, usb_cb_flags_t); /* Asynchronous release of streams. */ usb_pipe_bulk_free_stream(pipe, 0, free_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_reset_stream\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)