Tribblix: manual page: usb_get

USB_GET_CFG(9F) Kernel Functions for Drivers USB_GET_CFG(9F)

NAME

usb_get_cfg, usb_set_cfg - Get and set current USB device
configuration

SYNOPSIS

#include <sys/usb/usba.h>

int usb_get_cfg(dev_info_t *dip, uint_t cfgval, usb_flags_t flags);

int usb_set_cfg(dev_info_t *dip, uint_t cfg_index, 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);

INTERFACE LEVEL

illumos DDI specific (illumos DDI)

PARAMETERS

For usb_get_cfg():

dip
Pointer to device's dev_info structure.

cfgval
Pointer to returned configuration value.

flags
Not used. Always waits for completion.

For usb_set_cfg():

dip
Pointer to device's dev_info structure.

cfg_index
Desired device configuration index. Set to
USB_DEV_DEFAULT_CONFIG_INDEX to restore default
configuration.

flags
Only USB_FLAGS_SLEEP is recognized. Wait for
completion and do not call callback.

callback
Callback handler to notify of asynchronous
completion.

callback_arg
Second argument passed to callback handler.

DESCRIPTION

The usb_get_cfg() function retrieves the current configuration. It
ignores the flags argument and always blocks while contacting the
device.

The usb_set_cfg() function sets a new configuration. Because this
call changes the device's mode of operation, the device must be
quiescent and have all pipes, with the exception of the default
control pipe, closed. The driver must have control over the entire
device and cannot own just a single interface on a composite device.
Additionally, its device node must not be a parent to other device
nodes that can be operated by other drivers. The driver must own the
device exclusively, otherwise drivers managing other parts of the
device would be affected without their knowledge or control.

This call updates all internal USBA framework data structures,
whereas issuing a raw USB_REQ_SET_CFG device request does not. The
usb_set_cfg() function is the only supported programmatic way to
change device configuration.

This call blocks if USB_FLAGS_SLEEP is set in flags. It returns
immediately and calls the callback on completion if USB_FLAGS_SLEEP
is not set.

RETURN VALUES

For usb_get_cfg():

USB_SUCCESS
New configuration is retrieved.

USB_INVALID_ARGS
cfgval or dip is NULL.

USB_FAILURE
Configuration cannot be retrieved.

For usb_set_cfg():

USB_SUCCESS
New configuration is set.

USB_INVALID_ARGS
dip is NULL.

USB_FLAGS_SLEEP is clear and callback is NULL.

USB_INVALID_CONTEXT
Called from interrupt context with
USB_FLAGS_SLEEP specified.

USB_INVALID_PERM
Caller does not own entire device or device is
a parent to child devices.

USB_BUSY
One or more pipes other than the default
control pipe are open on the device.

USB_INVALID_PIPE
Pipe handle is NULL or invalid, or pipe is
closing or closed.

USB_FAILURE
An illegal configuration is specified.

One or more pipes other than the default
control pipe are open on the device.

CONTEXT

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

The usb_set_cfg() function may be called from user or kernel context
always. 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. Please see
usb_callback_flags(9S) for more information on callbacks.

EXAMPLES

Setting the configuration to the one at index 1 (in the
array of usb_cfg_data_t configuration nodes as returned
by usb_get_dev_data()), and verifying what the configuration
is at that index. (See usb_get_dev_data(9F)).

uint_t cfg_index = 1;

/*
* Assume all pipes other than the default control pipe
* are closed and make sure all requests to the default
* control pipe have completed. /
*/

if (usb_set_cfg(dip, cfg_index, USB_FLAGS_SLEEP, NULL, 0)
!= USB_SUCCESS) {
cmn_err (CE_WARN,
"%s%d: Error setting USB device to configuration #%d",
ddi_driver_name(dip), ddi_get_instance(dip), cfg_index);
}

if (usb_get_cfg(dip, &bConfigurationValue, 0) == USB_SUCCESS) {
cmn_err (CE_WARN, "%s%d: USB device active configuration is %d",
ddi_driver_name(dip), ddi_get_instance(dip),
bConfigurationValue);
} else {
...
...
}

ATTRIBUTES