Kernel Functions for Drivers usbpipeisocxfer(9F)
NAME
usbpipeisocxfer, usbpipestopisocpolling - USB iso-
chronous transfer and polling functions
SYNOPSIS
#include
int usbpipeisocxfer(usbpipehandlet pipehandle, usbisocreqt *request,
usbflagst flags);
void usbpipestopisocpolling(usbpipehandlet pipehandle, usbflagst flags);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
For usbpipeisocxfer():
pipehandle Isochronous pipe handle on which request is
made.
request Pointer to isochronous transfer request.
flags USBFLAGSLEP is the only flag recognized.
Wait for needed resources if unavailable.
For usbpipestopisocpolling():
pipehandle Isochronous pipe handle on which to stop pol-
ling for input.
flags USBFLAGSLEP is the only flag recognized.
Wait for polling to stop.
DESCRIPTION
The usbpipeisocxfer() function requests the USBA frame-
work to perform a transfer through a USB isochronous
pipe. The request is passed to the host controller driver
(HCD), which performs the necessary transactions to complete
the request.
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbpipeisocxfer(9F)
By their nature, isochronous transfers require several tran-
sactions for completion. Each request may contain several
packet descriptors. Descriptors correspond to subtransfers
to be made in different frames. A request is deemed com-
pleted once all packets of that request have been processed.
It is illegal to specify the USBATRSONEXFER attribute in
an isochronous request. The isochronous polling interval is
always one millisecond, the period of a full-speed frame.
All isochronous requests are asynchronous, and will notify
the caller of their completion via a callback function.
All isochronous requests must specify normal and exception
callback handlers.
Requests will wait for needed, unavailable resources when
USBFLAGSLEP has been specified in flags. Requests made
without USBFLAGSLEP set will fail if needed resources
are not readily available.
No errors seen during request processing will result in
aborted transfers or exception callbacks. Such errors will
instead be logged in the packet descriptor's isocpktstatus
field. These errors can be examined when the completed
request is returned through a normal callback.
Isochronous-OUT TRANSFERS
Allocate room for data when allocating isochronous-OUT
requests via usballocisocreq(9F), by passing a positive
value for the len argument. The data will be divided
among the request transactions, each transaction represented
by a packet descriptor. (See usbisocrequest(9F). When all
of the data has been sent, regardless of any errors encoun-
tered, a normal transfer callback will be made to notify
the client driver of completion.
If a request is submitted while other requests are active or
queued, and the new request has its USBATRSISOCXFERASAP
attribute set, the host controller driver will queue the
request to start on a frame which immediately follows the
last frame of the last queued request.
Isochronous-IN TRANSFERS
All isochronous-IN transfers start background polling, and
require only a single (original) request. The USBA frame-
work will allocate a new request each time polling has new
data to return. Specify a zero length when calling
usballocisocreq() to allocate the original request, since
it will not be used to return data. Set the
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbpipeisocxfer(9F)
isocpktslength in the request to specify how much data to
poll per interval (the length of one packet in the request).
The original request passed to usbpipeisocxfer() will be
used to return status when polling termination is requested,
or for error condition notification. There can be only one
isochronous-IN request submitted at a time.
CALBACKS
Isochronous transfer normal-completion callbacks cannot
block for any reason since they are called from interrupt
context. They will have USBCBINTRCONTEXT set in their
callback flags to note this.
Isochronous exception callbacks have the following restric-
tions for blocking:
1. They can block for resources (for example to allo-
cate memory).
2. They cannot block for synchronous completion of a
command (for example usbpipeclose(9F)) done on
the same pipe. Asynchronous commands can be
started, when the pipe's policy ppmaxasyncreqs
field is initialized to accommodate them.
3. They cannot block waiting for another callback to
complete.
4. They cannot block waiting for a synchronous
transfer request to complete. They can, however,
make an asynchronous request (such as restarting
polling with a new isochronous-IN transfer).
Please see the section on callbacks in
usbcallbackflags(9S) for more information.
All isochronous transfer exception callbacks signify that
polling has stopped. Polling requests are returned with the
following completion reasons:
USBCRSTOPEDPOLING
USBCRPIPECLOSING
Note: There are no exception callbacks for error conditions.
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbpipeisocxfer(9F)
The usbpipestopisocpolling() function terminates polling
on an isochronous-IN pipe. The usbpipestopisocpolling()
function does the following:
1. Cease polling.
2. Allow any requests-in-progress to complete and be
returned to the client driver through the normal
callback mechanism.
3. Idle the pipe.
4. Return the original polling request to the client
driver through an exception callback with a comple-
tion reason of USBCRSTOPEDPOLING.
RETURN VALUES
For usbpipeisocxfer():
USBSUCES Transfer was successful.
USBINVALIDARGS Request is NUL.
USBINVALIDCONTEXT Called from interrupt context
with the USBFLAGSLEP flag
set.
USBINVALIDREQUEST The request has been freed or
otherwise invalidated.
A set of conflicting attributes
were specified. See
usbisocrequest(9S).
The normal and/or exception
callback was NUL,
USBFLAGSLEP was not set and
USBATRSONEXFER was not set.
An isochronous request was speci-
fied with a zeroed
isocpktdescr, a NUL
isocpktdescr, or a NUL data
argument.
An isochronous request was speci-
fied with
USBATRSISOCXFERASAP and a
nonzero isocframeno.
SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usbpipeisocxfer(9F)
USBNOFRAMENUMBER An isochronous request was not
specified with one and only one
of USBATRSISOCSTARTFRAME or
USBATRSISOCXFERASAP speci-
fied.
An isochronous request was
specified with
USBATRSISOCSTARTFRAME and a
zero isocframeno.
USBINVALIDSTARTFRAME An isochronous request was speci-
fied with an invalid starting
frame number (less than current
frame number, or zero) and
USBATRSISOCSTARTFRAME speci-
fied.
USBINVALIDPIPE Pipe handle is NUL or invalid.
Pipe is closing or closed.
USBPIPEROR Pipe handle refers to a pipe
which is in the
USBPIPESTATEROR state.
USBNORESOURCES Memory, descriptors or other
resources unavailable.
USBHCHARDWAREROR Host controller is in error
state.
USBFAILURE An asynchronous transfer failed
or an internal error occurred.
An isoch request requested too much data:
(length > (usbgetmaxpktsperisocrequest() *
endpoint's wMaxPacketSize))
The pipe is in an unsuitable
state (error, busy, not ready).
Additional status information may be available in the
isoccompletionreason and isoccbflags fields of the
SunOS 5.11 Last change: 5 Jan 2004 5
Kernel Functions for Drivers usbpipeisocxfer(9F)
request. Please see usbcompletionreason(9S) and
usbcallbackflags(9S) for more information.
For usbpipestopisocpolling():
None, but will fail if called with USBFLAGSLEP specified
from interrupt context; the pipe handle is invalid, NUL or
pertains to a closing or closed pipe; or the pipe is in an
error state. Messages regarding these errors will be logged
to the console logfile.
CONTEXT
Both of these functions may be called from kernel or user
context without regard to arguments. May be called from
interrupt context only when the USBFLAGSLEP flag is
clear.
EXAMPLES
/* Start polling on an isochronous-IN pipe. */
usbisocreqt isocreq;
void isocpipecallback(usbpipehandlet, usbisocreqt*);
void isocpipeexceptioncallback(
usbpipehandlet, usbisocreqt*);
uintt pktsize;
usbepdatat *isoceptreenode;
usbepdescrt *isocepdescr = ...; /* From usblookupepdata() */
isocepdescr = &isoceptreenode->epdescr;
pktsize = isocepdescr->wMaxPacketSize;
isocreq = usballocisocreq(
dip, numpkts, NUMPKTS * pktsize, USBFLAGSLEP);
...
...
isocreq->isocattributes = USBATRSISOCXFERASAP;
...
...
isocreq->isoccb = isocpipecallback;
isocreq->isocexccb = isocpipeexceptioncallback;
...
...
isocreq->isocpktslength = pktsize;
isocreq->isocpktscount = NUMPKTS;
for (pkt = 0; pkt < NUMPKTS; pkt]) {
isocreq->isocpktdescr[pkt].isocpktlength = pktsize;
}
if ((rval = usbpipeisocxfer(pipe, isocreq, USBFLAGSNOSLEP))
!= USBSUCES) {
SunOS 5.11 Last change: 5 Jan 2004 6
Kernel Functions for Drivers usbpipeisocxfer(9F)
cmnerr (CEWARN,"%s%d: Error starting isochronous pipe polling.",
ddidrivername(dip), ddigetinstance(dip));
}
-------
/* Stop polling before powering off device. Wait for polling to stop. */
usbpipestopisocpolling(pipe, USBFLAGSLEP);
pmidlecomponent(dip, 0);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Evolving
Availability SUNWusb
SEE ALSO
attributes(5), usballocrequest(9F),
usbgetcurrentframenumber(9F), usbgetcfg(9F),
usbgetmaxpktsperisocrequest(9F), usbgetstatus(9F),
usbpipebulkxfer(9F), usbpipectrlxfer(9F),
usbpipegetstate(9F), usbpipeintrxfer(9F),
usbpipeopen(9F), usbpipereset(9F), usbbulkrequest(9S),
usbcallbackflags(9S), usbcompletionreason(9S),
usbctrlrequest(9S), usbepdescr(9S),
usbintrrequest(9S), usbisocrequest(9S)
SunOS 5.11 Last change: 5 Jan 2004 7
|
