UserGuideUsbDriver PSP 04 02 00 07

USB Driver

Introduction

TI OMAP35x, AM3517, AM/DM37x have a host cum gadget controller MUSB OTG, an EHCI and its companion OHCI controller. There are three USB ports which are to be controlled by either EHCI or OHCI controller individually.

Ports has to be connected to high speed USB phy to act as an EHCI port and similarly it should be connected to full speed USB phy to act as an OHCI port. We don't need these USB phys in TLL mode of operations.

In ES2.0/2.1 silicon all the three port can either be configured in PHY mode or in TLL mode at a time. This limitation got resolved in ES3.0/3.1 silicon where PHY/TLL mode selection can be done on per port basis.

Supported features

The salient features of the MUSB OTG controller are:

Common feature

• High/full speed operation as USB peripheral.
• High/full/low speed operation as Host controller.
• The host controller for a multi-point USB system (when connected via hub).
• USB On-The-Go compliant USB controller.
• 15 Transmit and 15 Receive Endpoints other than the mandatory Control Endpoint 0.
• Double buffering FIFO.
• Support for Bulk split and Bulk combine
• Support for high bandwidth Isochronous transfer

OMAP35x, AM/DM37x

• 16 Kilobytes of Endpoint FIFO RAM for USB packet buffering.
• Dual Mode HS DMA controller with 8 channels.

AM3517

• 32 Kilobytes of Endpoint FIFO RAM for USB packet buffering.
• CPPI4.1 DMA controller with 15 Rx and 15 Tx channels.

References

• OMAP35x, AM/DM37x Technical Reference Manual
• AM3517 Technical Reference Manual

Hardware Overview

OMAP35x, AM/DM37x

The OMAP35x MUSB OTG controller sits on the L3 and L4 interconnect.It can be an L3 master while performing DMA transfers and an L4 target when host CPU/DMA engine is the master.

OMAP3EVM-1 (<=Rev-E) has an OTG compliant USB PHY from NXP (ISP 1504)and OMAP3EVM-2 (>=Rev-E) has NXP USB PHY ISP1507.

HS USB port2 is connected to SMSC USB83320 high speed PHY on Mistral/Multimedia daughter card (MMDC) attached to OMAP3EVM-1 (<=Rev-E) whereas on OMAP3EVM-2 (>=Rev-E) it is connected to SMSC USB3320 PHY. Port1 and Port3 are not available either on MMDC attached to OMAP3EVM-1 (<=Rev-E) or OMAP3EVM-2 (>=Rev-E).

AM3517

AM3517 HS USB port1 is connected to SMSC3320 high speed PHY and available on baseboard while port2 is connected to same SMSC PHY but is available on UI card. Port2 will be functional only if LCD is not in use.This limitation is due to shared pinmux.

Features

The MUSB OTG and EHCI driver supports a significant subset of all the features provided by the USB controller. The following section discusses the features supported in this release.

Supported feature on MUSB OTG port

• Can be built in-kernel (part of vmlinux) as well as a driver module (musb_hdrc.ko).
• Audio Class in Host mode.
• Video Class in Host mode.
• Mass Storage Class in Host mode.
• Mass Storage Class in Gadget mode.
• Hub Class in Host mode.
• Human Interface Devices (HID) in Host mode.
• Communication Device Class (CDC) in Gadget mode.
• Remote Network Driver Interface Specification (RNDIS) Gadget support.
• OTG support which includes support for Host Negotiation Protocol (HNP) and Session Request Protocol (SRP).

Supported feature on EHCI port

• Can be built in-kernel (part of vmlinux) as well as a driver module (ehci_hcd.ko).
• Human Interface Devices (HID) via a high speed hub.
• Mass Storage Class.
• Audio Class.
• Video Class.
• Hub Class.

Not supported

• OHCI is not supported as OHCI port is not available either on OMAP35x, AM/DM37x or AM3517 EVMs

Driver configuration

The MUSB OTG controller is used in Host and Gadget modes while EHCI is used only in Host mode.The following section shows the configuration options for USB and its associated class drivers.

USB phy selection for MUSB OTG port

Please select NOP USB transceiver for MUSB support.

 Device Drivers --->
 USB support --->
 *** OTG and related infrastructure ***
 [ ] GPIO based peripheral-only VBUS sensing 'transceiver'
 [ ] Philips ISP1301 with OMAP OTG
 [ ] TWL4030 USB Transceiver Driver
 [*] NOP USB Transceiver Driver

USB controller in host mode

MUSB OTG Host Configuration

 Device Drivers --->
 USB support --->
 <*> Support for Host-side USB
     *** Miscellaneous USB options ***
 [*] USB device filesystem
 [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
 <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           *** Platform Glue Layer ***
 <>     TUSB6010
 <*>     OMAP2430 and onwards
 <>     AM35x  
           Driver Mode (USB Host) --->
 [ ] Disable DMA (always use PIO)
 [*] Use System DMA for Mentor DMA workaround 
 [*] Enable debugging messages

• Please enable "Use System DMA for Mentor DMA workaround" on OMAP35x/AM37x as a workaround to Mentor DMA issues.

EHCI Configuration

Port-2 will automatically be selected for OMAP35x, AM/DM37x EVM and would be configured in PHY mode.Port-1 will automatically be selected for AM3517 EVM while port-2 will be enabled only if LCD is not configured.

 Device Drivers --->
 USB support --->
 <*> Support for Host-side USB
     *** Miscellaneous USB options ***
 [*] USB device filesystem
 [*] USB device class-devices (DEPRECATED)
 <*> EHCI HCD (USB2.0) Support
 [ ] Root hub transaction translators
 [*] Improved Transaction Translator scheduling
     *** USB Host Controller Drivers ***

MUSB OTG controller in gadget mode

Configuration

Please do not disable support for host side usb as this will disable EHCI host interface also. Gadget option in driver mode will appear only when gadget support is also selected. Please enable gadget support as given below.

 Device Drivers --->
 USB support --->
   <*> USB Gadget Support --->
       [ ] Debugging messages (DEVELOPMENT)
       [ ] Debugging information files (DEVELOPMENT)
       [ ]   Debugging information files in debugfs (DEVELOPMENT)
       (2) Maximum VBUS power usage (2-500mA) NEW
   USB Peripheral Controller (Inventra HDRC Peripheral(TI,ADI, ...)) --->
   <M> USB Gadget Drivers
   <M> File-backed Storage Gadget

Please make sure that Inventra HDRC is selected as USB peripheral controller which will appear only when "USB Peripheral (gadget stack)" is selected in driver mode as shown below so after selecting Gadget Support go back to driver mode option to select "USB Peripheral (gadget stack)" and then come back again to select Inventra HDRC as USB peripheral controller.

 Device Drivers --->
 USB support --->
 <*> Support for Host-side USB
     *** Miscellaneous USB options ***
 [*] USB device filesystem
 [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
 <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
 <>     TUSB6010
 <*>     OMAP2430 and onwards
 <>     AM35x  
           Driver Mode (USB Peripheral (gadget stack)) --->
 [ ] Disable DMA (always use PIO)
 [*] Use System DMA for Mentor DMA workaround
 [*] Enable debugging messages

MUSB OTG controller in OTG mode

OTG Configuration

Both Host and Gadget driver should be selected for OTG support.If gadget driver is build as module then the host side module will be initialized only after gadget module is inserted after bootup.

If "Rely on targeted peripheral list" is also selected then make sure to update drivers/usb/core/otg_whitelist.h with the desired supported device class identification ids.

OTG option in driver mode will appear only when gadget support is also selected.Please enable gadget support as given below.

  Device Drivers --->
  USB support --->
   <*> USB Gadget Support --->
       [ ] Debugging messages (DEVELOPMENT)
       [ ] Debugging information files (DEVELOPMENT)
       [ ]   Debugging information files in debugfs (DEVELOPMENT)
       (2) Maximum VBUS power usage (2-500mA) NEW
   USB Peripheral Controller (Inventra HDRC Peripheral(TI,ADI, ...)) --->
   <M> USB Gadget Drivers
   <M> File-backed Storage Gadget

Please make sure that Inventra HDRC is selected as USB peripheral controller which will appear only when OTG is selected as below.

 Device Drivers --->
 USB support --->
 <*> Support for Host-side USB
     *** Miscellaneous USB options ***
 [*] USB device filesystem
 [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
 <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
 <>     TUSB6010
 <*>     OMAP2430 and onwards
 <>     AM35x  
           Driver Mode (Both Host and peripheral : USB OTG (On The Go) Device) --->
 [ ] Disable DMA (always use PIO)
 [*] Use System DMA for Mentor DMA workaround
 [*] Enable debugging messages

Host mode applications

Mass Storage Driver

This figure illustrates the stack diagram of the system with USB Mass Storage class.

Configuration

    Device Drivers --->
    SCSI device support --->
     <*> SCSI device support
     [*] legacy /proc/scsi/support
     --- SCSI support type (disk, tape, CD-ROM)
     <*> SCSI disk support
    USB support --->
     <*> Support for Host-side USB
     *** Miscellaneous USB options ***
     [*] USB device filesystem
     [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (Both Host and peripheral : USB OTG (On The Go) Device) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages
      --- USB Device Class drivers
      <*> USB Mass Storage support

Device nodes

The SCSI sub system creates /dev/sd* devices with help of mdev.

USB HID Class

USB Mouse and Keyboards that conform to the USB HID specifications are supported.

Configuration

    Device Drivers --->
    USB support --->
     <*> Support for Host-side USB
     *** Miscellaneous USB options ***
     [*] USB device filesystem
     [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (Both Host and peripheral : USB OTG (On The Go) Device) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages
    HID Devices --->
     <*> Generic HID Support
               *** USB Input Devices ***
     <*> USB Human Interface Device(full HID) support

Device nodes

The event sub system creates /dev/input/event* devices with the help of mdev.

USB Audio

The image below shows the USB stack architecture with USB Audio/Video class.

Configuration

   Device Drivers --->
   Sound --->
    <*> Sound card support
      Advanced Linux Sound Architecture --->
      <*> Advanced Linux Sound Architecture
      [*] Dynamic device file minor number
      [*] Support old ALSA API
         USB devices --->
         <*> USB Audio/MIDI driver
   USB support --->
      <*> Support for Host-side USB
      *** Miscellaneous USB options ***
      [*] USB device filesystem
      [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (Both Host and peripheral : USB OTG (On The Go) Device) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages

Resources

For testing USB Audio support we need any ALSA compliant audio player/capture application. Kindly read the Audio driver section to get more inputs on this.

USB Video

Configuration

  Device Drivers --->
    Multimedia devices --->
          *** Multimedia core support ***
      <*> Video for Linux
      [*] Enable Video for Linux API 1 (DEPRICATED)
      [*] Enable Video for Linux API 1 (compatible) layer
          *** Multimedia Drivers ***
      [*] Video capture adapters --->
          [*] V4L USB devices --->
              <*> USB Video Class (UVC)
    USB Support --->
      <*> Support for Host-side USB
      *** Miscellaneous USB options ***
      [*] USB device filesystem
      [*] USB device class-devices (DEPRECATED)
     *** USB Host Controller Drivers ***
    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (Both Host and peripheral : USB OTG (On The Go) Device) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages

Resources

For testing USB Video support we need a user level application like mplayer to stream video from an USB camera. If you are using mplayer as the capture application, then you must export the DISPLAY to a X server. Then, execute the following command:

 $ mplayer tv:// -tv driver=v4l2:width=320:height=240

Gadget Mode Applications

Mass Storage Gadget

This is the Mass storage gadget driver.

Configuration

  Device Drivers --->
  USB support --->
   <*> Support for USB Gadgets
   USB Peripheral Controller (Inventra HDRC Peripheral(TI, ...)) --->
   <M> USB Gadget Drivers
   <M> File-backed Storage Gadget

    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (USB Peripheral (gadget stack)) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages

Installation of File Storage Gadget Driver

Let us assume that we are interested in exposing /dev/mmcblk0 block device to the file storage gadget driver. To that effect we need to issue the following command to load the file storage gadget driver.

 $ insmod <g_file_storage.ko> file=/dev/mmcblk0 stall=0

CDC/RNDIS gadget

The CDC/RNDIS gadget driver that is used to send standard Ethernet frames using USB. Please enable "Use System DMA for Rx endpoints" to fix the flood ping hang issue with packet size of more than 16KB on OMAP35x due to Mentor DMA lockup issue.

The image below shows the USB stack architecture with CDC/RNDIS gadget.

Configuration for USB controller and CDC/RNDIS Gadget

Device Drivers --->
USB support --->
<*> Support for USB Gadgets
USB Peripheral Controller (Inventra HDRC Peripheral (TI, ...)) --->
<M> USB Gadget Drivers
<M> Ethernet Gadget
[*]   RNDIS support (EXPERIMENTAL) (NEW)

    <*> Inventra Highspeed Dual Role Controller (TI, ADI, ...)
           **** Platform Glue Layer ***
    <>     TUSB6010
    <*>     OMAP2430 and onwards
    <>     AM35x  
           Driver Mode (USB Peripheral (gadget stack)) --->
    [ ] Disable DMA (always use PIO)
    [*] Use System DMA for Mentor DMA workaround
    [*] Enable debugging messages

Please do not select RNDIS support for testing ethernet gadget with Linux 2.4, IXIA and MACOS host machine.

 USB Peripheral Controller (Inventra HDRC Peripheral (TI, ...)) --->
 <M> USB Gadget Drivers
 <M> Ethernet Gadget
 [ ]   RNDIS support (EXPERIMENTAL) (NEW)

Installation of CDC/RNDIS Gadget Driver

Installing the CDC/RNDIS gadget driver is as follows:

 $ insmod  <path to g_ether.ko>

Setting up USBNet

The CDC/RNDIS Gadget driver will create a Ethernet device by the name usb0. You need to assign an IP address to the device and bring up the device. The typical command for that would be:

 $ ifconfig usb0  <IP_ADDR> netmask 255.255.255.0 up

Modular testing on MUSB

Mentor USB (MUSB) linux driver has been reorganized in v2.6.37 to support multi platform config. Modular structure has also changed due to this and thus now onward there will be below modules on MUSB

1. musb_hdrc.ko: The core controller module.
2. cppi41dma.ko or musbhsdma.ko: The dma controller module. 
3. am35x.ko or omap2430.ko: The platform glue module.
4. g_file_storage.ko or g_ether.ko: The gadget controller module.

All the above four modules need to be inserted sequentially for an OTG (both host and device) configured or gadget only configured kernel. Fourth module (gadget controller) would not be needed in a host only config.

USB EHCI Electrical testing

USB EHCI electrical test is supported in software. Please use below command to perform various electrical tests.

 $ echo 'Options' > sys/devices/platform/ehci-omap.0/portN
 Where 'options' can be,
 reset   --> Reset Device
 t-j     --> Send TEST_J on suspended port
 t-k     --> Send TEST_K on suspended port
 t-pkt   --> Send TEST_PACKET[53] on suspended port
 t-force --> Send TEST_FORCE_ENABLE on suspended port
 t-se0   --> Send TEST_SE0_NAK on suspended port

USB OTG (HNP/SRP) testing

Please choose the configuration as described in driver configuration section for OTG and follow the steps below for testing.

• 1. Boot the OTG build image on two OMAP35x EVM.
• 2. If gadget driver is built as module then insert it to complete USB initialization.
• 3. Connect mini-A side of the OTG cable to one of the EVM (say EVM-1) and mini-B side on the other (say EVM-2).

In this scenario EVM-1 will become initial host or A-device and EVM-2 will become initial device or B-device. A-device will provide bus power throughout the bus communication even if it becomes peripheral using HNP.

There will not be any connect event at this point of time as Vbus power is not yet switched-on. Vbus power can be switched-on from A-device or from B-device using SRP.

• 4. Request to switch-on the Vbus power using below command on any EVM.

 $ echo "F" > /proc/driver/musb_hdrc.0

If this command is executed on B-device then SRP protocol will be used to request A-device to switch-on the Vbus power.

• 5. Now the connect event occurs, enumeration will complete and gadget driver on B-device will be ready to use if this driver is in "Targeted Peripheral List (TPL)" of A-device.

If TPL is disabled on A-device then gadget driver will be ready to use soon after enumeration.

If TPL is enabled and gadget driver of B-device is not in TPL list of A-device then there will be an automatic trial of HNP from usb core by suspending the bus. This will cause a role switch and B-device will enumerate A-device. Now the gadget driver of A-device will be configured if it is on the TPL list of B-device.

Currently this is the only way possible for HNP testing but we have added a suspend proc entry to start HNP in other than this scenario.

• 6. Complete all the communication between A-device and B-device.
• 7. Start HNP by executing below command on host side.

 $ echo "S" > /proc/driver/musb_hdrc.0

It will suspend the bus and role-switch will follow after that.

• 8. Repeat step 4, 5, 6 and 7 for further testing.

Software Interface

The USB driver exposes its state/control through the sysfs and the procfs interfaces. The following sections talks about these.

sysfs

sysfs attribute	Description
mode	The entry /sys/devices/platform/musb_hdrc.0/mode is a read-only entry. It will show the state of the OTG (though this feature is not supported) state machine. This will be true even if the driver has been compiled without OTG support. Only the states like A_HOST, B_PERIPHERAL, that makes sense for non-OTG will show up.
vbus	The entry /sys/devices/platform/musb_hdrc.0/vbus is a write-only entry. It is used to set the VBUS timeout value during OTG. If the current OTG state is a_wait_bcon then then urb submission is disabled.

procfs

The procfs entry /proc/driver/musb_hdrc.0 is used to control the driver behaviour as well as check the status of the driver.

• 1. The following command will show the usage of this proc entry

 $ echo "?" > /proc/driver/musb_hdrc.0

• 2. Specifically the most important usage of this entry would be to start an USB session(host mode) by issuing the following command:

 $ echo "F" > /proc/driver/musb_hdrc.0