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]
usb_get_alt_if, usb_set_alt_if, usb_get_if_number, usb_owns_device - Get and set alternate interface values

#include <sys/usb/usba.h>



int usb_get_alt_if(dev_info_t *dip, uint_t interface_number,
 uint_t *alternate_number, usb_flags_t flags);

int usb_set_alt_if(dev_info_t *dip, uint_t interface_number, 
 uint_t alternate_number, usb_flags_t flags, 
 void (*callback)(usb_pipe_handle_t pipe_handle,
 usb_opaque_t callback_arg, int rval, usb_cb_flags_t flags), 
 usb_opaque_t callback_arg);

int usb_get_if_number(dev_info_t *dip);

boolean_t usb_owns_device(dev_info_t *dip);

Solaris DDI specific (Solaris DDI)

For usb_get_alt_if():

dip

interface_number

alternate_number

flags

For usb_set_alt_if():

dip

interface_number

alternate_number

flags

callback

callback_arg

For usb_get_if_number():

dip

For usb_owns_device():

dip

USB devices can have multiple configurations, each with many interfaces. Within interfaces are alternate settings, and within alternate settings are endpoints.

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.

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.

The usb_get_alt_if() function requests the device to return the current alternate setting of the given interface. This function ignores the flags argument and always blocks.

The usb_set_alt_if() 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 interface_number.

If USB_FLAGS_SLEEP is set in flags, usb_set_alt_if() blocks until completed. Otherwise, usb_set_alt_if() returns immediately and calls the callback handler when completed.

callback is the asynchronous callback handler and takes the following arguments:

usb_pipe_handle_t pipe_handle

usb_opaque_t callback_arg

int rval

usb_cb_flags_t callback_flags:

The usb_get_if_number() function returns the interface number, or USB_COMBINED_NODE or USB_DEVICE_NODE node indicating that the driver is bound to the entire device.

The usb_owns_device() function returns B_TRUE if the driver of the dip argument owns the entire device, or B_FALSE if it owns just a particular interface.

For usb_get_alt_if():

USB_SUCCESS

USB_INVALID_ARGS

USB_INVALID_CONTEXT

USB_FAILURE

For usb_set_alt_if():

USB_SUCCESS

USB_INVALID_ARGS

USB_INVALID_PERM

USB_INVALID_CONTEXT

USB_INVALID_PIPE

USB_FAILURE

For usb_get_if_number():

USB_COMBINED_NODE if the driver is responsible for the entire active device configuration. The dip doesn't correspond to an entire physical device.

USB_DEVICE_NODE if the driver is responsible for the entire device. The dip corresponds to an entire physical device.

interface number: otherwise.

For usb_owns_device():

B_TRUE

B_FALSE

The usb_get_if_number() and usb_owns_device() functions may be called from user or kernel context.

The usb_set_alt_if() function may always be called from user or kernel context. It may be called from interrupt context only if USB_FLAGS_SLEEP is not set in flags. If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if supplied, can block because it is executing in kernel context. Otherwise the callback cannot block. See usb_callback_flags(9S) for more information on callbacks.

The usb_get_alt_if() function may be called from user or kernel context.

/* 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));
 }
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Architecture	PCI-based systems
Interface stability	Committed

attributes(5), usb_pipe_ctrl_xfer(9F), usb_get_dev_data(9F), usb_get_string_descr(9F), usb_get_cfg(9F)