Data Structures for Drivers usb_intr_request(9S)
NAME
usb_intr_request - USB interrupt request structure
SYNOPSIS
#include
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 combina-
tions 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) */
SunOS 5.11 Last change: 5 Jan 2004 1
Data Structures for Drivers usb_intr_request(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 automati-
cally 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 ofusb_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 indicatesneither ONE_XFER nor SHORT_XFER_OK
flags Type attributes data timeout semantics----------------------------------------------------------------
X IN X !=NULL X illegalX 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 illegalSunOS 5.11 Last change: 5 Jan 2004 2
Data Structures for Drivers usb_intr_request(9S)
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 continous 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 aSunOS 5.11 Last change: 5 Jan 2004 3
Data Structures for Drivers usb_intr_request(9S)
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 dataread 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 callingusb_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 callusb_pipe_stop_intr_polling().
e) All requests with USB_ATTRS_ONE_XFER require callbacks
to be specified. f) When continuous polling is stopped, the originalrequest 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 theUSB_ATTRS_AUTOCLEARING attribute will clear the error
but not restart polling. (NOTE: Polling can be restarted from an exception callback corresponding toan 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.SunOS 5.11 Last change: 5 Jan 2004 4
Data Structures for Drivers usb_intr_request(9S)
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 duringrecovery. See usb_callback_flags(9S) for
usb_cb_flags_t definitions.
--- Callback handling ---
All usb request types share the same callbackhandling. Please see usb_callback_flags(9S) for a
description of use and operation.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | PCI-based systems |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| Availability | system/header/header-usb |
|_____________________________|_____________________________|
SEE ALSO
usb_alloc_request(9F), usb_pipe_ctrl_xfer(9F),
usb_pipe_bulk_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)
SunOS 5.11 Last change: 5 Jan 2004 5