Windows PowerShell command on Get-command usb_callback

Manual Pages for UNIX Operating System command usage for man usb_callback_flags

Data Structures for Drivers usb_callback_flags(9S)

NAME

usb_callback_flags - USB callback flag definitions

SYNOPSIS

#include

INTERFACE LEVEL

Solaris DDI specific (Solaris DDI)

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

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

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

SunOS 5.11 Last change: 5 Jan 2004 1

Data Structures for Drivers usb_callback_flags(9S)

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 automatically via auto-

clearing, 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 excep-

tion callback is called.

USB_CB_ASYNC_REQ_FAILED 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

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

SunOS 5.11 Last change: 5 Jan 2004 2

Data Structures for Drivers usb_callback_flags(9S)

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 inter-

rupt context and should not block.

The usb_cb_flags_t enumerated type defines a bitmask. Multi-

ple bits can be set, reporting back multiple statuses to the exception callback handler. 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 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. 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 usb_callback_flags(9S)

The pp_max_async_reqs field of the pipe_policy 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 pipe_policy is passed to

usb_pipe_open(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 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.

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

usb_pipe_close(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 asyn-

chronous commands can start from a callback, pro-

viding that the pipe's policy pp_max_async_reqs

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 usb_callback_flags(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

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).) 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. 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 call-

back notification. 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).

SunOS 5.11 Last change: 5 Jan 2004 5

Data Structures for Drivers usb_callback_flags(9S)

The signature of a command completion callback is as fol-

lows:

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

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

SunOS 5.11 Last change: 5 Jan 2004 6

Data Structures for Drivers usb_callback_flags(9S)

____________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Architecture | PCI-based systems |

|_____________________________|_____________________________|

| Interface Stability | Committed |

|_____________________________|_____________________________|

| Availability | driver/usb, driver/usbu |

|_____________________________|_____________________________|

Manual Pages for UNIX Operating System command usage for man usb_callback_flags

Data Structures for Drivers usb_callback_flags(9S)

NAME

usb_callback_flags - USB callback flag definitions

SYNOPSIS

INTERFACE LEVEL

DESCRIPTION

Data Structures for Drivers usb_callback_flags(9S)

Data Structures for Drivers usb_callback_flags(9S)

USB_CB_INTR_CONTEXT Callback is executing in inter-

Data Structures for Drivers usb_callback_flags(9S)

flags show USB_CB_INTR_CONTEXT set, since that flag

Data Structures for Drivers usb_callback_flags(9S)

Data Structures for Drivers usb_callback_flags(9S)

ATTRIBUTES

Data Structures for Drivers usb_callback_flags(9S)

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

SEE ALSO