Kernel Functions for Drivers usbpipereset(9F)
NAME
usbpipereset - Abort queued requests from a USB pipe and
reset the pipe
SYNOPSIS
#include
void usbpipereset(devinfot *dip,
usbpipehandlet pipehandle, usbflagst usbflags,
void (*callback)(usbpipehandlet cbpipehandle,
usbopaquet arg, int rval, usbcbflagst flags),
usbopaquet callbackarg);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
dip Pointer to the device's devinfo structure.
pipehandle Handle of the pipe to reset. Cannot be the
handle to the default control pipe.
usbflags USBFLAGSLEP is the only flag recognized.
Wait for completion.
callback Function called on completion if the
USBFLAGSLEP flag is not specified. If
NUL, no notification of completion is pro-
vided.
callbackarg Second argument to callback function.
DESCRIPTION
Call usbpipereset() to reset a pipe which is in an error
state, or to abort a current request and clear the pipe. The
usbpipereset() function can be called on any pipe other
than the default control pipe.
A pipe can be reset automatically when requests sent to the
pipe have the USBATRSAUTOCLEARING attribute specified.
Client drivers see an exception callback with the
USBCBSTALCLEARED callback flag set in such cases.
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbpipereset(9F)
Stalls on pipes executing requests without the
USBATRSAUTOCLEARING attribute set must be cleared by the
client driver. The client driver is notified of the stall
via an exception callback. The client driver must then call
usbpipereset() to clear the stall.
The usbpipereset() function resets a pipe as follows:
1. Any polling activity is stopped if the pipe being reset
is an interrupt or isochronous pipe.
2. All pending requests are removed from the pipe. An
exception callback, if specified beforehand, is executed
for each aborted request.
3. The pipe is reset to the idle state.
Requests to reset the default control pipe are not allowed.
No action is taken on a pipe which is closing.
If USBFLAGSLEP is specified in flags, this function
waits for the action to complete before calling the callback
handler and returning. If not specified, this function
queues the request and returns immediately, and the speci-
fied callback is called upon completion.
callback is the callback handler. It takes the following
arguments:
usbpipehandlet cbpipehandle
Handle of the pipe to reset.
usbopaquet callbackarg
Callbackarg specified to usbpipereset().
int rval
Return value of the reset call.
usbcbflagst callbackflags
Status of the queueing operation. Can be:
USBCBNOINFO - Callback was uneventful.
USBCBASYNCREQFAILED - Error starting asynchronous
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbpipereset(9F)
request.
RETURN VALUES
Status is returned to the caller via the callback handler's
rval argument. Possible callback hander rval argument values
are:
USBSUCES Pipe successfully reset.
USBINVALIDPIPE pipehandle specifies a pipe which is
closed or closing.
USBINVALIDARGS dip or pipehandle arguments are
NUL. USBFLAGSLEP is clear and
callback is NUL.
USBINVALIDCONTEXT Called from interrupt context with
the USBFLAGSLEP flag set.
USBINVALIDPERM pipehandle specifies the default
control pipe.
USBFAILURE Asynchronous resources are unavail-
able. In this case,
USBCBASYNCREQFAILED is passed in
as the callbackflags arg to the
callback hander.
Exception callback handlers of interrupt-IN and
isochronous-IN requests which are terminated by these com-
mands are called with a completion reason of
USBCRSTOPEDPOLING.
Exception handlers of incomplete bulk requests are called
with a completion reason of USBCRFLUSHED.
Exception handlers of unstarted requests are called with
USBCRPIPERESET.
Note that messages mirroring the above errors are logged to
the console logfile on error. This provides status for calls
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbpipereset(9F)
which could not otherwise provide status.
CONTEXT
May be called from user or kernel context regardless of
arguments. May be called from any callback with the
USBFLAGSLEP clear. May not be called from a callback
executing in interrupt context if the USBFLAGSLEP flag
is set.
If the USBCBASYNCREQFAILED bit is clear in
usbcbflagst, the callback, if supplied, can block because
it is executing in kernel context. Otherwise the callback
cannot block. Please see usbcallbackflags(9S) for more
information on callbacks.
EXAMPLES
void postresethandler(
usbpipehandlet, usbopaquet, int, usbcbflagst);
/*
* Do an asynchronous reset on bulkpipe.
* Execute postresethandler when done.
*/
usbpipereset(dip, bulkpipe, 0, postresethandler, arg);
/* Do a synchronous reset on bulkpipe. */
usbpipereset(dip, bulkpipe, USBFLAGSLEP, NUL, NUL);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usbpipereset(9F)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusb
SEE ALSO
attributes(5), usbgetcfg(9F), usbpipebulkxfer(9F),
usbpipeclose(9F), usbgetstatus(9F),
usbpipectrlxfer(9F), usbpipedrainreqs(9F),
usbpipegetstate(9F), usbpipeintrxfer(9F),
usbpipeisocxfer(9F), usbpipeopen(9F),
usbpipestopintrpolling(9F),
usbpipestopisocpolling(9F), usbcallbackflags(9S)
SunOS 5.11 Last change: 5 Jan 2004 5
|
