Data Structures for Drivers usbbulkrequest(9S)
NAME
usbbulkrequest - USB bulk request structure
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
A bulk request (that is, a request sent through a bulk pipe)
is used to transfer large amounts of data in reliable but
non-time-critical fashion. Please refer to Section 5.8 of
the USB 2.0 specification for information on bulk transfers.
(The USB 2.0 specification is available at www.usb.org.)
The fields in the usbbulkreqt are used to format a bulk
request. Please see below for acceptable combinations of
flags and attributes.
The usbbulkreqt fields are:
uintt bulklen; /* number of bytes to xfer */
/* Please see */
/* usbpipegetmaxbulkxfersize(9F) */
/* for maximum size */
mblkt *bulkdata; /* the data for the data phase */
/* IN or OUT: allocated by client */
uintt bulktimeout; /* xfer timeout value in secs */
/* If set to zero, defaults to 5 sec */
usbopaquet bulkclientprivate; /* Client specific information */
usbreqattrst bulkattributes; /* xfer-attributes */
/* Normal callback function, called upon completion. */
void (*bulkcb)(
usbpipehandlet ph, struct usbbulkreq *req);
/* Exception callback function, for error handling. */
void (*bulkexccb)(
usbpipehandlet ph, struct usbbulkreq *req);
/* set by USBA/HCD framework on completion */
usbcrt bulkcompletionreason; /* overall success status */
/* See usbcompletionreason(9S) */
usbcbflagst bulkcbflags; /* recovery done by callback hndlr */
/* See usbcallbackflags(9S) */
SunOS 5.11 Last change: 5 Jan 2004 1
Data Structures for Drivers usbbulkrequest(9S)
Request attributes define special handling for transfers.
The following attributes are valid for bulk requests:
USBATRSHORTXFEROK USB framework accepts transfers
where less data is received than
expected.
USBATRSAUTOCLEARING USB framework resets pipe and
clears functional stalls automat-
ically on exception.
USBATRSPIPERESET USB framework resets pipe
automatically on exception.
Please see usbrequestattributes(9S) for more information.
Bulk transfers/requests are subject to the following con-
straints and caveats:
1) The following table indicates combinations of
usbpipebulkxfer() flags argument and fields of the
usbbulkreqt request argument (X = don't care).
Flags Type Attributes Data Timeout Semantics
---------------------------------------------------------------
X X X ==NUL X illegal
X X ONEXFER X X illegal
no sleep IN !SHORTXFEROK !=NUL 0 See note (A)
no sleep IN !SHORTXFEROK !=NUL > 0 See note (B)
sleep IN !SHORTXFEROK !=NUL 0 See note (C)
sleep IN !SHORTXFEROK !=NUL > 0 See note (D)
no sleep IN SHORTXFEROK !=NUL 0 See note (E)
no sleep IN SHORTXFEROK !=NUL > 0 See note (F)
sleep IN SHORTXFEROK !=NUL 0 See note (G)
sleep IN SHORTXFEROK !=NUL > 0 See note (H)
SunOS 5.11 Last change: 5 Jan 2004 2
Data Structures for Drivers usbbulkrequest(9S)
X OUT SHORTXFEROK X X illegal
no sleep OUT X !=NUL 0 See note (I)
no sleep OUT X !=NUL > 0 See note (J)
sleep OUT X !=NUL 0 See note (K)
sleep OUT X !=NUL > 0 See note (L)
Table notes:
A). Fill buffer, no timeout, callback when bulklen is
transferred.
B). Fill buffer, with timeout; callback when bulklen is
transferred.
C). Fill buffer, no timeout, unblock when bulklen is
transferred; no callback.
D). Fill buffer, with timeout; unblock when bulklen is
transferred or a timeout occurs; no callback.
E) Fill buffer, no timeout, callback when bulklen is
transferred or first short packet is received.
F). Fill buffer, with timeout; callback when bulklen is
transferred or first short packet is received.
G). Fill buffer, no timeout, unblock when bulklen is
transferred or first short packet is received; no call-
back.
H). Fill buffer, with timeout; unblock when bulklen is
transferred, first short packet is received, or a timeout
occurs; no callback.
I). Empty buffer, no timeout; callback when bulklen is
transferred.
J) Empty buffer, with timeout; callback when bulklen is
transferred or a timeout occurs.
K). Empty buffer, no timeout; unblock when bulklen is
transferred; no callback.
L). Empty buffer, with timeout; unblock when bulklen is
transferred or a timeout occurs; no callback.
2) bulklen must be > 0. bulkdata must not be NUL.
3) Bulkresidue is set for both READ and WRITE. If it is set
to 0, it means that all of the data was transferred success-
fully. In case of WRITE it contains data not written and in
case of READ it contains the data NOT read so far. A residue
can only occur because of timeout or bus/device error. (Note
that a short transfer for a request where the
USBATRSHORTXFEROK attribute is not set is considered a
device error.) An exception callback is made and
SunOS 5.11 Last change: 5 Jan 2004 3
Data Structures for Drivers usbbulkrequest(9S)
completionreason will be non-zero.
4) Splitting large Bulk xfers: Due to internal constraints,
the USBA framework can only do a limited size bulk data xfer
per request. A client driver may first determine this limi-
tation by calling the USBA interface
(usbpipegetmaxbulkxfersize(9F)) and then restrict
itself to doing transfers in multiples of this fixed size.
This forces a client driver to do data xfers in a loop for a
large request, splitting it into multiple chunks of fixed
size.
The bulkcompletionreason indicates the status of the
transfer. See usbcompletionreason(9S) for usbcrt defin-
itions.
The bulkcbflags are set prior to calling the exception
callback handler to summarize recovery actions taken and
errors encountered during recovery. See
usbcallbackflags(9S) for usbcbflagst definitions.
--- Callback handling ---
All usb request types share the same callback handling. See
usbcallbackflags(9S) for details.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jan 2004 4
Data Structures for Drivers usbbulkrequest(9S)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusbu
SEE ALSO
usballocrequest(9F), usbpipebulkxfer(9F),
usbpipectrlxfer(9F),
usbpipegetmaxbulktransfersize(9F),
usbpipeintrxfer(9F), usbpipeisocxfer(9F),
usbcallbackflags(9S), usbcompletionreason(9S),
usbctrlrequest(9S), usbintrrequest(9S),
usbisocrequest(9S), usbrequestattributes(9S)
SunOS 5.11 Last change: 5 Jan 2004 5
|
