'\" te
.\"  Copyright (c) 2007, 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_RESET_DEVICE 9F "Sep 16, 2016"
.SH NAME
usb_reset_device \- reset a USB device according to the reset_level.
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h



\fBint\fR \fBusb_reset_device\fR (\fBdev_info_t *\fR\fIdip\fR,
     \fBusb_dev_reset_lvl_t\fR \fIreset_level\fR);
.fi

.SH INTERFACE LEVEL
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.sp .6
.RS 4n
Pointer to the devices's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIreset_level\fR\fR
.ad
.sp .6
.RS 4n
The level to which the device is reset. See below for a list of valid
\fBusb_dev_reset_lvl_t\fR values and explanations.
.RE

.SH DESCRIPTION
.LP
The \fBusb_reset_device()\fR function provides a client driver to request a
hardware reset for a \fBUSB\fR device, which may be required in some situations
such as:
.RS +4
.TP
.ie t \(bu
.el o
Resetting the hardware may help drivers to recover devices from an error state
caused by physical or firmware defects.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Some \fBUSB\fR devices need the driver to upload firmware into the device's
\fBRAM\fR and initiate a hardware reset in order to activate the new firmware.
.RE
.sp
.LP
The valid values for the \fIreset_level\fR are:
.sp
.ne 2
.na
\fB\fBUSB_RESET_LVL_DEFAULT\fR\fR
.ad
.sp .6
.RS 4n
The default reset level. The device is reset and any error status is cleared.
The device state machines and registers are also cleared and need to be
reinitialized in the driver. The current driver remains attached. This reset
level applies to hardware error recovery, or firmware download without changing
the descriptors.
.RE

.sp
.ne 2
.na
\fB\fBUSB_RESET_LVL_REATTACH\fR\fR
.ad
.sp .6
.RS 4n
The device is reset. The original driver is detached and a new driver attaching
process is started according to the updated compatible name. This reset level
applies to the firmware download with the descriptors changing, or other
situations in which the device needs to be reattached.
.sp
The \fBusb_reset_device()\fR function creates a new helper thread for
reattachment. When called from \fBattach\fR(9E), the new thread sets a timer (1
second), and waits until the driver's \fBattach\fR(9E) completes, after which
the thread attempts to reattach the driver. When not called from
\fBattach\fR(9E), the new thread attempts to reattach the driver immediately.
.sp
If the thread fails to reattach to the driver, an error message is printed in
system log with the detailed reason. The driver returns to a stable state,
depending on where the failure occurred.
.RE

.SH RETURN VALUES
.LP
The return values for the \fBusb_reset_device()\fR function are:
.sp
.ne 2
.na
\fB\fBUSB_SUCCESS\fR\fR
.ad
.RS 23n
If \fBUSB_RESET_LVL_DEFAULT\fR is specified, the device was reset successfully.
If \fBUSB_RESET_LVL_REATTACH\fR is specified, reattaching was started
successfully or a previous reset is still in progress.
.RE

.sp
.ne 2
.na
\fB\fBUSB_FAILURE\fR\fR
.ad
.RS 23n
The state of the device's parent hub is invalid (disconnected or suspended).
This is called when the driver being detached. If \fBUSB_RESET_LVL_DEFAULT\fR
is specified, the device failed to be reset. If \fBUSB_RESET_LVL_REATTACH\fR is
specified, reattaching failed to start.
.RE

.sp
.ne 2
.na
\fB\fBUSB_INVALID_ARGS\fR\fR
.ad
.RS 23n
Invalid arguments.
.RE

.sp
.ne 2
.na
\fB\fBUSB_INVALID_PERM\fR\fR
.ad
.RS 23n
The driver of the dip does not own the entire device.
.RE

.sp
.ne 2
.na
\fB\fBUSB_BUSY\fR\fR
.ad
.RS 23n
If \fBUSB_RESET_LVL_DEFAULT\fR is specified, one or more pipes other than the
default control pipe are open on the device.
.RE

.sp
.ne 2
.na
\fB\fBUSB_INVALID_CONTEXT\fR\fR
.ad
.RS 23n
If \fBUSB_RESET_LVL_DEFAULT\fR is specified, called from interrupt context
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRResetting a Device
.sp
.LP
The following example shows how a device is reset to recover it from an error
state:

.sp
.in +2
.nf
xxx_configure()
{
    xxx_set_parameter1();

    if (xxx_set_parameter2() == USB_FAILURE) {

       /* Close all the opened pipes except the default pipe */
       xxx_close_all_opened_pipes();

       /* Reset the device */
       rval = usb_reset_device(dip, USB_RESET_LVL_DEFAULT);
       if (rval == USB_SUCCESS) {
           /* Re-configure the device */
           xxx_set_parameter1();
           xxx_set_parameter2();

           /* Open the closed pipes if needed */
           ...
       } else {
           /* Failed to reset the device, check the return value for
              further process */
           ...
       }
    }
}
.fi
.in -2

.LP
\fBExample 2 \fRResetting a Device After Downloading Firmware
.sp
.LP
The following example shows how a device is reset after downloading firmware.
the device's descriptors change after the reset:

.sp
.in +2
.nf
static int xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
    ...
    /* Download the firmware to the RAM of the device */
    if (firmware_download() == USB_SUCCESS) {
        /* Reset the device and re-enumerate it */
        rval = usb_reset_device(dip, USB_RESET_LVL_REATTACH);
        if (rval == USB_SUCCESS) {
            /* The re-enumeration has been started up, just return */
            return (DDI_SUCCESS);
       } else {
            /* Failed to start the re-enumeration, check the return value
               for further process*/
               ...
             return (DDI_FAILURE);
      }
}
.fi
.in -2

.SH CONTEXT
.LP
The \fBusb_reset_device()\fR function may be called from user or kernel
context.
.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) 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
.LP
\fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_cfg\fR(9F),
\fBusb_pipe_close\fR(9F), \fBusb_pipe_xopen\fR(9F), \fBusb_pipe_reset\fR(9F),
.SH DIAGNOSTICS
.LP
The messages described below may appear on the system console as well as being
logged. All messages are formatted in the following manner:
.sp
.in +2
.nf
WARNING: \fIdev_path\fR hubd\fIinstance_num\fR \fIdriver_name\fR Error message ...
.fi
.in -2
.sp

.sp
.ne 2
.na
\fB\fIdriver_name\fR \fIinstance_num\fR is under bus power management, cannot
be reset. Please disconnect and reconnect this device.\fR
.ad
.sp .6
.RS 4n
Bus power management is in process when calling the reset function, the device
failed to be reset and stayed in the former state. Please disconnect and
reconnect it to system.
.RE

.sp
.ne 2
.na
\fBTime out when resetting the device \fIdriver_name\fR \fIinstance_num\fR.
Please disconnect and reconnect it to system.\fR
.ad
.sp .6
.RS 4n
The parent hub/root hub of this device is busy now. The device failed to be
reset and stayed in the former state. Please disconnect the device, wait for a
while and reconnect it to system.
.RE

.sp
.ne 2
.na
\fB\fIdriver_name\fR \fIinstance_num\fR cannot be reset due to other
applications are using it, please first close these applications, then
disconnect and reconnect the device.\fR
.ad
.sp .6
.RS 4n
The device is using by other applications, the related driver failed to be
detached. Please make sure to close these applications before calling the reset
function.
.RE

.SH NOTES
.LP
Always close all applications before resetting a device.