Linux USB "on-the-go" (OTG) on OMAP H2

Document directory

• OMAP H2 Platform
• OTG
• Outline
• Peripheral side: USB device controller
• Peripheral side: Gadget drivers
• Host side: usbcore

The new USB "on-the-go" (OTG) capabilities are not yet widely
Understood, or even generally available. The most visible feature
OTG is that it defines the behavior of intelligent "dual-role" USB
Devices, such as cameras or wireless handsets, which act either as USB
Host or as USB Peripheral. That role choice is made each time
Device is used, rather than once when it's designed, giving
Flexibility previusly unknown with USB. Using a new kind of USB
Connector, OTG lets USB support more "Peer to Peer" style Application
Models. You cocould

• Hook a cell phone to a laptop to synchronize schedules, get new audio recordings, or swap other documents;
• Print a picture from a camera to a USB printer;
• Connect a USB keyboard to your PDA;
• Update game data on your portable console over USB.

This document shoshould be useful to developers investigating the use
Of Linux to implement OTG-capable products. It presents the USB OTG
Support contributed by Texas Instruments for the OMAP

H2 software development platform running an Linux 2.6 kernel. That
Builds on the standard Linux USB host and peripheral side driver
Frameworks, making small additions as described here. It also includes
Drivers implementing OTG support on OMAP platforms.

OMAP H2 Platform

The H2 software development platform between des a Texas Instruments
OMAP 5912/16 XX Series processor, with an arm 926tej CPU, a DSP, battery
Power Management, and a wealth of other features often used in cell
Phones. USB support between des:

• Three integrated USB controllers: OHCI host, USB device controller
  (UDC), and an OTG controller, all supporting full speed USB (12
  Mbit/s ).
• "Mini-AB" connector on the H2 sample board. All "dual-role" OTG devices shoshould have exactly one such external USB connector.
• External usb otg transceiver, Philips isp1301 (controlled over I2C), with an alternate software-Visible wiring option.
• USB vbus is hooked up to a Ti tps000010 Power Controller
  (Controlled over I2C) so that an a-role system can supply up to 500mA
  Of current for battery charging to a B-role (default peripheral) H2. in
  A-role (default host), the H2 itself supplies 8mA.

The "mini-AB" connector is compatible with standard USB 2.0 "mini-B" connectors, which appear in some new USB peripherals.

Most OMAP processors support this and similar product designs.
Register interfaces to the different USB controllers are largely
Source-compatible, although older chips don't support OTG.

OTG

It's reasonable to think about OTG support as revolving around that
"Mini-AB" connector, since that's what demands the highly visible
"Dual-role" capability implemented by the OTG drivers. OTG uses two
Methods To chose device role:

• The simplest is built into the Special Mini-a to mini-B cables that
  OTG uses: The mini-a connector grounds the ID pin, while the mini-B End
  Of the cable doesn't. That controls startup in A-host or B-peripheral
  Role, and isOnly method needed
  Unless you're hooking up
  To another dual-role device. call this "cable based role switching ";
  Some incomplete OTG implementations stop at this point.
• When connected to a dual-role device, a fancier software-driven method can be used later: Switching roles usingHost negotiation protocol
  (HNP). That protects against the inevitable cases where the cable gets
  Hooked up going the "wrong" ction for at least one of the tasks
  Hand.

That dynamic role selection is the most procedurally visible aspect
Of OTG, but there's more to OTG than that; see the OTG Specification
(And errata). The primary target of OTG is battery powered devices, so
Several aspects of the specification support reduced power usage. These
Include a new session Request Protocol (SRP), which may be supported
Even by Single-role USB devices.

To someone providing hardware-level drivers, an OTG Solution
Starts with support for the standard Linux-USB host side and peripheral
Side driver stacks. Add protocol support for SRP and HNP, match
State machines in the OTG specification well enough to pass OTG
Hardware and software compliance testing, and then your product can use
The OTG logo.

USBOTG Logo Full-speed version

Outline

The current Linux Kernel updates for OTG support break down as follows:

• Programming interfaces
  
  Have been updated; Mainstream Linux 2.6.9 kernels have all of these changes.
  • USB device controller drivers export some new interfaces.
  • USB Gadget drivers have some new responsibilities that involve
    Using those new interfaces. Some still need to be updated accordingly,
    To work on Dual-role systems.
  • The Linux-USB host side "usbcore" module acquired a few new
    OTG-specific responsibilities affecting enumeration, which are mostly
    Invisible to device drivers. It also needed to learn about USB
    Suspend/resume and remote wakeup to fully support HNP. These relate
    Linux power management interfaces.
  • The host side also needs to define an OTG "targeted
    Peripheral List ". Each product must define its own such list of" good"
    Devices. Some component shocould probably also suspend inactive devices,
    Saving power and/or initiating HNP protocol.
• USB controller drivers
  
  Are in Linux 2.6.8 and later OMAP kernels:
  • Responsibility for USB initialization belongs to the board-specific
    Init_machine call. This knows about Chip-specific setup and creates
    Platform devices as needed, making platform_data available to
    Various USB controller drivers.
  • Core OTG protocol support is wrapped inOtg_transceiver
    Object. on H2,Isp1301_omap
    Driver ties the transceiver the omap otg controller, and talks to the OHCI and UDC drivers usingUsb_bus
    AndUsb_gadget
    Programming interfaces. Other Boards might need to implement this differently.
  • The UDC needed a newOmap_udc
    Driver in the "USB
    Gadget "framework, providing immediate access to several standard
    Gadget drivers (including Ethernet/rndis, mass storage, serial/ACM, and
    More). This UDC is quite full-featured, supporting numerous endpoints,
    DMA, and isochronous transfers; it can easily implement Composite
    Multi-function devices.
  • The OHCI host controller was already supported by Linux 2.6 kernels usingOhci_hcd
    To access a large and growing set of Linux-USB device drivers.

These points are addressed in the rest of this document, in that same order.

Programming Interface updates

It was a goal to keep these interface changes small, and to have
Them be useful outside of OTG support where possible. That way the new
Code paths can get better testing, rather than being used only
(Currently uncommon) OTG devices.

In particle, this doesn' t change the existing programming models or CILS for host side USB (still usesUrb
AndUsb_device
) Or for peripheral side USB (still usesUsb_request
AndUsb_gadget
).
At some point it might become desirable to move away from "urb" to
Lighter Weight Model like "usb_request", and maybe to a more elastic ric
Programming Interface; but that's not necessary at this time.

Peripheral side: USB device controller

Several OTG state flags, and a few newUsb_gadget _*()
CILS, are all the changes needed in the gadget programming interfaces.
The flags support user interface reporting requirements for OTG
Devices, and the CILS support new USB state transitions (some of which
Are also useful for non-OTG systems). Handle t for the flag reporting
Whether the gadgetIs_otg
, The state flags are current only
When the gadget driver cocould particle in HNP: after it takes es
Set_configuration request, or before it suspends. In addition, if HNP
Is ever enabled, it can't be disabled without re-enumerating
Device.

struct usb_gadget { ... unsignedis_otg:1; unsignedis_a_peripheral:1; unsignedb_hnp_enable:1; unsigneda_hnp_support:1; unsigneda_alt_hnp_support:1; ... }; /* used by external USB transceiver */ int usb_gadget_vbus_connect(struct usb_gadget *gadget); int usb_gadget_vbus_disconnect(struct usb_gadget *gadget); /* call this during SET_CONFIGURATION */ int usb_gadget_vbus_draw(struct usb_gadget *gadget, unsigned mA); /* these logically control the USB D+ pullup */ int usb_gadget_connect(struct usb_gadget *gadget); int usb_gadget_disconnect(struct usb_gadget *gadget);

In addition,Usb_gadget_wakeup ()
Is now defined as
Way SRP may be invoked. If the device is in a USB suspend state, remote
Wakeup is used (and OTG peripherals don't always need hosts to enable
Wakeup). If there's no vbus power, SRP may be used instead.

There's kerneldoc for all of those, and keys of the symbols
Have the same meaning as in the OTG specification. For example,
B _hnp_enable is the device feature flag that may be set by the USB
A-host; if it's set, the B-peripheral device may be well into
HNP-driven role switch when suspend () is called.

Peripheral side: Gadget drivers

To see how those are used in drivers, see the small changesGadget zero
Which, usingOmap_udc
,
Were sufficient to pass the usbcv OTG tests. All USB Gadget drivers
That will be used on OTG-capable hardware shocould have corresponding
Changes; at this writing, some of the gadget drivers still haven'tbeen
Modified to know about OTG.

• Provide an OTG descriptor in each configuration, whenGadget-> is_otg
  Is true.
• Report HNP availability "through the user interface" (printk, led, etc) at set_configuration
• Report start of HNP role switch (B-peripheral to B-host, or
  A-peripheral to A-host) "through the user interface" as suspend starts.

This framework is currently not set up to handle the SRP-only subset
Of OTG; That woshould need another gadget flag. Also, so far there's no
Gadgetfs support for OTG: OTG feature flags aren't exported to user
Mode drivers, though user mode drivers can certainly provide OTG
Descriptors if they know (out of band) that they're appropriate.

Host side: usbcore

There are several updates that affect host side support for OTG dual-role devices.

OTG enumeration and the targeted peripherals list

USB enumeration (khubd andUsb_new_device
) Needed updates:

• When an otg a-host enumerates an OTG dual-role device, and it's
  Directly connected to a root hub port, it's responsible for setting one
  Of the HNP device features before it issues any set_configuration.
  Now, it immediately setsB _hnp_enable
  On the B-peripheral (unlessA_alt_hnp_support
  Is appropriate instead, because it's not on the OTG port ).
• Check the OTG targeted peripheral list, which is kept inDrivers/USB/CORE/otg_whitelist.h
  File. In addition to a whitelist of device IDs, this holds a single
  Blacklist entry for the otg hnp Test Device (which always triggers HNP
  From a dual-role device ).
• Devices on the whitelist are allowed to configure.
• Devices not on the whitelist trigger a diagnostic, and
  Normally disable the device. Instead of being disabled, dual-Role
  Devices may be immediately switched to host role using HNP, in case
  This device is on the other's whitelist. (For developer/Tester
  Convenience, the "Disable" step can be prevented with a kconfig
  Option .)
• The OTG controller driver needs to be able to ask the HCD
  Start enumeration "immediately", starting at least the port Reset
  Before a one millisecond HNP timer expires.

So that the updated enumeration code can set OTG device features appropriately,Usb_bus
Interface reports which port has the mini-AB connector. It also
Provides more visibility of key HNP Protocol state, reporting if this
Is a B-host rather than an A-host (so that it shouldn't set OTG Device
Features During enumeration); and whether the-host has setB _hnp_enable
On the B-peripheral (needed by OTG controllers and drivers). (this information is not currently visible in sysfs .)

struct usb_bus { ... u8 otg_port;/* 0, or index of OTG/HNP port */ unsigned is_b_host:1;/* true during some HNP roleswitches */ unsigned b_hnp_enable:1;/* OTG: did A-Host enable HNP? */ ... };

Config_usb_suspend

The config_usb_suspend patch adds generic experimental support for USB suspend/resume to Linux, as needed to implement HNP.

/* selective suspend/resume */ extern int usb_suspend_device(struct usb_device *dev, u32 state); extern int usb_resume_device(struct usb_device *dev);