1usb_reset_device(9F) Kernel Functions for Drivers usb_reset_device(9F)
2
6 usb_reset_device - reset a USB device according to the reset_level.
7
9 #include <sys/usb/usba.h
10 int usb_reset_device (dev_info_t *dip,
14 usb_dev_reset_lvl_t reset_level);
15
18 Solaris DDI specific (Solaris DDI)
19
21 dip
22 Pointer to the devices's dev_info structure.
24 reset_level
27 The level to which the device is reset. See below for a list of
29 valid usb_dev_reset_lvl_t values and explanations.
30
33 The usb_reset_device() function provides a client driver to request a
34 hardware reset for a USB device, which may be required in some situa‐
35 tions such as:
36 o Resetting the hardware may help drivers to recover devices
38 from an error state caused by physical or firmware defects.
39 o Some USB devices need the driver to upload firmware into the
41 device's RAM and initiate a hardware reset in order to acti‐
42 vate the new firmware.
43 The valid values for the reset_level are:
46 USB_RESET_LVL_DEFAULT
48 The default reset level. The device is reset and any error status
50 is cleared. The device state machines and registers are also
51 cleared and need to be reinitialized in the driver. The current
52 driver remains attached. This reset level applies to hardware error
53 recovery, or firmware download without changing the descriptors.
54 USB_RESET_LVL_REATTACH
57 The device is reset. The original driver is detached and a new
59 driver attaching process is started according to the updated com‐
60 patible name. This reset level applies to the firmware download
61 with the descriptors changing, or other situations in which the
62 device needs to be reattached.
63 The usb_reset_device() function creates a new helper thread for
65 reattachment. When called from attach(9E), the new thread sets a
66 timer (1 second), and waits until the driver's attach(9E) com‐
67 pletes, after which the thread attempts to reattach the driver.
68 When not called from attach(9E), the new thread attempts to reat‐
69 tach the driver immediately.
70 If the thread fails to reattach to the driver, an error message is
72 printed in system log with the detailed reason. The driver returns
73 to a stable state, depending on where the failure occurred.
74
77 The return values for the usb_reset_device() function are:
78 USB_SUCCESS If USB_RESET_LVL_DEFAULT is specified, the
80 device was reset successfully. If
81 USB_RESET_LVL_REATTACH is specified, reattaching
82 was started successfully or a previous reset is
83 still in progress.
84 USB_FAILURE The state of the device's parent hub is invalid
87 (disconnected or suspended). This is called when
88 the driver being detached. If
89 USB_RESET_LVL_DEFAULT is specified, the device
90 failed to be reset. If USB_RESET_LVL_REATTACH is
91 specified, reattaching failed to start.
92 USB_INVALID_ARGS Invalid arguments.
95 USB_INVALID_PERM The driver of the dip does not own the entire
98 device.
99 USB_BUSY If USB_RESET_LVL_DEFAULT is specified, one or
102 more pipes other than the default control pipe
103 are open on the device.
104 USB_INVALID_CONTEXT If USB_RESET_LVL_DEFAULT is specified, called
107 from interrupt context
108
111 Example 1 Resetting a Device
112 The following example shows how a device is reset to recover it from an
115 error state:
116 xxx_configure()
119 {
120 xxx_set_parameter1();
121 if (xxx_set_parameter2() == USB_FAILURE) {
123 /* Close all the opened pipes except the default pipe */
125 xxx_close_all_opened_pipes();
126 /* Reset the device */
128 rval = usb_reset_device(dip, USB_RESET_LVL_DEFAULT);
129 if (rval == USB_SUCCESS) {
130 /* Re-configure the device */
131 xxx_set_parameter1();
132 xxx_set_parameter2();
133 /* Open the closed pipes if needed */
135 ...
136 } else {
137 /* Failed to reset the device, check the return value for
138 further process */
139 ...
140 }
141 }
142 }
143 Example 2 Resetting a Device After Downloading Firmware
146 The following example shows how a device is reset after downloading
149 firmware. the device's descriptors change after the reset:
150 static int xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
153 {
154 ...
155 /* Download the firmware to the RAM of the device */
156 if (firmware_download() == USB_SUCCESS) {
157 /* Reset the device and re-enumerate it */
158 rval = usb_reset_device(dip, USB_RESET_LVL_REATTACH);
159 if (rval == USB_SUCCESS) {
160 /* The re-enumeration has been started up, just return */
161 return (DDI_SUCCESS);
162 } else {
163 /* Failed to start the re-enumeration, check the return value
164 for further process*/
165 ...
166 return (DDI_FAILURE);
167 }
168 }
169
172 The usb_reset_device() function may be called from user or kernel con‐
173 text.
174
176 See attributes(5) for descriptions of the following attributes:
177 ┌─────────────────────────────┬─────────────────────────────┐
182 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
183 ├─────────────────────────────┼─────────────────────────────┤
184 │Architecture │PCI-based systems │
185 ├─────────────────────────────┼─────────────────────────────┤
186 │Availability │SUNWusb │
187 ├─────────────────────────────┼─────────────────────────────┤
188 │Interface Stability │Committed │
189 └─────────────────────────────┴─────────────────────────────┘
190
192 attributes(5), usb_clr_feature(9F), usb_get_cfg(9F),
193 usb_pipe_close(9F), usb_pipe_open(9F), usb_pipe_reset(9F),
194
196 The messages described below may appear on the system console as well
197 as being logged. All messages are formatted in the following manner:
198 WARNING: dev_path hubdinstance_num driver_name Error message ...
200 driver_name instance_num is under bus power management, cannot be
204 reset. Please disconnect and reconnect this device.
205 Bus power management is in process when calling the reset function,
207 the device failed to be reset and stayed in the former state.
208 Please disconnect and reconnect it to system.
209 Time out when resetting the device driver_name instance_num. Please
212 disconnect and reconnect it to system.
213 The parent hub/root hub of this device is busy now. The device
215 failed to be reset and stayed in the former state. Please discon‐
216 nect the device, wait for a while and reconnect it to system.
217 driver_name instance_num cannot be reset due to other applications are
220 using it, please first close these applications, then disconnect and
221 reconnect the device.
222 The device is using by other applications, the related driver
224 failed to be detached. Please make sure to close these applications
225 before calling the reset function.
226
229 Always close all applications before resetting a device.
230SunOS 5.11 21 August 2007 usb_reset_device(9F)