Go to main content

man pages section 9: DDI and DKI Kernel Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

usb_pipe_bulk_free_streams(9F)

Name

usb_pipe_bulk_free_streams - Release streams resource

Synopsis

#include <sys/usb/usba.h>
int usb_pipe_bulk_free_streams(usb_pipe_handle_t *
pipe_handle, 
usb_flag_t usb_flags, void (*
callback) (usb_pipe_handle_t pipe_handle
, usb_opaque_t arg, 
int rval, usb_cb_flags_t
 flags), usb_opaque_t 
callback_arg);

Interface Level

Solaris DDI specific (Solaris DDI)

Parameters

pipe_handle

Pointer to a usb bulk pipe handle to release streams resource.

flags

USB_FLAGS_SLEEP is the only flag recognized. Set it to wait for resources, streams to become free, and for all pending request callbacks to complete.

callback

This function is called on completion if the USB_FLAGS_SLEEP flag is not specified. Mandatory if the USB_FLAGS_SLEEP flag has not been specified.

callback_arg

Second argument to callback function.

Description

The usb_pipe_bulk_free_streams() function releases streams resource on a USB bulk pipe. It is recommended that the function be called before usb_pipe_close(9F).

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

If USB_FLAGS_SLEEP is specified in flags, wait for all cleanup operations to complete before calling the callback handler and returning the value.

If USB_FLAGS_SLEEP 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.

The callback parameter is the callback handler and takes the following arguments:

usb_pipe_handle_t pipe_handle

Handle of the pipe to release streams resource.

usb_opaque_t callback_arg

Callback_arg specified to usb_pipe_bulk_free_streams ().

int rval

Return value of the streams release.

usb_cb_flags_t callback_flags

Status of the queueing operation can be one of the following:

USB_CB_NO_INFO

Callback was uneventful.

USB_CB_ASYNC_REQ_FAILED

Error starting asynchronous request.

Return Values

Status is returned to the caller via the callback handler's rval argument. The possible values for the callback handler rval argument are:

USB_INVALID_PIPE

Pipe handle specifies a pipe which is closed or closing.

USB_INVALID_CONTEXT

Called from interrupt context.

USB_INVALID_ARGS

pipe_handle arguments are NULL.

USB_FAILURE

Asynchronous resources are unavailable. In this case, USB_CB_ASYNC_REQ_FAILED is passed in as the callback_flags argument to the callback handler.

Exception handlers of any queued requests which were flushed are called with a completion reason of USB_CR_FLUSHED.

Context

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 usb_callback_flags(9S).

If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if supplied, can block because it is executing in kernel context. Otherwise, the callback cannot block. For more information about callbacks, see usb_callback_flags(9S).

Examples


/* 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);

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Architecture
PCI-based systems
Interface Stability
Committed
Availability
system/io/usb

See Also

attributes(7), usb_pipe_get_max_bulk_streams(9F), usb_pipe_bulk_alloc_streams(9F), usb_pipe_bulk_reset_stream(9F), usb_pipe_bulk_xfer(9F), usb_pipe_close(9F), usb_pipe_open(9F), usb_pipe_reset(9F), usb_bulk_request(9S), usb_callback_flags(9S), usb_request_attributes(9S)