USB_GET_ALT_IF(9F)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 <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);
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 expan‐
sion.
For usb_set_alt_if():
dip
Pointer to device's dev_info structure.
interface_number
Interface of the desired alternate.
alternate_number
Alternate interface number to be set.
flags
Only USB_FLAGS_SLEEP is recognized. Wait for com‐
pletion and do not call callback.
callback
Callback handler to notify of asynchronous comple‐
tion.
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 inter‐
faces. 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 deter‐
mined 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 opera‐
tion as seen by the system, the driver must insure that all pipes other
than the default control pipe are closed and quiescent. To avoid con‐
tending 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 com‐
pleted. 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
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 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 particu‐
lar 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 call‐
back 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.
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 device.
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 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 can‐
not block. See usb_callback_flags(9S) for more information on call‐
backs.
The usb_get_alt_if() function may be called from user or kernel con‐
text.
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,
"%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 attributes:
┌────────────────────┬───────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼───────────────────┤
│Architecture │ PCI-based systems │
├────────────────────┼───────────────────┤
│Interface stability │ Committed │
└────────────────────┴───────────────────┘
SEE ALSOattributes(5), usb_pipe_ctrl_xfer(9F), usb_get_dev_data(9F),
usb_get_string_descr(9F), usb_get_cfg(9F)
Dec 29, 2006 USB_GET_ALT_IF(9F)
