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

Language:

usb_pipe_bulk_reset_stream(9F)

Name

usb_pipe_bulk_reset_stream - Abort queued requests from a USB stream and reset the stream

Synopsis

#include <sys/usb/usba.h>

int usb_pipe_bulk_reset_stream(usb_pipe_handle_t *
pipe_handle,
uint16_t stream_id, 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: Bulk pipe to reset the stream.
stream_id: The stream id.
flags: USB_FLAG_SLEEP is the only flag recognized. Wait for completion.
callback: Function called on completion if the USB_FLAGS_SLEEP flag is not specified. If NULL, no notification of completion is provided.
callback_arg: Second argument to callback function.

Description

The usb_pipe_bulk_reset_stream() 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.

The usb_pipe_bulk_reset_stream() function resets a stream as follows:

All pending requests are removed from the stream. An exception callback, if specified beforehand, is executed for each aborted request.
The stream is reset to the idle state.

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

callback is the callback handler. It takes the following arguments:

usb_pipe_handle_t cb_pipe_handle

Handle of the stream pipe to reset.

usb_opaque_t callback_arg

Callback_arg specified to usb_pipe_bulk_reset_stream ().

int rval

Return value of the reset call.

usb_cb_flags_t callback_flags

The status of the queueing operation can be one of the following value:

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 of the callback handler rval argument are as follows:

USB_SUCCESS: Reset successful on a stream.
USB_INVALID_PIPE: pipe_handle specifies a pipe which is closing or closed.
USB_INVALID_ARGS: pipe_handle arguments are NULL. USB_FLAGS_SLEEP is clear and callback is NULL.
USB_INVALID_CONTEXT: Called from the interrupt context with the USB_FLAGS_SLEEP flag set.
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.

Context

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 USB_FLAGS_SLEEP flag is in clear state. They may not be called from a callback executing in interrupt context if the USB_FLAGS_SLEEP flag is set.

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


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

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

man pages section 9: DDI and DKI Kernel Functions