path: root/usr/src/man/man9f/usb_pipe_open.9f

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH USB_PIPE_OPEN 9F "Jan 5, 2004"
.SH NAME
usb_pipe_open \- Open a USB pipe to a device
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>



\fBint\fR \fBusb_pipe_open\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_ep_descr_t *\fR\fIendpoint\fR,
     \fBusb_pipe_policy_t *\fR\fIpipe_policy\fR,
\fBusb_flags_t\fR \fIflags\fR, \fBusb_pipe_handle_t *\fR\fIpipe_handle\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 15n
Pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIendpoint\fR\fR
.ad
.RS 15n
Pointer to endpoint descriptor.
.RE

.sp
.ne 2
.na
\fB\fIpipe_policy\fR\fR
.ad
.RS 15n
Pointer to \fIpipe_policy\fR. \fIpipe_policy\fR provides hints on pipe usage.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 15n
USB_FLAGS_SLEEP is only flag that is recognized. Wait for memory resources if
not immediately available.
.RE

.sp
.ne 2
.na
\fB\fIpipe_handle\fR\fR
.ad
.RS 15n
Address to where new pipe handle is returned. (The handle is opaque.)
.RE

.SH DESCRIPTION
.sp
.LP
A pipe is a logical connection to an endpoint on a USB device. The
\fBusb_pipe_open()\fR function creates such a logical connection and returns an
initialized handle which refers to that connection.
.sp
.LP
The \fIUSB 2.0\fR 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:
.sp
.ne 2
.na
\fBControl pipe\fR
.ad
.RS 20n
Used for bursty, non-periodic, reliable, host-initiated request/response
communication, such as for command/status operations. These are guaranteed to
get approximately 10% of frame time and will get more if needed and if
available, but there is no guarantee on transfer promptness. Bidirectional.
.RE

.sp
.ne 2
.na
\fBBulk pipe\fR
.ad
.RS 20n
Used for large, reliable, non-time-critical data transfers. These get the bus
on a bandwidth-available basis. Unidirectional. Sample uses include printer
data.
.RE

.sp
.ne 2
.na
\fBInterrupt pipe\fR
.ad
.RS 20n
Used for sending or receiving small amounts of reliable data infrequently but
with bounded service periods, as for interrupt handling. Unidirectional.
.RE

.sp
.ne 2
.na
\fBIsochronous pipe\fR
.ad
.RS 20n
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 isochronous data are together guaranteed 90% of frame
time as needed. Unidirectional. Sample uses include audio.
.RE

.sp
.LP
The type of endpoint to which a pipe connects (and therefore the pipe type) is
defined by the \fBbmAttributes\fR field of that pipe's endpoint descriptor.
(See \fBusb_ep_descr\fR(9S)). Opens to interrupt and isochronous pipes can fail
if the required bandwidth cannot be guaranteed.
.sp
.LP
The polling interval for periodic (interrupt or isochronous) pipes, carried by
the endpoint argument's bInterval field, must be within range. Valid ranges
are:
.sp
.LP
Full speed: range of 1-255 maps to 1-255 ms.
.sp
.LP
Low speed: range of 10-255 maps to 10-255 ms.
.sp
.LP
High speed: range of 1-16 maps to (2**(bInterval-1)) * 125us.
.sp
.LP
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 \fI5.7\fR and \fI5.8\fR of the \fIUSB 2.0\fR specification
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.
.sp
.LP
The bandwidth required by a device varies based on polling interval, the
maximum packet size (\fBwMaxPacketSize\fR) and the device speed. Unallocated
bandwidth remaining for new devices depends on the bandwidth already allocated
for previously opened periodic pipes.
.sp
.LP
The \fIpipe_policy\fR parameter provides a hint as to pipe usage and must be
specified. It is a \fBusb_pipe_policy_t\fR which contains the following fields:
.sp
.in +2
.nf
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 made
                    without 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.
.fi
.in -2

.sp
.LP
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 \fBusb_get_dev_data\fR(9F). A client driver cannot open the default
control pipe manually. Note that the same control pipe may be shared among
several drivers when a device has multiple interfaces and each interface is
operated by its own driver.
.sp
.LP
All explicit pipe opens are exclusive; attempts to open an opened pipe fail.
.sp
.LP
On success, the pipe_handle argument points to an opaque handle of the opened
pipe. On failure, it is set to NULL.
.SH RETURN VALUES
.sp
.ne 2
.na
\fBUSB_SUCCESS\fR
.ad
.RS 25n
Open succeeded.
.RE

.sp
.ne 2
.na
\fBUSB_NO_RESOURCES\fR
.ad
.RS 25n
Insufficient resources were available.
.RE

.sp
.ne 2
.na
\fBUSB_NO_BANDWIDTH\fR
.ad
.RS 25n
Insufficient bandwidth available. (isochronous and interrupt pipes).
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 25n
Called from interrupt handler with USB_FLAGS_SLEEP set.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 25n
dip and/or pipe_handle is NULL. Pipe_policy is NULL.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_PERM\fR
.ad
.RS 25n
Endpoint is NULL, signifying the default control pipe. A client driver cannot
open the default control pipe.
.RE

.sp
.ne 2
.na
\fBUSB_NOT_SUPPORTED\fR
.ad
.RS 25n
Isochronous or interrupt endpoint with maximum packet size of zero is not
supported.
.RE

.sp
.ne 2
.na
\fBUSB_HC_HARDWARE_ERROR\fR
.ad
.RS 25n
Host controller is in an error state.
.RE

.sp
.ne 2
.na
\fBUSB_FAILURE\fR
.ad
.RS 25n
Pipe is already open. Host controller not in an operational state. Polling
interval (\fBep_descr bInterval\fR field) is out of range (intr or isoc pipes).
.RE

.SH CONTEXT
.sp
.LP
May be called from user or kernel context regardless of arguments. May also be
called from interrupt context if the \fIUSB_FLAGS_SLEEP\fR option is not set.
.SH EXAMPLES
.sp
.in +2
.nf
    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, &reg_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) {
            ...
    }
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	PCI-based systems
_
Interface stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F),
\fBusb_get_status\fR(9F), \fBusb_get_dev_data\fR(9F),
\fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F),
\fBusb_pipe_close\fR(9F), \fBusb_pipe_get_state\fR(9F),
\fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F),
\fBusb_pipe_reset\fR(9F), \fBusb_pipe_set_private\fR(9F),
\fBusb_ep_descr\fR(9S), \fBusb_callback_flags\fR(9S)