Initial Contribution
msm-2.6.38: tag AU_LINUX_ANDROID_GINGERBREAD.02.03.04.00.142
Signed-off-by: Bryan Huntsman <bryanh@codeaurora.org>
diff --git a/Documentation/usb/msm_otg.txt b/Documentation/usb/msm_otg.txt
new file mode 100644
index 0000000..29b6f1a
--- /dev/null
+++ b/Documentation/usb/msm_otg.txt
@@ -0,0 +1,382 @@
+Introduction
+============
+This driver implements Session Request Protocol (SRP) and Host negotiation
+Protocol (HNP) described in On-The-Go (OTG) Supplement to the USB 2.0
+Specification. It also provides support for Accessory Charger Adapter (ACA)
+defined in the Battery Charging Specification 1.1.
+
+These protocols provide a means for USB host devices to intelligently manage
+power on VBUS and USB peripheral devices to become the host when paired with
+another OTG device.
+
+Hardware description
+====================
+USB hardware found in Qualcomm chipsets like MSM7x27, MSM7x30, QSD8x50 and
+MSM8660 is compliant to USB 2.0 high speed On-The-Go protocol.
+The transceiver, aka PHY is integrated on the chip and ULPI interface is used for
+communication.
+
+USB hardware interfaces to the system memory via AHB BUS. DMA engine is included
+to move all of the data to be transferred over the USB between USB core and
+system memory. Device controller can support 16 endpoints of all types
+(control/bulk/interrupt /isochronous) defined in USB 2.0 specification. The
+host controller is compliant to EHCI specification. Directly connected USB 1.1
+Full/Low speed devices are supported without a companion controller by having
+inbuilt Transaction Translator (TT).
+
+USB_HS_CLK, USB_HS_PCLK and USB_HS_CCLK are required for USB operation.
+Phy feeds 60MHZ HS_CLK to link when ULPI interface is used. This clock needs to
+be turned on only while resetting the link. HS_PCLK (Pbus clock) is required to
+move data to/from hardware FIFO. This clock may not be required on targets like
+MSM8660 where USB is part of smart peripheral subsystem. AXI bus frequency needs
+to be kept at maximum value while USB data transfers are happening. HS_CCLK
+(core clock) is introduced in MSM7x30 to get rid of dependency on AXI bus
+frequency.
+
+The same irq line is shared across OTG, Device controller and Host controller
+drivers. Phy is integrated on the chip and no gpios are required to connect link
+and PHY.
+
+Phy can monitor VBUS and ID lines while operating in low power mode (LPM). But
+leaving comparators ON in LPM increases power consumption. Hence VBUS line is
+routed to PMIC hardware which can generate interrupt (when accessed by Apps
+processor) or send RPC callback. This is also useful when an External LDO to
+power up 3.3V of PHY is not installed. An internal LDO is turned upon
+receiving notification from PMIC. Id line is not routed to PMIC. Hence OTG mode
+can not be supported with this configuration and External LDO must be present.
+
+Hardware can generate interrupt when voltage on VBUS line is reached
+above/below A-VBUS Valid and B-Session Valid threshold values defined in OTG
+specification. Interrupt is generated when Id line is grounded i.e Micro-A
+cable is connected.
+
+The following hardware features help in meeting the SRP and HNP protocol
+timings.
+
+Hardware Assist Data-pulse (HADP):
+---------------------------------
+When software programs HADP, Hardware start a data pulse of approximately 7ms
+in duration and then automatically ceases the data pulsing. This automation
+relieves software from controlling the data-pulse duration. This assist will
+ensure data pulsing meets the OTG requirement of > 5ms and < 10ms.
+
+Hardware Assist Auto-Reset (HAAR):
+---------------------------------
+When software programs HAAR, Hardware will automatically start a reset after
+a connect event. This shortcuts the normal process where software is notified
+of the connect event and starts the reset. Software will still receive
+notification of the connect event but should not write the reset bit when the
+HAAR is set. Software will be notified again after the reset is complete via
+the enable change bit in the PORTSC register which cause a port change
+interrupt.
+
+Hardware Assist B-Disconnect to A-Connect (HABA):
+------------------------------------------------
+During Host negotiation Protocol(HNP), A-Device must enable pull-up on D+ as
+soon as possible after detecting disconnect from B-device.
+
+When Software programs HABA, the Host Controller port is in suspend mode, and
+the B-device disconnects, then this hardware assist begins.
+1. Reset the OTG core
+2. Write the OTG core into device mode.
+3. Write the device run bit to a '1' and enable necessary interrupts including:
+ * USB Reset Enable (URE) : enables interrupt on usb bus reset to device
+ * Sleep Enable (SLE) : enables interrupt on device suspend
+ * Port Change Detect Enable (PCE) : enables interrupt on device connect
+
+When software has enabled this hardware assist, it must not interfere during the
+transition and should not write any register in the core until it gets an
+interrupt from the device controller signifying that a reset interrupt has
+occurred or at least first verify that the core has entered device mode.
+
+The following hardware feature helps in supporting Accessory Charger Adapter:
+
+PHY Support for ID_A/B/C:
+------------------------
+Accessory Charger Adapter has three ports to attach an OTG, charger and A or
+B-device. So, based on what all device are attached to the ACA, it outputs a
+state on the ID pin (i.e GROUND, ID_A, ID_B, ID_C, FLOAT).
+USB PHY has support for these ID states. Once software enables this support,
+PHY sets corresponding bit in its INTS register based on any changes in the
+ID state.
+
+Software description
+====================
+
+This driver provides OTG functionality when Device controller driver (DCD) and
+Host controller driver (HCD) are enabled. It is enabled even when one of the DCD
+or HCD is enabled to use PHY initialization, clock management, register memory
+mapping, low power mode (LPM) functionalities.
+
+Session Request Protocol (SRP): A-device may turn off power on VBUS upon user
+request or A_WAIT_BCON timeout. SRP detection interrupt is enabled and
+hardware is put into LPM. If Data pulse is detected, A-device starts a new
+session by applying power on VBUS. Hardware Auto Assist Data pulse feature is
+used to program Data pulse
+When acting as a B-device, if SRP initial conditions (SE0 condition for
+TB_SE0_SRP min and previous session was ended before TB_SSEND_SRP) are met, SRP
+is initiated upon user request. Hardware Auto Assist Data pulse feature is
+used to program Data pulse. If remote device does not turn on VBUS before
+TB_SRP_FAIL, an error is reported to user space.
+
+Host Negotiation Protocol (HNP): A-device periodically polls B-device to check
+host request status. When B-device returns true, A-device shall enable HNP and
+suspend the bus with in THOST_REQ_SUSP. HNP polling is implemented in USB core
+software. HCD registers a start_hnp callback method with EHCI framework. This
+method is called after suspending the port if HNP is enabled. HCD notifies OTG
+that B-device is suspended. A_AIDL_BDIS timer is kicked and waits for B-device
+disconnection. If B-device does not signal disconnect within TA_AIDL_BDIS
+timeout, session is closed by powering down VBUS. Otherwise A-device stops HCD
+and starts DCD to enable pull-up. A-device again resumes host role if it had
+observed bus idle for TA_BIDL_ADIS time.
+B-device signals host_request true upon user request. DCD notifies OTG that
+HNP is enabled and bus is idle. OTG driver disable pull-up by stopping DCD and
+kick B_ASE0_BRST timer. If A-device does not signal connect with in
+TB_ASE0_BRST, B-device resumes in peripheral role. Otherwise B-device assert
+the bus reset and enumerate the A-device.
+
+MSM chipsets which have 45nm integrated PHY supports Attach Detection Protocol.
+(A protocol which enables an OTG device to detect when a remote device has been
+attached or detached without supplying VBUS). ADP support needs to be
+implemented to efficiently supply/request power on VBUS. Leakage currents (i.e
+VBUS applied but no peripheral is connected) are very less on MSM hardware. So
+VBUS can be applied when Id becomes false. ADP may be never implemented in
+this driver due to this reason.
+
+The state machine is implemented as described in the OTG specification.
+A few exceptions are mentioned below:
+
+1. Host session request i.e a_bus_request input variable is automatically
+asserted when Id becomes false and SRP is detected.
+It is de-asserted When HCD suspends the bus and asserted again in case of
+remote device remote wakeup.
+2. Output variables like drv_vbus, loc_conn, loc_sof, adp_prb are not
+maintained in the state machine as they serve no purpose.
+3. Bus power down request i.e a_bus_drop is cleared when Micro-A cable is
+connected so that non OTG device can be detected when Micro-A cable is
+connected next time.
+4. Input variables that determine SRP initial condition status b_se0_srp and
+b_ssend_srp are not maintained in state machine processing. When a session is
+ended i.e VBUS falls below B-Session Valid threshold, time stamp is taken and
+is compared against the current time at the time of SRP initiation.
+
+
+Controller gives interrupt for every 1 msec if 1MSIE (1 Msec interrupt enable)
+is set. Timers used in OTG state machine can be implementing using 1MSEC
+timer as a source. But hrtimer on MSM hardware can give at least 1/32KHZ
+precision. So hrtimer framework is used to implement OTG timers. No two OTG
+timers run in parallel. Hence one hrtimer is used for all OTG timers.
+
+OTG state machine processing can not be done in atomic context. Hence a worker
+thread is created for processing the state machine events. A separate worker
+thread is created instead of using default worker thread to meet OTG
+specification timings.
+
+OTG supplement Revision 2.0 has made HNP timings less stringent compared to
+Revision 1.3. TA_BDIS_ACON (The time with in A-Device should enable pull-up
+upon B-device signals disconnect) has been changed to 150 msec from 3 msec.
+DCD can be easily activated within 150 msec. Hence HABA is not used.
+TB_ACON_BSE0 (The time with in B-device should reset the A-device) has been
+changed to 150 msec from 1 sec. Host software would easily meet this timing
+given that de-bounce delays and root hub port power stabilization delays are
+not required during HNP.
+
+Accessory Charger Adapter (ACA): To support ACA there must be support in the
+USB hardware (Controller and PHY) for the ID_A/B/C states. It should be able
+to interrupt software for any ID state changes. On receiving this interrupt,
+interrupt handler checks the current ID state and invokes OTG state machine
+for further handling. Even if the USB Controller doesn't support these ID_A/B/C
+states, driver can still detect the ID state transitions by depending on USB
+PHY if the PHY supports these ID states. For this scenario, driver relies
+on polling of PHY register to determine the ID state changes as long as an
+ACA is attached to the system. This polling is implemented by using a timer
+running at a frequency of 1 sec. This timer checks for the current ID state
+and on detecting any change it invokes OTG state machine for further handling.
+
+Following are the actions performed by the driver as per the ID state:
+* ID_FLOAT: Configure device to act as peripheral and allow charging if VBUS
+ is present, else move it to LPM (low power mode).
+* ID_GROUND: Configure device to act as host and supply VBUS.
+* ID_A: Configure device to act as host and don't supply VBUS. In this state
+ the device can charge as well.
+* ID_B: Keep the device in IDLE state and allow charging.
+* ID_C: Configure device to act as peripheral and allow charging.
+
+Design
+======
+
+The following goals are kept in mind while designing OTG state machine.
+
+1. Avoid User intervention when operating as a standard Host or standard
+peripheral
+2. Support host only and peripheral only modes
+3. Put Hardware in LPM when ever possible
+4. Pass OTG compliance tests
+5. Report notification/error messages to user space
+6. With ACA, allow charging in Host mode as well
+7. Disable LPM as long as ID state polling is happening
+
+Power Management
+================
+
+System suspend is negated by acquiring wakelock while processing OTG state
+machine, or while polling for the PHY ID state in case of ACA.
+Wakelock is released:
+1. After activating the DCD/HCD. It is the responsibility of DCD/HCD to
+acquire wakelock if required.
+2. After putting hardware in LPM.
+3. No state machine events and timers are pending. This would cover scenarios
+mentioned in (1) and (2).
+4. After driver stops polling for ID state in case of ACA.
+
+Wake lock is re-acquired when state machine work is scheduled, which can
+happen from interrupt (exiting LPM), sysfs entries (initiate SRP, clear
+error, bus drop, etc), or from ID state polling routine.
+
+OTG driver provides set_suspend method for DCD/HCD to put hardware in LPM. DCD
+can use this method upon bus suspend. HCD can use this method upon suspending
+the root hub.
+
+LPM entering procedure:
+1. Clear PHY interrupt latch registers.
+2. Enable PHY comparators to detect Id, B-Session Valid interrupts while hardware
+is in LPM.
+3. Turn off PLL block on the PHY to achieve maximum power savings.
+4. Put PHY in suspend mode by setting PHCD bit in PORTSC register.
+5. Enable asynchronous interrupt so that PHY can generate interrupt when
+clocks are disabled.
+6. Disable all USB clocks.
+
+LPM exit procedure:
+1. Enable USB clocks.
+2. Disable asynchronous interrupt.
+3. Put PHY out of suspend mode. This is not required when LPM is exited due to
+hardware activity i.e asynchronous interrupt.
+
+SMP/multi-core
+==============
+
+OTG state machine inputs like bus request, bus drop, srp_detect etc accessed
+from interrupt context, and multiple process contexts. Hence atomic bit ops are
+used. ulpi_read and ulpi_write functions can now be accessed from multiple
+context, hence, these are protected using a spin_lock.
+
+Interface
+=========
+This driver provides the following methods to DCD and HCD.
+
+set_peripheral: DCD use this methods to register/unregister USB gadget.
+
+set_host: HCD use this method to register/unregister USB bus. Unlike gadget
+framework, there are no standard methods to start/stop HCD. Hence start_host
+method is introduced and must be initialized by HCD prior to registration.
+
+set_clk: HCD and DCD use this method to turn on/off USB_HS_CLK clk which is
+required only while resetting the controller.
+
+start_srp: DCD use this method to initiate Session Request Protocol (SRP).
+SRP may be initiated when function drivers use remote wakeup facility, when
+B-Device wishes to become host. OTG driver programs Data-Pulsing if initial
+condition of SRP are met. Otherwise proper error code is returned.
+
+set_suspend: DCD call this method when controller generates suspend
+interrupt or generates reset/port change interrupt before HNP and during HNP.
+If device is in B_PERIPHERAL state, HNP is initiated if host had enabled it.
+If device is in A_PERIPHERAL state, A_BIDL_ADIS timer is kicked in case of
+suspend interrupt. If this timer expires, A-device take back it's host role
+and continue previous session. This timer is deleted in case of
+reset/port change interrupts.
+HCD call this method after suspending the root hub. Hardware is put into LPM.
+
+start_hnp: A-device needs to enable pull-up on D+ within TA_BIDL_ADIS after
+suspending the bus i.e putting port in suspend state. EHCI stack can use this
+method to notify OTG right after suspending the OTG port. OTG driver schedule
+a work to stop host and enable pull-up on D+.
+
+send_event: USB core, DCD and HCD can use otg_send_event() API to send OTG
+notification/error messages to user space. send_event method defined in
+otg_transceiver is invoked by otg_send_event() API. An uevent is sent
+with SUBSYSTEM=platform, MODULE=msm_otg and EVENT=<event>, where event could
+be one of the following events.
+
+OTG_EVENT_DEV_CONN_TMOUT: Device connection timeout or device not responding.
+OTG_EVENT_NO_RESP_FOR_HNP_ENABLE: Device is not responding to B_HNP_ENABLE
+ feature request.
+OTG_EVENT_HUB_NOT_SUPPORTED: Host does not support HUB class peripherals.
+OTG_EVENT_DEV_NOT_SUPPORTED: Host does not support the attached peripheral.
+OTG_EVENT_HNP_FAILED: HNP failed due to not meeting protocol timings.
+OTG_EVENT_NO_RESP_FOR_SRP: No Response for B-device SRP request.
+
+set_power: DCD can use otg_set_power() API to specify about the current that
+can be withdrawn from the VBUS for charging. Based on the current OTG state
+and whether ACA is attached or not, OTG driver makes a decision about the
+charging current and calls the charging APIs.
+
+The following sysfs nodes are provided at /sys/devices/platform/msm_otg
+
+pwr_down: This node can be used to control A-device session. a_bus_drop and
+a_bus_req state machine input variables are altered to start/stop session.
+Write to this node is invalid when device operating as a B-device.
+
+start_srp: This node can be used for requesting session. If all initial
+conditions of SRP are met, SRP is initiated. Write to this node is invalid
+when device operating as an A-device.
+
+clr_err: This node can be used to clear over-current condition. Write to this
+node is invalid when operating as an B-device. Error condition is
+automatically cleared when Id becomes false.
+
+The following sysfs nodes are provided at /sys/devices/platform/msm_hsusb/otg
+
+host_request: This node can be used for requesting host role. A-device shall
+select a_hnp_support feature prior to configuration and poll B-device for host
+request. When '1' is written to this node, host request is asserted. This node
+can also be used for taking host role when A-device operating as a peripheral.
+
+hnp_avail: User space can check this node before requesting the host role.
+Gadget controller driver asserts its internal variable hnp_avail when HNP
+polling request is send by the Host.
+
+Dependencies
+============
+
+If USB clocks are controlled by modem processor, proc_comm interface is used
+to turn on/off clocks.
+
+If VBUS power is controlled by modem processor, RPC interface is used to turn
+on/off VBUS power.
+
+Config options
+==============
+
+CONFIG_USB_MSM_ACA: Enable support for Accessory Charger Adapter (ACA)
+CONFIG_ENABLE_MSM_OTG_A_WAIT_BCON_TIMEOUT: Enable A_WAIT_BCON timeout. VBUS
+will be turned off and SRP detection is enabled upon this timeout. If this
+config is not selected, VBUS will not be turned off when Mini/Micro-A cable
+is connected. But hardware is put into LPM.
+
+Other
+=====
+On-The-Go and Embedded Host Supplement to the USB Revision 2.0 Specification
+(Revision 2.0) found at http://www.usb.org/developers/onthego
+
+Known issues
+============
+Phy instability issues are observed when vbus_valid interrupt is enabled.
+Hence a_vbus_vld state machine variable is explicitly asserted after
+a_wait_vrise timer expiration.
+
+Spurious interrupt is seen when trying to put PHY in Low Power Mode with
+ID_A/B/C interrupts enabled in the PHY. As a result of which PHY doesn't stay
+in LPM. Hence, ID_A/B/C interrupts are disabled before entering LPM, and
+enabled while returning.
+
+To do
+=====
+
+Verify SRP detection on all targets.
+
+Phy instability issues are observed when A-Vbus Valid interrupt is enabled.
+But without this interrupt over current condition can not be determined. Root
+cause analysis for PHY instability issue and alternative methods like PMIC
+interrupt are being pursued.