Data Structures for Drivers usbisocrequest(9S)
NAME
usbisocrequest - USB isochronous request structure
SYNOPSIS
#include
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
DESCRIPTION
A request sent through an isochronous pipe is used to
transfer large amounts of packetized data with relative
unreliability, but with bounded service periods. A packet is
guaranteed to be tried within a bounded time period, but is
not retried upon failure. Isochronous transfers are sup-
ported on both USB 1.1 and USB 2.0 devices. For further
information, see section 5.6 of the USB 2.0 specification
available at www.usb.org.
This section provides information on acceptable combinations
of flags and attributes with additional details. The follow-
ing fields of the usbisocreqt are used to format an iso-
chronous request.
usbframenumbert
isocframeno; /* frame num to start sending req. */
ushortt isocpktscount; /* num USB pkts in this request */
/*
* The sum of all pkt lengths in an isoc request. Recommend to set it to
* zero, so the sum of isocpktlength in the isocpktdescr list will be
* used automatically and no check will be apply to this element.
*/
ushortt isocpktslength;
ushortt isocerrorcount;/* num pkts completed w/errs */
usbreqattrst isocattributes;/* request-specific attrs */
mblkt *isocdata; /* data to xfer */
/* IN or OUT: alloc. by client. */
/* Size=total of all pkt lengths. */
usbopaquet isocclientprivate; /* for client driver excl use. */
struct usbisocpktdescr /* (see below) */
*isocpktdescr;
/*
* Normal callback function, called upon completion.
* This function cannot block as it executes in soft interrupt context.
*/
void (*isoccb)(
usbpipehandlet ph, struct usbisocreq *req);
/* Exception callback function, for error handling. */
SunOS 5.11 Last change: 28 Dec 2006 1
Data Structures for Drivers usbisocrequest(9S)
void (*isocexccb)(
usbpipehandlet ph, struct usbisocreq *req);
usbcrt isoccompletionreason; /* overall completion status */
/* set by USBA framework */
/* See usbcompletionreason(9S) */
usbcbflagst isoccbflags; /* recovery done by callback hndlr */
/* set by USBA on exception. */
/* See usbcallbackflags(9S) */
A usbisocpktdescrt describes the status of an isochro-
nous packet transferred within a frame or microframe. The
following fields of a usbisocpktdescrt packet descriptor
are used within an usbisocreqt. The isocpktlength is
set by the client driver to the amount of data managed by
the packet for input or output. The latter two fields are
set by the USBA framework to indicate status. Any packets
with an isoccompletionreason, other than USBCROK, are
reflected in the isocerrorcount of the usbisocreqt.
ushortt isocpktlength; /* number bytes to transfer */
ushortt isocpktactuallength; /* actual number transferred */
usbcrt isocpktstatus; /* completion status */
If two multi-frame isoc requests that both specify the
USBATRSISOCXFERASAP attribute are scheduled closely
together, the first frame of the second request is queued to
start after the last frame of the first request.
No stalls are seen in isochronous transfer exception call-
backs. Because transfers are not retried upon failure, iso-
chronous transfers continue regardless of errors.
Request attributes define special handling for transfers.
The following attributes are valid for isochronous requests:
USBATRSISOCSTARTFRAME Start transferring at the
starting frame number speci-
fied in the isocframeno
field of the request.
USBATRSISOCXFERASAP Start transferring as soon as
possible. The USBA framework
picks an immediate frame
number to map to the starting
SunOS 5.11 Last change: 28 Dec 2006 2
Data Structures for Drivers usbisocrequest(9S)
frame number.
USBATRSHORTXFEROK Accept transfers where less
data is received than
expected.
The usbisocreqt contains an array of descriptors that
describe isochronous packets. One isochronous packet is sent
per frame or microframe. Because packets that comprise a
transfer are sent across consecutive frames or microframes,
USBATRSONEXFER is invalid.
See usbrequestattributes(9S) for more information.
Isochronous transfers/requests are subject to the following
constraints and caveats:
1) The following table indicates combinations of usbpipeisocxfer
flags argument and fields of the usbisocreqt request argument
(X = don't care). (Note that attributes considered in this table
are ONEXFER, STARTFRAME, XFERASAP, and SHORTXFER, and that
some transfer types are characterized by multiple table entries.)
Flags Type Attributes Data Semantics
---------------------------------------------------------------
X X X NUL illegal
X X ONEXFER X illegal
X X ISOCSTARTFRAME X illegal
& ISOCXFERASAP
X X !ISOCSTARTFRAME X illegal
& !ISOCXFERASAP
X OUT SHORTXFEROK X illegal
X IN X !=NUL See table note (A)
X X ISOCSTARTFRAME !=NUL See table note (B)
X X ISOCXFERASAP !=NUL See table note (C)
Table notes:
A) continuous polling, new data is returned in
cloned request structures via continous callbacks,
SunOS 5.11 Last change: 28 Dec 2006 3
Data Structures for Drivers usbisocrequest(9S)
original request is returned on stop polling
B) invalid if the currentframe number is past
"isocframeno" or "isocframeno" == 0
C)"isocframeno" is ignored. The USBA framework
determines which frame to insert and start
the transfer.
2) USBFLAGSLEP indicates to wait for resources but
not for completion.
3) For polled reads:
A. The USBA framework accepts a request which
specifies the size and number of packets to fill
with data. The packets get filled one packet per
(1 ms) frame/(125 us) microframe. All requests
have an implicit USBATRSHORTXFEROK attribute
set, since transfers continue in spite of any en-
countered. The amount of data read per packet will
match the isocpktlength field of the packet
descriptor unless a short transfer occurs. The
actual size is returned in the
isocpktactuallength field of the packet
descriptor. When all packets of the request have
been processed, a normal callback is done to sig-
nal the completion of the original request.
B. When continuous polling is stopped, the original
request is returned in an exception callback with a
completion reason of USBCRSTOPEDPOLING.
(NOTE: Polling can be restarted from an exception
callback corresponding to an original request.
Please see usbpipeisocxfer(9F) for more information.
C. Callbacks must be specified.
The isoccompletionreason indicates the status of the transfer. See
usbcompletionreason(9s) for usbcrt definitions.
The isoccbflags 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. Please see
usbcallbackflags(9s) for a description of use and operation.
SunOS 5.11 Last change: 28 Dec 2006 4
Data Structures for Drivers usbisocrequest(9S)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusbu
SEE ALSO
attributes(5), usballocrequest(9F),
usbgetcurrentframenumber(9F),
usbgetmaxpktsperisocrequest(9F),
usbpipebulkxfer(9F), usbpipectrlxfer(9F),
usbpipeintrxfer(9F), usbpipeisocxfer(9F),
usbbulkrequest(9S), usbcallbackflags(9S),
usbcompletionreason(9S), usbctrlrequest(9S),
usbintrrequest(9S), usbrequestattributes(9S)
SunOS 5.11 Last change: 28 Dec 2006 5
|
