usr/src/man/man9f/usb_reset_device.9f

   1 '\" te
   2 .\"  Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH USB_RESET_DEVICE 9F "Sep 16, 2016"
   7 .SH NAME
   8 usb_reset_device \- reset a USB device according to the reset_level.
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/usb/usba.h
  13
  14
  15
  16 \fBint\fR \fBusb_reset_device\fR (\fBdev_info_t *\fR\fIdip\fR,
  17      \fBusb_dev_reset_lvl_t\fR \fIreset_level\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .LP
  22 Solaris DDI specific (Solaris DDI)
  23 .SH PARAMETERS
  24 .ne 2
  25 .na
  26 \fB\fIdip\fR\fR
  27 .ad
  28 .sp .6
  29 .RS 4n
  30 Pointer to the devices's \fBdev_info\fR structure.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIreset_level\fR\fR
  37 .ad
  38 .sp .6
  39 .RS 4n
  40 The level to which the device is reset. See below for a list of valid
  41 \fBusb_dev_reset_lvl_t\fR values and explanations.
  42 .RE
  43
  44 .SH DESCRIPTION
  45 .LP
  46 The \fBusb_reset_device()\fR function provides a client driver to request a
  47 hardware reset for a \fBUSB\fR device, which may be required in some situations
  48 such as:
  49 .RS +4
  50 .TP
  51 .ie t \(bu
  52 .el o
  53 Resetting the hardware may help drivers to recover devices from an error state
  54 caused by physical or firmware defects.
  55 .RE
  56 .RS +4
  57 .TP
  58 .ie t \(bu
  59 .el o
  60 Some \fBUSB\fR devices need the driver to upload firmware into the device's
  61 \fBRAM\fR and initiate a hardware reset in order to activate the new firmware.
  62 .RE
  63 .sp
  64 .LP
  65 The valid values for the \fIreset_level\fR are:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBUSB_RESET_LVL_DEFAULT\fR\fR
  70 .ad
  71 .sp .6
  72 .RS 4n
  73 The default reset level. The device is reset and any error status is cleared.
  74 The device state machines and registers are also cleared and need to be
  75 reinitialized in the driver. The current driver remains attached. This reset
  76 level applies to hardware error recovery, or firmware download without changing
  77 the descriptors.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBUSB_RESET_LVL_REATTACH\fR\fR
  84 .ad
  85 .sp .6
  86 .RS 4n
  87 The device is reset. The original driver is detached and a new driver attaching
  88 process is started according to the updated compatible name. This reset level
  89 applies to the firmware download with the descriptors changing, or other
  90 situations in which the device needs to be reattached.
  91 .sp
  92 The \fBusb_reset_device()\fR function creates a new helper thread for
  93 reattachment. When called from \fBattach\fR(9E), the new thread sets a timer (1
  94 second), and waits until the driver's \fBattach\fR(9E) completes, after which
  95 the thread attempts to reattach the driver. When not called from
  96 \fBattach\fR(9E), the new thread attempts to reattach the driver immediately.
  97 .sp
  98 If the thread fails to reattach to the driver, an error message is printed in
  99 system log with the detailed reason. The driver returns to a stable state,
 100 depending on where the failure occurred.
 101 .RE
 102
 103 .SH RETURN VALUES
 104 .LP
 105 The return values for the \fBusb_reset_device()\fR function are:
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBUSB_SUCCESS\fR\fR
 110 .ad
 111 .RS 23n
 112 If \fBUSB_RESET_LVL_DEFAULT\fR is specified, the device was reset successfully.
 113 If \fBUSB_RESET_LVL_REATTACH\fR is specified, reattaching was started
 114 successfully or a previous reset is still in progress.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBUSB_FAILURE\fR\fR
 121 .ad
 122 .RS 23n
 123 The state of the device's parent hub is invalid (disconnected or suspended).
 124 This is called when the driver being detached. If \fBUSB_RESET_LVL_DEFAULT\fR
 125 is specified, the device failed to be reset. If \fBUSB_RESET_LVL_REATTACH\fR is
 126 specified, reattaching failed to start.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBUSB_INVALID_ARGS\fR\fR
 133 .ad
 134 .RS 23n
 135 Invalid arguments.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBUSB_INVALID_PERM\fR\fR
 142 .ad
 143 .RS 23n
 144 The driver of the dip does not own the entire device.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBUSB_BUSY\fR\fR
 151 .ad
 152 .RS 23n
 153 If \fBUSB_RESET_LVL_DEFAULT\fR is specified, one or more pipes other than the
 154 default control pipe are open on the device.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBUSB_INVALID_CONTEXT\fR\fR
 161 .ad
 162 .RS 23n
 163 If \fBUSB_RESET_LVL_DEFAULT\fR is specified, called from interrupt context
 164 .RE
 165
 166 .SH EXAMPLES
 167 .LP
 168 \fBExample 1 \fRResetting a Device
 169 .sp
 170 .LP
 171 The following example shows how a device is reset to recover it from an error
 172 state:
 173
 174 .sp
 175 .in +2
 176 .nf
 177 xxx_configure()
 178 {
 179     xxx_set_parameter1();
 180
 181     if (xxx_set_parameter2() == USB_FAILURE) {
 182
 183        /* Close all the opened pipes except the default pipe */
 184        xxx_close_all_opened_pipes();
 185
 186        /* Reset the device */
 187        rval = usb_reset_device(dip, USB_RESET_LVL_DEFAULT);
 188        if (rval == USB_SUCCESS) {
 189            /* Re-configure the device */
 190            xxx_set_parameter1();
 191            xxx_set_parameter2();
 192
 193            /* Open the closed pipes if needed */
 194            ...
 195        } else {
 196            /* Failed to reset the device, check the return value for
 197               further process */
 198            ...
 199        }
 200     }
 201 }
 202 .fi
 203 .in -2
 204
 205 .LP
 206 \fBExample 2 \fRResetting a Device After Downloading Firmware
 207 .sp
 208 .LP
 209 The following example shows how a device is reset after downloading firmware.
 210 the device's descriptors change after the reset:
 211
 212 .sp
 213 .in +2
 214 .nf
 215 static int xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 216 {
 217     ...
 218     /* Download the firmware to the RAM of the device */
 219     if (firmware_download() == USB_SUCCESS) {
 220         /* Reset the device and re-enumerate it */
 221         rval = usb_reset_device(dip, USB_RESET_LVL_REATTACH);
 222         if (rval == USB_SUCCESS) {
 223             /* The re-enumeration has been started up, just return */
 224             return (DDI_SUCCESS);
 225        } else {
 226             /* Failed to start the re-enumeration, check the return value
 227                for further process*/
 228                ...
 229              return (DDI_FAILURE);
 230       }
 231 }
 232 .fi
 233 .in -2
 234
 235 .SH CONTEXT
 236 .LP
 237 The \fBusb_reset_device()\fR function may be called from user or kernel
 238 context.
 239 .SH ATTRIBUTES
 240 .LP
 241 See \fBattributes\fR(5) for descriptions of the following attributes:
 242 .sp
 243
 244 .sp
 245 .TS
 246 box;
 247 c | c
 248 l | l .
 249 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 250 _
 251 Architecture    PCI-based systems
 252 _
 253 Interface Stability     Committed
 254 .TE
 255
 256 .SH SEE ALSO
 257 .LP
 258 \fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_cfg\fR(9F),
 259 \fBusb_pipe_close\fR(9F), \fBusb_pipe_xopen\fR(9F), \fBusb_pipe_reset\fR(9F),
 260 .SH DIAGNOSTICS
 261 .LP
 262 The messages described below may appear on the system console as well as being
 263 logged. All messages are formatted in the following manner:
 264 .sp
 265 .in +2
 266 .nf
 267 WARNING: \fIdev_path\fR hubd\fIinstance_num\fR \fIdriver_name\fR Error message ...
 268 .fi
 269 .in -2
 270 .sp
 271
 272 .sp
 273 .ne 2
 274 .na
 275 \fIdriver_name instance_num\fR \fBis under bus power management, cannot
 276 be reset. Please disconnect and reconnect this device.\fR
 277 .ad
 278 .sp .6
 279 .RS 4n
 280 Bus power management is in process when calling the reset function, the device
 281 failed to be reset and stayed in the former state. Please disconnect and
 282 reconnect it to system.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fBTime out when resetting the device\fR \fIdriver_name instance_num\fR\fB.
 289 Please disconnect and reconnect it to system.\fR
 290 .ad
 291 .sp .6
 292 .RS 4n
 293 The parent hub/root hub of this device is busy now. The device failed to be
 294 reset and stayed in the former state. Please disconnect the device, wait for a
 295 while and reconnect it to system.
 296 .RE
 297
 298 .sp
 299 .ne 2
 300 .na
 301 \fIdriver_name instance_num\fR \fBcannot be reset due to other
 302 applications are using it, please first close these applications, then
 303 disconnect and reconnect the device.\fR
 304 .ad
 305 .sp .6
 306 .RS 4n
 307 The device is using by other applications, the related driver failed to be
 308 detached. Please make sure to close these applications before calling the reset
 309 function.
 310 .RE
 311
 312 .SH NOTES
 313 .LP
 314 Always close all applications before resetting a device.