Kernel Functions for Drivers usbpipeopen(9F)
NAME
usbpipeopen - Open a USB pipe to a device
SYNOPSIS
#include
int usbpipeopen(devinfot *dip, usbepdescrt *endpoint,
usbpipepolicyt *pipepolicy,
usbflagst flags, usbpipehandlet *pipehandle);
INTERFACE LEVEL
Solaris DI specific (Solaris DI)
PARAMETERS
dip Pointer to the device's devinfo structure.
endpoint Pointer to endpoint descriptor.
pipepolicy Pointer to pipepolicy. pipepolicy provides
hints on pipe usage.
flags USBFLAGSLEP is only flag that is recog-
nized. Wait for memory resources if not
immediately available.
pipehandle Address to where new pipe handle is returned.
(The handle is opaque.)
DESCRIPTION
A pipe is a logical connection to an endpoint on a USB dev-
ice. The usbpipeopen() function creates such a logical
connection and returns an initialized handle which refers to
that connection.
The USB 2.0 specification defines four endpoint types, each
with a corresponding type of pipe. Each of the four types of
pipes uses its physical connection resource differently.
They are:
Control pipe Used for bursty, non-periodic, reliable,
host-initiated request/response communi-
cation, such as for command/status
operations. These are guaranteed to get
SunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usbpipeopen(9F)
approximately 10% of frame time and will
get more if needed and if available, but
there is no guarantee on transfer
promptness. Bidirectional.
Bulk pipe Used for large, reliable, non-time-
critical data transfers. These get the
bus on a bandwidth-available basis. Uni-
directional. Sample uses include printer
data.
Interrupt pipe Used for sending or receiving small
amounts of reliable data infrequently
but with bounded service periods, as for
interrupt handling. Unidirectional.
Isochronous pipe Used for large, unreliable, time-
critical data transfers. Boasts a
guaranteed constant data rate as long as
there is data, but there are no retries
of failed transfers. Interrupt and iso-
chronous data are together guaranteed
90% of frame time as needed. Unidirec-
tional. Sample uses include audio.
The type of endpoint to which a pipe connects (and therefore
the pipe type) is defined by the bmAttributes field of that
pipe's endpoint descriptor. (See usbepdescr(9S)). Opens to
interrupt and isochronous pipes can fail if the required
bandwidth cannot be guaranteed.
The polling interval for periodic (interrupt or isochronous)
pipes, carried by the endpoint argument's bInterval field,
must be within range. Valid ranges are:
Full speed: range of 1-255 maps to 1-255 ms.
Low speed: range of 10-255 maps to 10-255 ms.
High speed: range of 1-16 maps to (2**(bInterval-1)) *
125us.
SunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usbpipeopen(9F)
Adequate bandwidth during transfers is guaranteed for all
periodic pipes which are opened successfully. Interrupt and
isochronous pipes have guaranteed latency times, so
bandwidth for them is allocated when they are opened.
(Please refer to Sections 5.7 and 5.8 of the USB 2.0 specif-
ication which address isochronous and interrupt transfers.)
Opens of interrupt and isochronous pipes fail if inadequate
bandwidth is available to support their guaranteed latency
time. Because periodic pipe bandwidth is allocated on pipe
open, open periodic pipes only when needed.
The bandwidth required by a device varies based on polling
interval, the maximum packet size (wMaxPacketSize) and the
device speed. Unallocated bandwidth remaining for new dev-
ices depends on the bandwidth already allocated for previ-
ously opened periodic pipes.
The pipepolicy parameter provides a hint as to pipe usage
and must be specified. It is a usbpipepolicyt which con-
tains the following fields:
uchart ppmaxasyncreqs:
A hint indicating how many
asynchronous operations requiring
their own kernel thread will be
concurrently in progress, the highest
number of threads ever needed at one
time. Allow at least one for
synchronous callback handling and as
many as are needed to accommodate the
anticipated parallelism of asynchronous*
calls to the following functions:
usbpipeclose(9F)
usbsetcfg(9F)
usbsetaltif(9F)
usbclrfeature(9F)
usbpipereset(9F)
usbpipedrainreqs(9F)
usbpipestopintrpolling(9F)
usbpipestopisocpolling(9F)
Setting to too small a value can
deadlock the pipe.
* Asynchronous calls are calls made
without the USBFLAGSLEP flag being
passed. Note that a large number of
callbacks becomes an issue mainly when
blocking functions are called from
callback handlers.
SunOS 5.11 Last change: 5 Jan 2004 3
Kernel Functions for Drivers usbpipeopen(9F)
The control pipe to the default endpoints (endpoints for
both directions with addr 0, sometimes called the default
control pipe or default pipe) comes pre-opened by the hub. A
client driver receives the default control pipe handle
through usbgetdevdata(9F). A client driver cannot open
the default control pipe manually. Note that the same con-
trol pipe may be shared among several drivers when a device
has multiple interfaces and each interface is operated by
its own driver.
All explicit pipe opens are exclusive; attempts to open an
opened pipe fail.
On success, the pipehandle argument points to an opaque
handle of the opened pipe. On failure, it is set to NUL.
RETURN VALUES
USBSUCES Open succeeded.
USBNORESOURCES Insufficient resources were avail-
able.
USBNOBANDWIDTH Insufficient bandwidth available.
(isochronous and interrupt pipes).
USBINVALIDCONTEXT Called from interrupt handler with
USBFLAGSLEP set.
USBINVALIDARGS dip and/or pipehandle is NUL.
Pipepolicy is NUL.
USBINVALIDPERM Endpoint is NUL, signifying the
default control pipe. A client
driver cannot open the default con-
trol pipe.
USBNOTSUPORTED Isochronous or interrupt endpoint
with maximum packet size of zero is
not supported.
USBHCHARDWAREROR Host controller is in an error
state.
SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usbpipeopen(9F)
USBFAILURE Pipe is already open. Host con-
troller not in an operational
state. Polling interval (epdescr
bInterval field) is out of range
(intr or isoc pipes).
CONTEXT
May be called from user or kernel context regardless of
arguments. May also be called from interrupt context if the
USBFLAGSLEP option is not set.
EXAMPLES
usbepdatat *epdata;
usbpipepolicyt policy;
usbpipehandlet pipe;
usbclientdevdatat *regdata;
uint8t interface = 1;
uint8t alternate = 1;
uint8t firstepnumber = 0;
/* Initialize pipe policy. */
bzero(policy, sizeof(usbpipepolicyt));
policy.ppmaxasyncrequests = 2;
/* Get tree of descriptors for device. */
if (usbgetdevdata(
dip, USBDRVERSION, ®data, USBFLAGSALDESCR, 0) !=
USBSUCES) {
...
}
/* Get first interrupt-IN endpoint. */
epdata = usblookupepdata(dip, regdata, interface, alternate,
firstepnumber, USBEPATRINTR, USBEPDIRIN);
if (epdata == NUL) {
...
}
/* Open the pipe. Get handle to pipe back in 5th argument. */
if (usbpipeopen(dip, &epdata.epdescr
&policy, USBFLAGSLEP, &pipe) != USBSUCES) {
...
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jan 2004 5
Kernel Functions for Drivers usbpipeopen(9F)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture PCI-based systems
Interface stability Committed
Availability SUNWusb
SEE ALSO
attributes(5), usbgetaltif(9F), usbgetcfg(9F),
usbgetstatus(9F), usbgetdevdata(9F),
usbpipebulkxfer(9F), usbpipectrlxfer(9F),
usbpipeclose(9F), usbpipegetstate(9F),
usbpipeintrxfer(9F), usbpipeisocxfer(9F),
usbpipereset(9F), usbpipesetprivate(9F),
usbepdescr(9S), usbcallbackflags(9S)
SunOS 5.11 Last change: 5 Jan 2004 6
|
