path: root/usr/src/man/man9f/usb_get_cfg.9f

'\" 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]
.TH USB_GET_CFG 9F "Sep 16, 2016"
.SH NAME
usb_get_cfg, usb_set_cfg \- Get and set current USB device configuration
.SH SYNOPSIS
.nf
#include <sys/usb/usba.h>



\fBint\fR \fBusb_get_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfgval\fR, \fBusb_flags_t\fR \fIflags\fR);
.fi

.LP
.nf
\fBint\fR \fBusb_set_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfg_index\fR, \fBusb_flags_t\fR \fIflags\fR,
     \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, \fBusb_opaque_t\fR
     \fIcallback_arg\fR, \fBint\fR  \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, \fBusb_opaque_t\fR
     \fIcallback_arg\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI)
.SH PARAMETERS
For \fBusb_get_cfg()\fR:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 10n
Pointer to device's dev_info structure.
.RE

.sp
.ne 2
.na
\fB\fIcfgval\fR\fR
.ad
.RS 10n
Pointer to returned configuration value.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 10n
Not used.  Always waits for completion.
.RE

.sp
.LP
For \fBusb_set_cfg()\fR:
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 16n
Pointer to device's dev_info structure.
.RE

.sp
.ne 2
.na
\fB\fIcfg_index\fR\fR
.ad
.RS 16n
Desired device configuration index. Set to USB_DEV_DEFAULT_CONFIG_INDEX to
restore default configuration.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 16n
Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call
callback.
.RE

.sp
.ne 2
.na
\fB\fIcallback\fR\fR
.ad
.RS 16n
Callback handler to notify of asynchronous completion.
.RE

.sp
.ne 2
.na
\fB\fIcallback_arg\fR\fR
.ad
.RS 16n
Second argument passed to callback handler.
.RE

.SH DESCRIPTION
The \fBusb_get_cfg()\fR function retrieves the current configuration. It
ignores the flags argument and always blocks while contacting the device.
.sp
.LP
The \fBusb_set_cfg()\fR 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.
.sp
.LP
This call updates all internal USBA framework data structures, whereas issuing
a raw USB_REQ_SET_CFG device request does not.  The \fBusb_set_cfg()\fR
function is the only supported programmatic way to change device configuration.
.sp
.LP
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.
.SH RETURN VALUES
For \fBusb_get_cfg()\fR:
.sp
.ne 2
.na
\fBUSB_SUCCESS\fR
.ad
.RS 20n
New configuration is retrieved.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 20n
\fIcfgval\fR or \fIdip\fR is NULL.
.RE

.sp
.ne 2
.na
\fBUSB_FAILURE\fR
.ad
.RS 20n
Configuration cannot be retrieved.
.RE

.sp
.LP
For \fBusb_set_cfg()\fR:
.sp
.ne 2
.na
\fBUSB_SUCCESS\fR
.ad
.RS 23n
New configuration is set.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 23n
dip is NULL.
.sp
USB_FLAGS_SLEEP is clear and callback is NULL.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_CONTEXT\fR
.ad
.RS 23n
Called from interrupt context with USB_FLAGS_SLEEP specified.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_PERM\fR
.ad
.RS 23n
Caller does not own entire device or device is a parent to child devices.
.RE

.sp
.ne 2
.na
\fBUSB_BUSY\fR
.ad
.RS 23n
One or more pipes other than the default control pipe are open on the device.
.RE

.sp
.ne 2
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 23n
Pipe handle is NULL or invalid, or pipe is closing or closed.
.RE

.sp
.ne 2
.na
\fBUSB_FAILURE\fR
.ad
.RS 23n
An illegal configuration is specified.
.sp
One or more pipes other than the default control pipe are open on the device.
.RE

.SH CONTEXT
The \fBusb_get_cfg()\fR function may be called from user or kernel context.
.sp
.LP
The \fBusb_set_cfg()\fR 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.
.sp
.LP
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 \fBusb_callback_flags\fR(9S) for more
information on callbacks.
.SH EXAMPLES
.in +2
.nf
 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 {
          ...
          ...
  }

.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	PCI-based systems
_
Interface stability	Committed
.TE

.SH SEE ALSO
.BR attributes (7),
.BR usb_get_alt_if (9F),
.BR usb_get_dev_data (9F),
.BR usb_get_string_descr (9F),
.BR usb_pipe_xopen (9F),
.BR usb_callback_flags (9S),
.BR usb_cfg_descr (9S),
.BR usb_ep_descr (9S),
.BR usb_if_descr (9S)