PSARC/2007/406 USB device reset

[Lin Guo]

Neal Pollack wrote:

> Artem Kachitchkine wrote:
>
>> I am sponsoring this case for Lin Guo.
>> Requested binding is patch/micro, timeout 07/17/2007.
>>
>> -Artem.
>>
>> Template Version: @(#)sac_nextcase 1.63 06/14/07 SMI
>> This information is Copyright 2007 Sun Microsystems
>> 1. Introduction
>>     1.1. Project/Component Working Name:
>>      USB device reset
>>     1.2. Name of Document Author/Supplier:
>>      Author:  Lin Guo
>>     1.3  Date of This Document:
>>     10 July, 2007
>> 4. Technical Description
>> 4.1. Problem
>>
>> The Solaris USB Architecture (USBA) does not provide a client driver to
>> request hardware reset for a USB device, which may be required in some
>> situations such as:
>>
>> - Some USB devices need the driver to upload firmware into devices' RAM
>> and initiate a hardware reset in order to activate the new firmware.
>>
>> - Hardware reset may help drivers to recover devices from an error state
>> caused by physical or firmware defects.
>
>
> Will this functionality also assist in the upcoming attempts to get 
> Suspend-Resume
> going on x86 systems?
> I know we (our team) need to add hooks in the other disk/net/display 
> drivers, for example.
>
> Neal

No, it will not.
The reset is hardware reset for a USB device. It is aimed to activate 
the new firmware in attach() or recover a usb device from a hardware 
error state.  We made this function for requirements from Wireless USB 
dongle and USB wlan 802.11 device. Both of them need a haredware reset 
after uploading firmware into themselves.

Lin

>
>>
>> Other major OSes, such as Microsoft Windows and Linux, provide such
>> interface to device drivers.
>>
>> 4.2. Proposal
>>
>> We propose to introduce a new DDI function usb_reset_device(9F):
>>
>> int usb_reset_device(dev_info_t *dip, usb_dev_reset_lvl_t reset_level);
>>
>> 4.3. Details
>>
>> The Universal Serial Bus Specification Revision 2.0 defines a standard
>> PORT RESET request which generates an electrical reset signaling on the
>> requested hub port. Upon receipt of the reset signaling, the downstream
>> device on the port will perform a hardware reset and return to the
>> default  state. So we can implement the device reset function based on
>> the standard PORT RESET request.
>>
>> From a client driver's perspective, the effect of 
>> usb_reset_device(9F) is
>> the same as that of physical hot-removal followed by immediate physical
>> reinsersion. The same driver code that handles actual hotplugging 
>> will be
>> activated.
>>
>> Some devices change their "identity" when firmware is uploaded and the
>> device is reset - a change that is reflected via device's USB
>> descriptors. In such event the related kernel data structures need to be
>> updated and compatible names regenerated. Therefore, these devices need
>> to be detached from the original driver and make a new driver binding
>> according to the new compatible names. Drivers can indicate the need to
>> reattach using the reset level parameter.
>>
>> int usb_reset_device(dev_info_t *dip, usb_dev_reset_lvl_t reset_level);
>>
>> The valid values for reset_level are:
>>
>> USB_RESET_LVL_DEFAULT
>>
>> Default reset level. The device is reset, all 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 descriptors changing.
>>
>> 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
>> reenumerated.
>>
>> usb_reset_device(9F) creates a new helper thread for reattach. When
>> called from attach(9E), the new thread sets a timer (1s) 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 
>> will
>> attempt the reattach the driver immediately.
>>
>> If driver reattach fails, an error message is printed in system log with
>> the detailed reason and the driver will be recovered to a stable state
>> which depends on where the failure happened.
>>
>> Return values:
>>
>> USB_SUCCESS
>>
>> With USB_RESET_LVL_DEFAULT: the device was reset successfully.
>> With USB_RESET_LVL_REATTACH: reenumeration was started successfully or a
>> previous reset is still in progress.
>>
>> USB_INVALID_ARGS
>>
>> Invalid arguments.
>>
>> USB_INVALID_CONTEXT
>>
>> Called from interrupt context with USB_RESET_LVL_DEFAULT specified.
>>
>> USB_INVALID_PERM
>>
>> The driver of the dip does not own the entire device.
>>
>> USB_BUSY
>>
>> One or more pipes other than the default control pipe are open on the
>> device with USB_RESET_LVL_DEFAULT specified.
>>
>> USB_FAILURE
>>
>> The state of the device's parent hub is invalid (disconnected or 
>> suspended).
>> Called when the driver is detached.
>> The port associated with the device failed to be reset.
>> Reenumeration fails to start with USB_RESET_LVL_REATTACH specified.
>>
>> The function can be called from user or kernel context.
>>
>> 4.4. Interfaces
>>
>> -----------------------+-----------+-------------------------------------- 
>>
>> usb_device_reset       | Committed | USB device reset function
>> usb_dev_reset_lvl_t    | Committed | reset level type
>> USB_RESET_LVL_DEFAULT  | Committed | reset level value
>> USB_RESET_LVL_REATTACH | Committed | reset level value
>> -----------------------+-----------+-------------------------------------- 
>>
>>
>> Binding: patch/micro
>>
>> 4.5. References
>>
>> Universal Serial Bus Specification Revision 2.0
>> http://www.usb.org/developers/docs/usb_20_040907.zip
>>
>> PSARC/1998/111 Universal Serial Bus Framework Support
>> PSARC/2000/542 USB Architecture Update project
>> PSARC/2003/207 USBA2.0: adding USBA interfaces to the DDI
>>
>> 6. Resources and Schedule
>>     6.4. Steering Committee requested information
>>        6.4.1. Consolidation C-team Name:
>>         ON
>>     6.5. ARC review type: FastTrack
>>     6.6. ARC Exposure: open
>>
>