usb_callback_flags(9S) Data Structures for Drivers usb_callback_flags(9S)NAMEusb_callback_flags - USB callback flag definitions
SYNOPSIS
#include <sys/usb/usba.h>
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)
DESCRIPTION
If the USB framework detects an error during a request execution, 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 recov‐
ery process, and summarize recovery actions taken by the USBA frame‐
work.
Information from the callback flags supplements information from the
original transport error. For transfers, the original transport error
status is returned to the callback handler through the original request
(whose completion reason field contains any transport error indica‐
tion). For command completion callbacks, the callback's rval argument
contains the transport error status. A completion reason of USB_CR_OK
means the transfer completed with no errors detected.
The usb_cb_flags_t enumerated type contains the following definitions:
USB_CB_NO_INFO No additional errors discovered or recovery
actions taken.
USB_CB_FUNCTIONAL_STALL A functional stall occurred during 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.
USB_CB_STALL_CLEARED A functional stall has been cleared by the
USBA framework. This can happen
if USB_ATTRS_AUTOCLEARING is set in the
request's xxxx_attributes field.
USB_CB_PROTOCOL_STALL 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.
USB_CB_RESET_PIPE A pipe with a stall has been reset automati‐
cally via autoclearing, or via an explicit
call to usb_pipe_reset(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
USB_CB_RESET_PIPE set in the usb_cb_flags_t
when their exception callback is called.
USB_CB_ASYNC_REQ_FAILED Resources could not be allocated to process
callbacks asynchronously. Call‐
backs receiving this flag must not block,
since those callbacks are executing in a
context which holds resources shared by the
rest of the system. Note that exception
callbacks with USB_CB_ASYNC_REQ_FAILED 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.
USB_CB_SUBMIT_FAILED A queued request was submitted to the host
controller driver and was
rejected. The usb_completion_reason shows
why the request was rejected by the host
controller.
USB_CB_NO_RESOURCES Insufficient resources were available for
recovery to proceed.
USB_CB_INTR_CONTEXT Callback is executing in interrupt context
and should not block.
The usb_cb_flags_t enumerated type defines a bitmask. Multiple bits can
be set, reporting back multiple statuses to the exception callback han‐
dler.
CALLBACK 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 speci‐
fies the USB_FLAGS_SLEEP flag. (USB_FLAGS_SLEEP 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 comple‐
tion 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 overlap‐
ping callbacks.
The pp_max_async_reqs field of the pipe_policy provides a hint of how
many threads to allocate for asynchronous processing of request call‐
backs on a pipe. Set this value high enough per pipe to accommodate
all of the pipe's possible asynchronous conditions. The pipe_policy is
passed to usb_pipe_open(9F).
Transfer completion callbacks (normal completion and exception):
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
USB_CB_INTR_CONTEXT set, since that flag indicates that the
callback is running in interrupt context instead of kernel
context. Isochronous normal completion callbacks, plus
those with USB_CB_ASYNC_REQ_FAILED set, execute in inter‐
rupt context.
2. Any callback except for isochronous normal completion can
block for resources (for example to allocate memory).
3. No callback can block for synchronous completion of a com‐
mand (for example, a call to usb_pipe_close(9F) with the
USB_FLAGS_SLEEP flag passed) done on the same pipe. The com‐
mand could wait for all callbacks to complete, including the
callback which issued that command, causing all operations
on the pipe to deadlock. Note that asynchronous commands can
start from a callback, providing that the pipe's policy
pp_max_async_reqs field is initialized to accommodate them.
4. Avoid callbacks that block for synchronous completion of
commands done on other pipes. Such conditions can cause com‐
plex dependencies and unpredictable 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 com‐
plete. (This is because all callbacks are done by a single
thread.)
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 exception callback. Such requests conclude by call‐
ing the exception callback when the transfer completes abnormally. Note
that the same callback can be used for both normal completion and
exception callback handling. A completion reason of USB_CR_OK defines
normal completion.
All request-callbacks take as arguments a usb_pipe_handle_t and a
pointer to the request:
xxxx_cb(usb_pipe_handle_t ph, struct usb_ctrl_req *req);
Such callbacks can retrieve saved state or other information from the
private area of the pipe handle. (See usb_pipe_set_private(9F).) Han‐
dlers also have access to the completion reason (usb_cr_t) and callback
flags (usb_cb_flags_t) 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 usb_xxxx_req_t.
Normal completion callback handler field is xxxx_cb.
Exception callback handler field is xxxx_exc_cb.
Completion reason field is xxxx_completion_reason.
Callback flags field is xxxx_cb_flags.
COMMAND COMPLETION CALLBACKS
Calls to some non-transfer functions can be set up for callback notifi‐
cation. These include usb_pipe_close(9F), usb_pipe_reset(9F),
usb_pipe_drain_reqs(9F), usb_set_cfg(9F), usb_set_alt_if(9F) and
usb_clr_feature(9F).
The signature of a command completion callback is as follows:
command_cb(
usb_pipe_handle_t cb_pipe_handle,
usb_opaque_t arg,
int rval,
usb_cb_flags_t flags);
As with transfer completion callbacks, command completion callbacks
take a usb_pipe_handle_t 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 (usb_opaque_t arg),
the return status of the executed command (int rval), and the callback
flags (usb_cb_flags_t flags).
The rval argument is roughly equivalent to the completion reason of a
transfer callback, indicating the overall status. See the return val‐
ues 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 addi‐
tional information on execution events.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │PCI-based systems │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│Availability │driver/usb, driver/usbu │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOusb_alloc_request(9F), usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F),
usb_pipe_intr_xfer(9F), usb_pipe_isoc_xfer(9F), usb_bulk_request(9S),
usb_ctrl_request(9S), usb_intr_request(9S), usb_isoc_request(9S)SunOS 5.11 5 Jan 2004 usb_callback_flags(9S)
