8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man9s / usb_callback_flags.9s

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH USB_CALLBACK_FLAGS 9S "Jan 5, 2004"
.SH NAME
usb_callback_flags \- USB callback flag definitions
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH DESCRIPTION
.sp
.LP
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 recovery process, and summarize recovery
actions taken by the USBA framework.
.sp
.LP
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 indication). For command completion
callbacks, the callback's rval argument contains the transport error status. A
completion reason of \fBUSB_CR_OK\fR means the transfer completed with no
errors detected.
.sp
.LP
The usb_cb_flags_t enumerated type contains the following definitions:
.sp
.ne 2
.na
\fBUSB_CB_NO_INFO\fR
.ad
.RS 27n
No additional errors discovered or recovery actions taken.
.RE

.sp
.ne 2
.na
\fBUSB_CB_FUNCTIONAL_STALL\fR
.ad
.RS 27n
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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_STALL_CLEARED\fR
.ad
.RS 27n
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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_PROTOCOL_STALL\fR
.ad
.RS 27n
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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_RESET_PIPE\fR
.ad
.RS 27n
A pipe with a stall has been reset automatically via autoclearing, or via an
explicit call to \fBusb_pipe_reset\fR(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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_ASYNC_REQ_FAILED\fR
.ad
.RS 27n
Resources could not be allocated to process callbacks
asynchronously. Callbacks 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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_SUBMIT_FAILED\fR
.ad
.RS 27n
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.
.RE

.sp
.ne 2
.na
\fBUSB_CB_NO_RESOURCES\fR
.ad
.RS 27n
Insufficient resources were available for recovery to proceed.
.RE

.sp
.ne 2
.na
\fBUSB_CB_INTR_CONTEXT\fR
.ad
.RS 27n
Callback is executing in interrupt context and should not block.
.RE

.sp
.LP
The usb_cb_flags_t enumerated type defines a bitmask. Multiple bits can be set,
reporting back multiple statuses to the exception callback handler.
.SS "CALLBACK HANDLER"
.sp
.LP
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.
.sp
.LP
Callback handlers are called whenever they are specified in a request or
command, regardless of whether or not that request or command specifies 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.
.SS "PIPE POLICY"
.sp
.LP
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.
.sp
.LP
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 overlap and there are not enough
threads to handle the number of overlapping callbacks.
.sp
.LP
The pp_max_async_reqs field of the pipe_policy provides a hint of how many
threads to allocate for asynchronous processing of request callbacks 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 \fBusb_pipe_open\fR(9F).
.sp
.LP
Transfer completion callbacks (normal completion and exception):
.sp
.LP
Most transfer completion callbacks are allowed to block, but only under certain
conditions:
.RS +4
.TP
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  interrupt
context.
.RE
.RS +4
.TP
2.
Any callback except for isochronous normal completion can block for
resources (for example to allocate memory).
.RE
.RS +4
.TP
3.
No callback can block for synchronous completion of a command (for example,
a call to \fBusb_pipe_close\fR(9F) with the USB_FLAGS_SLEEP 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 asynchronous commands can start from a callback,
providing that the pipe's policy pp_max_async_reqs field is initialized to
accommodate them.
.RE
.RS +4
.TP
4.
Avoid callbacks that block for synchronous completion of commands done on
other pipes. Such conditions can cause complex dependencies and unpredictable
results.
.RE
.RS +4
.TP
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.)
.RE
.RS +4
.TP
6.
No callback can block waiting for another callback to complete. (This is
because all callbacks are done by a single thread.)
.RE
.RS +4
.TP
7.
Note that if a callback blocks, other callbacks awaiting processing can
backup behind it, impacting system resources.
.RE
.sp
.LP
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 calling 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.
.sp
.LP
All request-callbacks take as arguments a usb_pipe_handle_t and a pointer to
the request:
.sp
.in +2
.nf
xxxx_cb(usb_pipe_handle_t ph, struct usb_ctrl_req *req);
.fi
.in -2

.sp
.LP
Such callbacks can retrieve saved state or other information from the private
area of the pipe handle.  (See \fBusb_pipe_set_private\fR(9F).) Handlers also
have access to the completion reason (usb_cr_t) and callback flags
(usb_cb_flags_t) through the request argument they are passed.
.sp
.LP
Request information follows. In the data below, \fIxxxx\fR below represents the
type of request (ctrl, intr, isoc or bulk.)
.sp
.in +2
.nf
            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.
.fi
.in -2

.SS "COMMAND COMPLETION CALLBACKS"
.sp
.LP
Calls to some non-transfer functions can be set up for callback notification.
These include \fBusb_pipe_close\fR(9F), \fBusb_pipe_reset\fR(9F),
\fBusb_pipe_drain_reqs\fR(9F), \fBusb_set_cfg\fR(9F), \fBusb_set_alt_if\fR(9F)
and \fBusb_clr_feature\fR(9F).
.sp
.LP
The signature of a command completion callback is as follows:
.sp
.in +2
.nf
                command_cb(
                    usb_pipe_handle_t cb_pipe_handle,
                    usb_opaque_t arg,
                    int rval,
                    usb_cb_flags_t flags);
.fi
.in -2

.sp
.LP
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).
.sp
.LP
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.
.sp
.LP
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.
.SH ATTRIBUTES
.sp
.LP
See attributes(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Architecture    PCI-based systems
_
Interface stability     Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F),
\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F),
\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S),
\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S),
\fBusb_isoc_request\fR(9S)