383 lines
19 KiB
Plaintext
383 lines
19 KiB
Plaintext
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.
|