Go to main content

man pages section 9: DDI and DKI Properties and Data Structures

Exit Print View

Updated: Thursday, June 13, 2019
 
 

usb_intr_request(9S)

Name

usb_intr_request - USB interrupt request structure

Synopsis

#include <sys/usb/usba.h> 

Interface Level

Solaris DDI specific (Solaris DDI)

Description

An interrupt request (that is, a request sent through an interrupt pipe), is used to transfer small amounts of data infrequently, but with bounded service periods. (Data flows in either direction.) Please refer to Section 5.7 of the USB 2.0 specification for information on interrupt transfers. (The USB 2.0 specification is available at www.usb.org.)

The fields in the usb_intr_req_t are used to format an interrupt request. Please see below for acceptable combinations of flags and attributes.

The usb_intr_req_t fields are:


  ushort_t       intr_len;     /* Size of pkt. Must be set */
                                /* Max size is 8K for low/full speed */
                                /* Max size is 20K for high speed */
   mblk_t         *intr_data;   /* Data for the data phase  */
                                /* IN: zero-len mblk alloc by client */
                                /* OUT: allocated by client */
   usb_opaque_t   intr_client_private; /* client specific information  */
   uint_t         intr_timeout; /* only with ONE TIME POLL, in secs */
                                /* If set to zero, defaults to 5 sec */
   usb_req_attrs_t intr_attributes;

   /* Normal callback function, called upon completion. */
   void           (*intr_cb)(
                      usb_pipe_handle_t ph, struct usb_intr_req *req);

   /* Exception callback function, for error handling. */
   void           (*intr_exc_cb)(
                      usb_pipe_handle_t ph, struct usb_intr_req *req);

   /* set by USBA/HCD on completion */
   usb_cr_t    intr_completion_reason; /* overall completion status */
                                      /* See usb_completion_reason(9S) */
   usb_cb_flags_t intr_cb_flags; /* recovery done by callback hndlr */
                                     /* See usb_callback_flags(9S) */

Request attributes define special handling for transfers. The following attributes are valid for interrupt requests:

USB_ATTRS_SHORT_XFER_OK

Accept transfers where less data is received than expected.

USB_ATTRS_AUTOCLEARING

Have USB framework reset pipe and clear functional stalls automatically on exception.

USB_ATTRS_PIPE_RESET

Have USB framework reset pipe automatically on exception.

USB_ATTRS_ONE_XFER

Perform a single IN transfer. Do not start periodic transfers with this request.

Please see usb_request_attributes(9S) for more information.


Interrupt transfers/requests are subject to the following 
constraints and caveats:

1) The following table indicates combinations of 
   usb_pipe_intr_xfer() flags argument and fields 
   of the usb_intr_req_t request argument (X = don't care):

     "none" as attributes in the table below indicates 
     neither ONE_XFER nor SHORT_XFER_OK

     flags     Type  attributes      data    timeout semantics
     ----------------------------------------------------------------
     X         IN    X               !=NULL  X       illegal

     X         IN    !ONE_XFER       X       !=0     illegal

     X         IN    !ONE_XFER       NULL    0       See table note (A)

     no sleep  IN    ONE_XFER        NULL    0       See table note (B)

     no sleep  IN    ONE_XFER        NULL    !=0     See table note (C)

     sleep     IN    ONE_XFER        NULL    0       See table note (D)

     sleep     IN    ONE_XFER        NULL    !=0     See table note (E)

     X         OUT   X               NULL    X       illegal

     X         OUT   ONE_XFER        X       X       illegal
        
     X         OUT   SHORT_XFER_OK   X       X       illegal

     no sleep  OUT   none            !=NULL  0       See table note (F)

     no sleep  OUT   none            !=NULL  !=0     See table note (G)

     sleep     OUT   none            !=NULL  0       See table note (H)

     sleep     OUT   none            !=NULL  !=0     See table note (I)

     Table notes:

       A) Continuous polling, new data is returned in cloned request
          structures via continuous callbacks, original request is 
          returned on stop polling.

       B) One time poll, no timeout, callback when data is 
          received.

       C) One time poll, with timeout, callback when data 
          is received.

       D) One time poll, no timeout, one callback, unblock 
          when transfer completes.

       E) One time poll, timeout, one callback, unblock when 
          transfer completes or timeout occurs.

       F) Transfer until data exhausted, no timeout, callback 
          when done.

       G) Transfer until data exhausted, timeout, callback 
          when done.

       H) Transfer until data exhausted, no timeout, unblock 
          when data is received.

       I) Transfer until data exhausted, timeout, unblock 
          when data is received.


   2) USB_FLAGS_SLEEP indicates here just to wait for 
      resources, except when ONE_XFER is set, in which case it 
      also waits for completion before returning.

   3) Reads (IN):

       a) The client driver does *not* provide a data buffer.  
          By default, a READ request would mean continuous 
          polling for data IN.  The USBA framework allocates a 
          new data buffer for each poll.  intr_len specifies 
         the amount of 'periodic data' for each poll.

       b) The USBA framework issues a callback to the client 
          at the end of a polling interval when there is data to 
          return.  Each callback returns its data in a new request 
          cloned from the original.  Note that the amount of data 
          read IN is either intr_len or "wMaxPacketSize" in length.

       c) Normally, the HCD keeps polling the interrupt endpoint 
          forever even if there is no data to be read IN.  A 
          client driver may stop this polling by calling 
          usb_pipe_stop_intr_polling(9F).
        
       d) If a client driver chooses to pass USB_ATTRS_ONE_XFER 
          as 'xfer_attributes' the HCD polls for data until 
          some data is received.  The USBA framework reads in 
          the data, does a callback, and stops polling for any 
          more data.  In this case, the client
          driver need not explicitly call 
          usb_pipe_stop_intr_polling().

       e) All requests with USB_ATTRS_ONE_XFER require callbacks 
          to be specified. 
        
       f) When continuous polling is stopped, the original 
          request is returned with USB_CR_STOPPED_POLLING.
      
       g) If the USB_ATTRS_SHORT_XFER_OK attribute is not set 
          and a short transfer is received while polling, 
          an error is assumed and polling is stopped.  In this 
          case or the case of other errors, the error must be cleared 
          and polling restarted by the client driver. Setting the 
          USB_ATTRS_AUTOCLEARING attribute will clear the error
          but not restart polling.  (NOTE: Polling can be 
          restarted from an exception callback corresponding to 
          an original request.  Please see usb_pipe_intr_xfer(9F) 
          for more information.

   4) Writes (OUT):
        
       a) A client driver provides the data buffer, and 
          data, needed for intr write.

       b) Unlike read (see previous section), there  
         is no continuous write mode.

       c) The USB_ATTRS_ONE_XFER attribute is illegal.  
          By default USBA keeps writing intr data until 
          the provided data buffer has been
          written out. The USBA framework does ONE 
          callback to the client driver.

       d) Queueing is supported.

    The intr_completion_reason indicates the status 
    of the transfer.  See usb_completion_reason(9S) for 
    usb_cr_t definitions.

    The intr_cb_flags are set prior to calling the 
    exception callback handler, to summarize recovery actions 
    taken and errors encountered during
    recovery.  See usb_callback_flags(9S) for 
    usb_cb_flags_t definitions.

    --- Callback handling ---

    All usb request types share the same callback 
    handling. Please see usb_callback_flags(9S) for a 
   description of use and operation.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Architecture
PCI-based systems
Interface Stability
Committed
Availability
system/io/usb

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_callback_flags(9S), usb_completion_reason(9S), usb_ctrl_request(9S), usb_isoc_request(9S), usb_request_attributes(9S)