usb_callback_flags(9S)					    Data Structures for Drivers 				    usb_callback_flags(9S)

NAME

       usb_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
       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 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 misunder-
				  stood 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  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. 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.

       USB_CB_SUBMIT_FAILED	  A  queued  request  was  submitted  to  the host controller driver and	     was rejected. The usb_comple-
				  tion_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
       handler.

   CALLBACK HANDLER
       The USBA framework supports callback handling as a way of asynchronous client driver notification. There are three kinds of callbacks: Nor-
       mal 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  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 overlap and there are not enough threads to handle the number of
       overlapping 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  interrupt  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  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 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 complex depen-
		  dencies 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 complete. (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 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.

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

       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
       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 attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |PCI-based systems 	   |
       +-----------------------------+-----------------------------+
       |Interface stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWusb, SUNWusbu 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       usb_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)