usb_reset_device(9F)					   Kernel Functions for Drivers 				      usb_reset_device(9F)

NAME

       usb_reset_device - reset a USB device according to the reset_level.

SYNOPSIS

       #include <sys/usb/usba.h

       int usb_reset_device (dev_info_t *dip,
	    usb_dev_reset_lvl_t reset_level);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI)

PARAMETERS

       dip

	   Pointer to the devices's dev_info structure.

       reset_level

	   The level to which the device is reset. See below for a list of valid usb_dev_reset_lvl_t values and explanations.

DESCRIPTION

       The usb_reset_device() function provides a client driver to request a hardware reset for a USB device, which may be required in some situa-
       tions such as:

	   o	  Resetting the hardware may help drivers to recover devices from an error state caused by physical or firmware defects.

	   o	  Some USB devices need the driver to upload firmware into the device's RAM and initiate a hardware reset in order to activate the
		  new firmware.

       The valid values for the reset_level are:

       USB_RESET_LVL_DEFAULT

	   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.

       USB_RESET_LVL_REATTACH

	   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.

	   The	usb_reset_device() function creates a new helper thread for reattachment. When called from attach(9E), the new thread sets a timer
	   (1 second), and waits until the driver's attach(9E) completes, after which the thread attempts to reattach the driver. When not  called
	   from attach(9E), the new thread attempts to reattach the driver immediately.

	   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.

RETURN VALUES

       The return values for the usb_reset_device() function are:

       USB_SUCCESS	      If USB_RESET_LVL_DEFAULT is specified, the device was reset successfully. If  USB_RESET_LVL_REATTACH  is	specified,
			      reattaching was started successfully or a previous reset is still in progress.

       USB_FAILURE	      The  state  of  the device's parent hub is invalid (disconnected or suspended). This is called when the driver being
			      detached. If USB_RESET_LVL_DEFAULT is specified, the device failed to be reset. If USB_RESET_LVL_REATTACH is  speci-
			      fied, reattaching failed to start.

       USB_INVALID_ARGS       Invalid arguments.

       USB_INVALID_PERM       The driver of the dip does not own the entire device.

       USB_BUSY 	      If USB_RESET_LVL_DEFAULT is specified, one or more pipes other than the default control pipe are open on the device.

       USB_INVALID_CONTEXT    If USB_RESET_LVL_DEFAULT is specified, called from interrupt context

EXAMPLES

       Example 1 Resetting a Device

       The following example shows how a device is reset to recover it from an error state:

	 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 */
		    ...
		}
	     }
	 }

       Example 2 Resetting a Device After Downloading Firmware

       The following example shows how a device is reset after downloading firmware. the device's descriptors change after the reset:

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

CONTEXT

       The usb_reset_device() function may be called from user or kernel context.

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |PCI-based systems 	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWusb			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       attributes(5), usb_clr_feature(9F), usb_get_cfg(9F), usb_pipe_close(9F), usb_pipe_open(9F), usb_pipe_reset(9F),

DIAGNOSTICS

       The messages described below may appear on the system console as well as being logged. All messages are formatted in the following manner:

	 WARNING: dev_path hubdinstance_num driver_name Error message ...

       driver_name instance_num is under bus power management, cannot be reset. Please disconnect and reconnect this device.

	   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.

       Time out when resetting the device driver_name instance_num. Please disconnect and reconnect it to system.

	   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.

       driver_name instance_num cannot be reset due to other applications are using it, please first close these applications, then disconnect and
       reconnect the device.

	   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.

NOTES

       Always close all applications before resetting a device.

SunOS 5.11							  21 August 2007					      usb_reset_device(9F)