'\" te
.\" Copyright (c) 2006 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_get_alt_if 9F "29 Dec 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_get_alt_if, usb_set_alt_if, usb_get_if_number, usb_owns_device \- Get and
set alternate interface values
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>



\fBint\fR \fBusb_get_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR,
     \fBuint_t *\fR\fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR);
.fi

.LP
.nf
\fBint\fR \fBusb_set_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR, 
     \fBuint_t\fR \fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR, 
     \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR,
     \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags\fR), 
     \fBusb_opaque_t\fR \fIcallback_arg\fR);
.fi

.LP
.nf
\fB\fR

\fBint\fR \fBusb_get_if_number\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

.LP
.nf
\fB\fR

\fBboolean_t\fR \fBusb_owns_device\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.LP
For \fBusb_get_alt_if()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 20n
.rt  
Pointer to device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinterface_number\fR\fR
.ad
.RS 20n
.rt  
Interface of the desired alternate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIalternate_number\fR\fR
.ad
.RS 20n
.rt  
Address where current alternate setting is returned.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 20n
.rt  
No flags are recognized. Reserved for future expansion.
.RE

.sp
.LP
For \fBusb_set_alt_if()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 20n
.rt  
Pointer to device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIinterface_number\fR\fR
.ad
.RS 20n
.rt  
Interface of the desired alternate.
.RE

.sp
.ne 2
.mk
.na
\fB\fIalternate_number\fR\fR
.ad
.RS 20n
.rt  
Alternate interface number to be set.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 20n
.rt  
Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call
callback.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcallback\fR\fR
.ad
.RS 20n
.rt  
Callback handler to notify of asynchronous completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcallback_arg\fR\fR
.ad
.RS 20n
.rt  
Second argument passed to callback handler.
.RE

.sp
.LP
For \fBusb_get_if_number()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 7n
.rt  
Pointer to device's \fBdev_info\fR structure.
.RE

.sp
.LP
For \fBusb_owns_device()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 7n
.rt  
Pointer to device's \fBdev_info\fR structure.
.RE

.SH DESCRIPTION
.sp
.LP
USB devices can have multiple configurations, each with many interfaces. Within
interfaces are alternate settings, and within alternate settings are endpoints.
.sp
.LP
Each interface within a configuration may be represented by the kernel as a
device node. Only one set of device nodes (interfaces as determined by the
configuration) can be active at one time.
.sp
.LP
Alternates to an interface represent different ways the kernel sees a device
node. Only one alternate setting within an interface can be active (or
selected) at one time.  The functions presented in this man page get or set
interface or alternate setting information.
.sp
.LP
The \fBusb_get_alt_if()\fR function requests the device to return the current
alternate setting of the given interface. This function ignores the flags
argument and always blocks.
.sp
.LP
The \fBusb_set_alt_if()\fR function requests the device to set the interface
and its alternate setting as specified. Because this call changes the current
device's interface and sets the new interface's mode of operation as seen by
the system, the driver must insure that all pipes other than the default
control pipe are closed and quiescent. To avoid contending with another driver
for a different part of the device, the driver must be bound to: the entire
device, the interface-association which includes the alternative interface, or
to the interface whose number is \fIinterface_number\fR.
.sp
.LP
If \fBUSB_FLAGS_SLEEP\fR is set in flags, \fBusb_set_alt_if()\fR blocks until
completed. Otherwise, \fBusb_set_alt_if()\fR returns immediately and calls the
callback handler when completed.
.sp
.LP
\fIcallback\fR is the asynchronous callback handler and takes the following
arguments:
.sp
.ne 2
.mk
.na
\fBusb_pipe_handle_t pipe_handle\fR
.ad
.sp .6
.RS 4n
Handle of the default control pipe used to perform the request.
.RE

.sp
.ne 2
.mk
.na
\fBusb_opaque_t callback_arg\fR
.ad
.sp .6
.RS 4n
Callback_arg specified to \fBusb_set_alt_if()\fR.
.RE

.sp
.ne 2
.mk
.na
\fBint rval\fR
.ad
.sp .6
.RS 4n
Request status.
.RE

.sp
.ne 2
.mk
.na
\fBusb_cb_flags_t callback_flags:\fR
.ad
.sp .6
.RS 4n
Status of the queueing operation. Can be:
.sp
USB_CB_NO_INFO - Callback was uneventful.
.sp
USB_CB_ASYNC_REQ_FAILED   -  Error queueing request.
.sp
USB_CB_NO_RESOURCES   -   Error allocating resources.
.RE

.sp
.LP
The \fBusb_get_if_number()\fR function returns the interface number, or
\fBUSB_COMBINED_NODE\fR or \fBUSB_DEVICE_NODE\fR node indicating that the
driver is bound to the entire device.
.sp
.LP
The \fBusb_owns_device()\fR function returns \fBB_TRUE\fR if the driver of the
dip  argument owns the entire device, or \fBB_FALSE\fR if it owns just a
particular interface.
.SH RETURN VALUES
.sp
.LP
For \fBusb_get_alt_if()\fR:
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 23n
.rt  
Interface's alternate setting was successfully obtained.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 23n
.rt  
Pointer to alternate_number and/or dip are NULL.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
.rt  
Called from interrupt context.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 23n
.rt  
The interface number is invalid.
.sp
An access error occurred.
.RE

.sp
.LP
For \fBusb_set_alt_if()\fR:
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 23n
.rt  
Alternate interface was successfully set.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 23n
.rt  
dip is NULL. USB_FLAGS_SLEEP is clear and callback is NULL.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PERM\fR
.ad
.RS 23n
.rt  
dip does not own the interface to be set.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
.rt  
Called from interrupt context with USB_FLAGS_SLEEP specified.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 23n
.rt  
Pipe handle is NULL, invalid, or refers to a pipe that is closing or closed.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 23n
.rt  
The interface number and/or alternate setting are invalid.
.sp
Pipes were open.
.sp
An access error occurred.
.RE

.sp
.LP
For \fBusb_get_if_number()\fR:
.sp
.LP
\fBUSB_COMBINED_NODE\fR if the driver is responsible for the entire active
device configuration. The \fBdip\fR doesn't correspond to an entire physical
device.
.sp
.LP
\fBUSB_DEVICE_NODE\fR if the driver is responsible for the entire device. The
\fIdip\fR corresponds to an entire physical device.
.sp
.LP
interface number: otherwise.
.sp
.LP
For \fBusb_owns_device()\fR:
.sp
.ne 2
.mk
.na
\fBB_TRUE\fR
.ad
.RS 11n
.rt  
Driver of the dip argument owns the entire device.
.RE

.sp
.ne 2
.mk
.na
\fBB_FALSE\fR
.ad
.RS 11n
.rt  
Driver of the dip argument owns only the current interface.
.RE

.SH CONTEXT
.sp
.LP
The \fBusb_get_if_number()\fR and \fBusb_owns_device()\fR functions may be
called from user or kernel context.
.sp
.LP
The \fBusb_set_alt_if()\fR function may always be called from user or kernel
context. It may be called from interrupt context only if \fBUSB_FLAGS_SLEEP\fR
is not set in flags. If the \fBUSB_CB_ASYNC_REQ_FAILED\fR bit is clear in
\fBusb_cb_flags_t\fR, the callback, if supplied, can block because it is
executing in kernel context. Otherwise the callback cannot block. See
\fBusb_callback_flags\fR(9S) for more information on callbacks.
.sp
.LP
The \fBusb_get_alt_if()\fR function may be called from user or kernel context.
.SH EXAMPLES
.sp
.in +2
.nf
/* Change alternate setting of interface 0.  Wait for completion. */
if (usb_set_alt_if(
    dip, 0, new_alternate_setting_num, USB_FLAGS_SLEEP, NULL, 0) !=
    USB_SUCCESS) {
        cmn_err (CE_WARN,
            "%s%d: Error setting alternate setting on pipe",
            ddi_driver_name(dip), ddi_get_instance(dip));
        }
}
.fi
.in -2

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
ArchitecturePCI-based systems
_
Interface stabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_get_dev_data\fR(9F),
\fBusb_get_string_descr\fR(9F), \fBusb_get_cfg\fR(9F)