Kernel Functions for Drivers usb_get_alt_if(9F)
NAME
usb_get_alt_if, usb_set_alt_if, usb_get_if_number,
usb_owns_device - Get and set alternate interface values
SYNOPSIS
#include
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);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI)PARAMETERS
For usb_get_alt_if():
dip Pointer to device's dev_info structure.
interface_number Interface of the desired alternate.
alternate_number Address where current alternate setting
is returned. flags No flags are recognized. Reserved for future expansion.For usb_set_alt_if():
dip Pointer to device's dev_info structure.
interface_number Interface of the desired alternate.
SunOS 5.11 Last change: 29 Dec 2006 1
Kernel Functions for Drivers usb_get_alt_if(9F)
alternate_number Alternate interface number to be set.
flags Only USB_FLAGS_SLEEP is recognized. Wait
for completion and do not call callback.callback Callback handler to notify of asynchro-
nous completion.callback_arg Second argument passed to callback
handler.For usb_get_if_number():
dip Pointer to device's dev_info structure.
For usb_owns_device():
dip Pointer to device's dev_info structure.
DESCRIPTION
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 ker-
nel 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.SunOS 5.11 Last change: 29 Dec 2006 2
Kernel Functions for Drivers usb_get_alt_if(9F)
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, thedriver must be bound to: the entire device, the interface-
association which includes the alternative interface, or tothe 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 immedi-
ately and calls the callback handler when completed. callback is the asynchronous callback handler and takes the following arguments:usb_pipe_handle_t pipe_handle
Handle of the default control pipe used to perform the request.usb_opaque_t callback_arg
Callback_arg specified to usb_set_alt_if().
int rval Request status.usb_cb_flags_t callback_flags:
Status of the queueing operation. Can be:USB_CB_NO_INFO - Callback was uneventful.
USB_CB_ASYNC_REQ_FAILED - Error queueing request.
USB_CB_NO_RESOURCES - Error allocating resources.
The usb_get_if_number() function returns the interface
number, or USB_COMBINED_NODE or USB_DEVICE_NODE node indi-
cating that the driver is bound to the entire device.SunOS 5.11 Last change: 29 Dec 2006 3
Kernel Functions for Drivers usb_get_alt_if(9F)
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.RETURN VALUES
For usb_get_alt_if():
USB_SUCCESS Interface's alternate setting was
successfully obtained.USB_INVALID_ARGS Pointer to alternate_number and/or
dip are NULL.USB_INVALID_CONTEXT Called from interrupt context.
USB_FAILURE The interface number is invalid.
An access error occurred.For usb_set_alt_if():
USB_SUCCESS Alternate interface was successfully
set.USB_INVALID_ARGS dip is NULL. USB_FLAGS_SLEEP is clear
and callback is NULL.USB_INVALID_PERM dip does not own the interface to be
set.USB_INVALID_CONTEXT Called from interrupt context with
USB_FLAGS_SLEEP specified.
USB_INVALID_PIPE Pipe handle is NULL, invalid, or
refers to a pipe that is closing or closed.USB_FAILURE The interface number and/or alternate
setting are invalid. Pipes were open.SunOS 5.11 Last change: 29 Dec 2006 4
Kernel Functions for Drivers usb_get_alt_if(9F)
An access error occurred.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 Driver of the dip argument owns the entire dev-
ice.B_FALSE Driver of the dip argument owns only the current
interface.CONTEXT
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 contextonly 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. Seeusb_callback_flags(9S) for more information on callbacks.
The usb_get_alt_if() function may be called from user or
kernel context.EXAMPLES
/* 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,
SunOS 5.11 Last change: 29 Dec 2006 5
Kernel Functions for Drivers usb_get_alt_if(9F)
"%s%d: Error setting alternate setting on pipe",
ddi_driver_name(dip), ddi_get_instance(dip));
} }ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | PCI-based systems |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| Availability | driver/usb ||_____________________________|_____________________________|
SEE ALSO
attributes(5), usb_pipe_ctrl_xfer(9F), usb_get_dev_data(9F),
usb_get_string_descr(9F), usb_get_cfg(9F)
SunOS 5.11 Last change: 29 Dec 2006 6