Data Structures for Drivers usbcallbackflags(9S)
NAME
usbcallbackflags - USB callback flag definitions
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
If the USB framework detects an error during a request exe-
cution, it calls the client driver's exception callback
handler to report what happened. Callback flags (which are
set prior to calling the exception callback handler) detail
errors discovered during the exception recovery process, and
summarize recovery actions taken by the USBA framework.
Information from the callback flags supplements information
from the original transport error. For transfers, the origi-
nal transport error status is returned to the callback
handler through the original request (whose completion rea-
son field contains any transport error indication). For com-
mand completion callbacks, the callback's rval argument con-
tains the transport error status. A completion reason of
USBCROK means the transfer completed with no errors
detected.
The usbcbflagst enumerated type contains the following
definitions:
USBCBNOINFO No additional errors discovered
or recovery actions taken.
USBCBFUNCTIONALSTAL A functional stall occurred dur-
ing the transfer. A functional
stall is usually caused by a
hardware error, and must be
explicitly cleared. A functional
stall is fatal if it cannot be
cleared. The default control pipe
never shows a functional stall.
USBCBSTALCLEARED A functional stall has been
cleared by the USBA framework.
This can happen if
USBATRSAUTOCLEARING is set in
the request's xxxxattributes
SunOS 5.11 Last change: 5 Jan 2004 1
Data Structures for Drivers usbcallbackflags(9S)
field.
USBCBPROTOCOLSTAL A protocol stall has occurred
during the transfer. A protocol
stall is caused usually by an
invalid or misunderstood command.
It is cleared automatically when
the device is given its next
command. The USBA framework
treats stalls detected on default
pipe transfers as protocol
stalls.
USBCBRESETPIPE A pipe with a stall has been
reset automatically via auto-
clearing, or via an explicit call
to usbpipereset(9F). Resetting
a pipe consists of stopping all
transactions on a pipe, setting
the pipe to the idle state, and
if the pipe is not the default
pipe, flushing all pending
requests. The request which has
the error, plus all pending
requests which are flushed, show
USBCBRESETPIPE set in the
usbcbflagst when their excep-
tion callback is called.
USBCBASYNCREQFAILED Resources could not be allocated
to process callbacks
asynchronously. Callbacks receiv-
ing this flag must not block,
since those callbacks are execut-
ing in a context which holds
resources shared by the rest of
the system. Note that exception
callbacks with
USBCBASYNCREQFAILED set may
execute out of order from the
requests which preceded them.
Normal callbacks may be already
queued when an exception hits
that the USBA is unable to queue.
USBCBSUBMITFAILED A queued request was submitted to
the host controller driver and
was rejected. The
SunOS 5.11 Last change: 5 Jan 2004 2
Data Structures for Drivers usbcallbackflags(9S)
usbcompletionreason shows why
the request was rejected by the
host controller.
USBCBNORESOURCES Insufficient resources were
available for recovery to
proceed.
USBCBINTRCONTEXT Callback is executing in inter-
rupt context and should not
block.
The usbcbflagst enumerated type defines a bitmask. Multi-
ple bits can be set, reporting back multiple statuses to the
exception callback handler.
CALBACK HANDLER
The USBA framework supports callback handling as a way of
asynchronous client driver notification. There are three
kinds of callbacks: Normal completion transfer callback,
exception (error) completion transfer callback, and command
completion callback, each described below.
Callback handlers are called whenever they are specified in
a request or command, regardless of whether or not that
request or command specifies the USBFLAGSLEP flag.
(USBFLAGSLEP tells the request or command to block until
completed.) Callback handlers must be specified whenever an
asynchronous transfer is requested.
PIPE POLICY
Each pipe is associated with a pool of threads that are used
to run callbacks associated with requests on that pipe. All
transfer completion callbacks for a particular pipe are run
serially by a single thread.
Pipes taking requests with callbacks which can block must
have their pipe policy properly initialized. If a callback
blocks on a condition that is only met by another thread
associated with the same pipe, there must be sufficient
threads available. Otherwise that callback thread will block
forever. Similarly, problems will ensue when callbacks over-
lap and there are not enough threads to handle the number of
overlapping callbacks.
SunOS 5.11 Last change: 5 Jan 2004 3
Data Structures for Drivers usbcallbackflags(9S)
The ppmaxasyncreqs field of the pipepolicy provides a
hint of how many threads to allocate for asynchronous pro-
cessing of request callbacks on a pipe. Set this value high
enough per pipe to accommodate all of the pipe's possible
asynchronous conditions. The pipepolicy is passed to
usbpipeopen(9F).
Transfer completion callbacks (normal completion and excep-
tion):
Most transfer completion callbacks are allowed to block, but
only under certain conditions:
1. No callback is allowed to block if the callback
flags show USBCBINTRCONTEXT set, since that flag
indicates that the callback is running in interrupt
context instead of kernel context. Isochronous
normal completion callbacks, plus those with
USBCBASYNCREQFAILED set, execute in interrupt
context.
2. Any callback except for isochronous normal comple-
tion can block for resources (for example to allo-
cate memory).
3. No callback can block for synchronous completion of
a command (for example, a call to
usbpipeclose(9F) with the USBFLAGSLEP flag
passed) done on the same pipe. The command could
wait for all callbacks to complete, including the
callback which issued that command, causing all
operations on the pipe to deadlock. Note that asyn-
chronous commands can start from a callback, pro-
viding that the pipe's policy ppmaxasyncreqs
field is initialized to accommodate them.
4. Avoid callbacks that block for synchronous comple-
tion of commands done on other pipes. Such condi-
tions can cause complex dependencies and unpredict-
able results.
5. No callback can block waiting for a synchronous
transfer request to complete. (Note that making an
asynchronous request to start a new transfer or
start polling does not block, and is OK.)
6. No callback can block waiting for another callback
to complete. (This is because all callbacks are
done by a single thread.)
SunOS 5.11 Last change: 5 Jan 2004 4
Data Structures for Drivers usbcallbackflags(9S)
7. Note that if a callback blocks, other callbacks
awaiting processing can backup behind it, impacting
system resources.
A transfer request can specify a non-null normal-completion
callback. Such requests conclude by calling the normal-
completion callback when the transfer completes normally.
Similarly, a transfer request can specify a non-null excep-
tion callback. Such requests conclude by calling the excep-
tion callback when the transfer completes abnormally. Note
that the same callback can be used for both normal comple-
tion and exception callback handling. A completion reason of
USBCROK defines normal completion.
All request-callbacks take as arguments a usbpipehandlet
and a pointer to the request:
xxxxcb(usbpipehandlet ph, struct usbctrlreq *req);
Such callbacks can retrieve saved state or other information
from the private area of the pipe handle. (See
usbpipesetprivate(9F).) Handlers also have access to the
completion reason (usbcrt) and callback flags
(usbcbflagst) through the request argument they are
passed.
Request information follows. In the data below, xxxx below
represents the type of request (ctrl, intr, isoc or bulk.)
Request structure name is usbxxxxreqt.
Normal completion callback handler field is xxxxcb.
Exception callback handler field is xxxxexccb.
Completion reason field is xxxxcompletionreason.
Callback flags field is xxxxcbflags.
COMAND COMPLETION CALBACKS
Calls to some non-transfer functions can be set up for call-
back notification. These include usbpipeclose(9F),
usbpipereset(9F), usbpipedrainreqs(9F),
usbsetcfg(9F), usbsetaltif(9F) and usbclrfeature(9F).
SunOS 5.11 Last change: 5 Jan 2004 5
Data Structures for Drivers usbcallbackflags(9S)
The signature of a command completion callback is as fol-
lows:
commandcb(
usbpipehandlet cbpipehandle,
usbopaquet arg,
int rval,
usbcbflagst flags);
As with transfer completion callbacks, command completion
callbacks take a usbpipehandlet to retrieve saved state
or other information from the pipe's private area. Also,
command completion callbacks are provided with an additional
user-definable argument (usbopaquet arg), the return
status of the executed command (int rval), and the callback
flags (usbcbflagst flags).
The rval argument is roughly equivalent to the completion
reason of a transfer callback, indicating the overall
status. See the return values of the relevant function for
possible rval values which can be passed to the callback.
The callback flags can be checked when rval indicates
failure status. Just as for transfer completion callbacks,
callback flags return additional information on execution
events.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jan 2004 6
Data Structures for Drivers usbcallbackflags(9S)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusb, SUNWusbu
SEE ALSO
usballocrequest(9F), usbpipebulkxfer(9F),
usbpipectrlxfer(9F), usbpipeintrxfer(9F),
usbpipeisocxfer(9F), usbbulkrequest(9S),
usbctrlrequest(9S), usbintrrequest(9S),
usbisocrequest(9S)
SunOS 5.11 Last change: 5 Jan 2004 7
|
