Processor SDK RTOS USB

From Texas Instruments Wiki
Jump to: navigation, search

RTOS Software Developer Guide USB


User Interface




Driver Overview

PDK USB driver (USB LLD) provides the following USB class functions while isolating application from the complexity of low level USB and USB class protocols:

  • USB device Mass Storage Class
  • USB host Mass Storage Class

In rest of the page AM437x EVM is being refered as an example. Please check Release Notes for list of supported EVMs for driver.

Modes of Operation

  • USB device Mass Storage Class

In this mode, a user-selected USB instance of the EVM will be working in device mode and will behave like a USB thumb drive. It uses part of the EVM DDR memory and exposes it as a physical storage for another USB host application. After the host PC enumerates this EVM-thumb drive, the PC will see a USB storage device. This EVM-thumb drive is not yet formatted with any file system and requires user to format it before use.

USB MSC device.PNG

The following screen shots show what one would expect when running the device mode demo application and plugging in a USB cable from the EVM USB port #0 to a PC running Windows

Printout from demo application:

Device mode printout.png

The MSC device is detected in Windows:

Device mode detected in windows.png

After formatting it, it can be seen in Windows Disk Management Tool and is ready to use

Usb device mode in disk management.png

Files can be copied over to the newly mounted and formatted MSC drive

Device mode mounted copied.png

  • USB host Mass Storage Class

In this mode, the USB instance will act as a USB host communicating with a USB device that supports Mass Storage Class function (USB thumb drive or a small USB hard drive). The demo example code utilizes a shell interface via the EVM via UART for interaction with the example. The shell provides some basic commands to manipulate the content of the attached USB disk drive.


Screenshot of a MSC host mode example running in RTOS after plugging in a USB thumb drive into USB port #1

Host shell screen shot.png

Driver Configuration

  • Data Structures:
    • tUSBDMSCDevice: Defined in usbdmsc.h. It is used in USB device mode application. This structure must be filled with the intended vendor and product ID as well as other product information and also the function pointers to functions that handle the disk functions (open/read/write/close, etc.). These product information will show up in the device and interface USB descriptors that are used during device enumeration. This device MSC class data is then assigned to the field usbClassData of the USB_Params bellow.
    • USB params: USB_Params structure is declared in usb_drv.h. This structure must be provided to the USB driver. It must be initialized before the USB_open() function is called.
    • USB APIs: main USB LLD and USB MSC API’s are declared in usb_drv.h and usbdmsc.h and usbhmsc.h provided in the root USB LLD directory.

  • General USB LLD expectations:

The USB LLD will setup appropriate USB clock and power domains for the particular SOC being in used as part of its “device specific peripheral” functions.

After the USB_open() is called, the driver expects the application code to sets up USB interrupts with the interrupt handler being the USB LLD provided interrupt handler. Then the application have to call the USB LLD provided API USB_irqConfig() which enables USB module’s interrupts. In device mode, both USB core and USB misc interrupts are used in the USB device MSC application. In host mode, the USB host MSC only uses USB core interrupts.

After these steps, application code then can expect to have USB enumeration done and start USB transfer through the provided APIs.

API Call Flow

  • USB Device MSC

The example application code uses the USB library, configures it as a USB device with MSC function. The example also provides functional codes that access a RAM disk (included from the Utils library in the included Starterware). The LLD calls these MSC back-ends functions to access the RAM disk. User can replace these functions with other functions that access other types of media or devices (MMCSD for example). The RAM disk image provided in the example demo application is not currently formatted. Thus the once enumerated, the PC will require the USB disc to be formatted before use.

Below diagram is the sequence of API calls that starts the USB device MSC application. All USB events are handled internally in the LLD and in the interrupt context.

USB MSC device API flow.PNG

User provided disk functions will be called from the LLD to handle the actual physical disk access. The overview of USB Device MSC example application:

USB MSC device example blocks.PNG

The content of the file: usb_msc_structs.c can be replaced with customer USB device information (PID/VID, device names, etc.)

  • USB Host MSC

The LLD also provides a USB host MSC example. The USB LLD is acting as a USB host, waiting for a USB thumb drive/memory stick to be plugged in. A console with a simple shell command is also provided so that the demo example can display and manipulated content of the USB device.

The following is how the USB host MSC example demo is organized:

USB MSC host example blocks.PNG

The following is the sequence of the APIs that were used:

USB MSC host API flow.PNG


Bare-metal and RTOS/BIOS examples of the USB device and USB host MSC are provided with the USB LLD. Please see the readme.txt in the docs directory for more info on how to build the example/demo application. Refer SDK release notes for supported EVMs.

Example Name EVM's Additional Notes
usb_dev_msc AM437x EVM Can only run on the USB device port (USB#0)
usb_host_msc AM437x EVM Can work for both USB#0 and USB#1. Demo application is using USB#1.
USB#0 would need a micro USB host OTG adapter to work in host mode