te
Copyright (c) 2004, 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_cfg, usb_set_cfg - Get and set current USB device configuration

#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);

illumos DDI specific (illumos DDI) For usb_get_cfg(): dip cfgval flags

For usb_set_cfg(): dip

cfg_index flags callback callback_arg 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.

For usb_get_cfg(): USB_SUCCESS USB_INVALID_ARGS USB_FAILURE

For usb_set_cfg(): USB_SUCCESS

USB_INVALID_ARGS USB_INVALID_CONTEXT USB_INVALID_PERM USB_BUSY USB_INVALID_PIPE USB_FAILURE 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.

 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 {
 ...
 ...
 }

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

ATTRIBUTE TYPE ATTRIBUTE VALUE

Architecture PCI-based systems

Interface stability Committed

attributes (7), usb_get_alt_if (9F), usb_get_dev_data (9F), usb_get_string_descr (9F), usb_pipe_xopen (9F), usb_callback_flags (9S), usb_cfg_descr (9S), usb_ep_descr (9S), usb_if_descr (9S)