Kernel Functions for Drivers usb_pipe_open(9F)
NAME
usb_pipe_open - Open a USB pipe to a device
SYNOPSIS
#include
int usb_pipe_open(dev_info_t *dip, usb_ep_descr_t *endpoint,
usb_pipe_policy_t *pipe_policy,
usb_flags_t flags, usb_pipe_handle_t *pipe_handle);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)PARAMETERS
dip Pointer to the device's dev_info structure.
endpoint Pointer to endpoint descriptor.pipe_policy Pointer to pipe_policy. pipe_policy provides
hints on pipe usage.flags USB_FLAGS_SLEEP is only flag that is recog-
nized. Wait for memory resources if not immediately available.pipe_handle 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 usb_pipe_open() 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 getapproximately 10% of frame time and will
get more if needed and if available, butSunOS 5.11 Last change: 5 Jan 2004 1
Kernel Functions for Drivers usb_pipe_open(9F)
there is no guarantee on transfer promptness. Bidirectional.Bulk pipe Used for large, reliable, non-time-
critical data transfers. These get thebus 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 retriesof failed transfers. Interrupt and iso-
chronous data are together guaranteed90% 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 thatpipe's endpoint descriptor. (See usb_ep_descr(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. Adequate bandwidth during transfers is guaranteed for all periodic pipes which are opened successfully. Interrupt andSunOS 5.11 Last change: 5 Jan 2004 2
Kernel Functions for Drivers usb_pipe_open(9F)
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 thedevice speed. Unallocated bandwidth remaining for new dev-
ices depends on the bandwidth already allocated for previ-
ously opened periodic pipes.The pipe_policy parameter provides a hint as to pipe usage
and must be specified. It is a usb_pipe_policy_t which con-
tains the following fields:uchar_t pp_max_async_reqs:
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:usb_pipe_close(9F)
usb_set_cfg(9F)
usb_set_alt_if(9F)
usb_clr_feature(9F)
usb_pipe_reset(9F)
usb_pipe_drain_reqs(9F)
usb_pipe_stop_intr_polling(9F)
usb_pipe_stop_isoc_polling(9F)
Setting to too small a value can deadlock the pipe. * Asynchronous calls are calls madewithout the USB_FLAGS_SLEEP 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 usb_pipe_open(9F)
The control pipe to the default endpoints (endpoints for both directions with addr 0, sometimes called the defaultcontrol pipe or default pipe) comes pre-opened by the hub. A
client driver receives the default control pipe handlethrough usb_get_dev_data(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 pipe_handle argument points to an opaque
handle of the opened pipe. On failure, it is set to NULL.RETURN VALUES
USB_SUCCESS Open succeeded.
USB_NO_RESOURCES Insufficient resources were avail-
able.USB_NO_BANDWIDTH Insufficient bandwidth available.
(isochronous and interrupt pipes).USB_INVALID_CONTEXT Called from interrupt handler with
USB_FLAGS_SLEEP set.
USB_INVALID_ARGS dip and/or pipe_handle is NULL.
Pipe_policy is NULL.
USB_INVALID_PERM Endpoint is NULL, signifying the
default control pipe. A clientdriver cannot open the default con-
trol pipe.USB_NOT_SUPPORTED Isochronous or interrupt endpoint
with maximum packet size of zero is not supported.USB_HC_HARDWARE_ERROR Host controller is in an error
state.SunOS 5.11 Last change: 5 Jan 2004 4
Kernel Functions for Drivers usb_pipe_open(9F)
USB_FAILURE Pipe is already open. Host con-
troller not in an operationalstate. Polling interval (ep_descr
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 theUSB_FLAGS_SLEEP option is not set.
EXAMPLES
usb_ep_data_t *ep_data;
usb_pipe_policy_t policy;
usb_pipe_handle_t pipe;
usb_client_dev_data_t *reg_data;
uint8_t interface = 1;
uint8_t alternate = 1;
uint8_t first_ep_number = 0;
/* Initialize pipe policy. */bzero(policy, sizeof(usb_pipe_policy_t));
policy.pp_max_async_requests = 2;
/* Get tree of descriptors for device. */if (usb_get_dev_data(
dip, USBDRV_VERSION, ®_data, USB_FLAGS_ALL_DESCR, 0) !=
USB_SUCCESS) {
... }/* Get first interrupt-IN endpoint. */
ep_data = usb_lookup_ep_data(dip, reg_data, interface, alternate,
first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN);
if (ep_data == NULL) {
... } /* Open the pipe. Get handle to pipe back in 5th argument. */if (usb_pipe_open(dip, &ep_data.ep_descr
&policy, USB_FLAGS_SLEEP, &pipe) != USB_SUCCESS) {
... }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 5 Jan 2004 5
Kernel Functions for Drivers usb_pipe_open(9F)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | PCI-based systems |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| Availability | driver/usb ||_____________________________|_____________________________|
SEE ALSO
attributes(5), usb_get_alt_if(9F), usb_get_cfg(9F),
usb_get_status(9F), usb_get_dev_data(9F),
usb_pipe_bulk_xfer(9F), usb_pipe_ctrl_xfer(9F),
usb_pipe_close(9F), usb_pipe_get_state(9F),
usb_pipe_intr_xfer(9F), usb_pipe_isoc_xfer(9F),
usb_pipe_reset(9F), usb_pipe_set_private(9F),
usb_ep_descr(9S), usb_callback_flags(9S)
SunOS 5.11 Last change: 5 Jan 2004 6