usb_pipe_bulk_free_streams - man pages section 9: DDI and DKI Kernel Functions

Language:

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(5) for descriptions of the following attributes:

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

man pages section 9: DDI and DKI Kernel Functions