SitaraWare USB User Guide

IMPORTANT - The content of this page is due to change quite frequently and thus the quality and accuracy are not guaranteed until this message has been removed. For suggestion/recommendation, please send mail to your local FAE.

SitaraWare USB

Introduction

The SitaraWare USB stack is a non OS based USB solution which is migrated from the StellarisWare. StellarisWare USB library user's guide can be found here. 

The API refernce guide for SitaraWare USB is available as part of release package.

Current SitaraWare release package supports only the following features:-

• CDC in device mode (PIO mode)
• HID in device mode (PIO mode)
• MSC in decive mode ( DMA mode and PIO mode)

Sitara and Stellaris USB

The below table provides a comparison of sitaraware and stellarisware USB features.

Feature	Sitara (AM1808) USB Subsystem	Stellaris USB Subsystem
Core IP	MUSB	MUSB
Number Of Endpoints	4 + 1	15 + 1
DMA	CPPI DMA	Micro DMA
Mapped to Wrapper Registers	Yes, Only the Interrupt registers	No
Endpoint 0 FIFO size	64 Bytes	64 Bytes
Other Endpoint FIFO	8 to 8192 bytes configurable	8 to 8192 bytes configurable
Speed	Full speed and High Speed	High Speed Not Supported

The Core Design

The below picture shows the architecture of SitaraWare USB

 

Mentor Controller Device Abstraction Layer (MUSB DAL)

The USBOTG Subsystem is based on Mentor Graphics USB Controller. IP core supports 4Tx/4Rx endpoints and integrated CPPI41 DMA engine. The Device Abstraction layer is the only module in SitaraWare USB which directly communicates with the Mentor controller. The MUSB DAL layers abstracts all the functionalities or services used by the layer above to configure and control the USB OTG Controller. The DAL APIs are used by the other components of device or host stack.

The MUSB DAL is implemented in single file (usb.c) and important APIs are as follows.

• USBDevConnect: - This API is called to the USB controller to the bus in device mode. This is used by the USB Core module during the initialization.
• USBDevDisconnect:- this API is used to remove the USB controller from the bus in device mode. This API is used by the USB core while unplugging or resetting the device.
• USBReset:- This API will reset the USB controller. This API is used by the core during enumeration or whenever the reset signal comes.
• USBEndpointDataPut:- This API puts data into the given endpoint's FIFO. This is used by the individual device stack.
• USBEndpointDataSend:- This API starts the transfer of data from an endpoint's FIFO. This is used by the individual device stack in order to send the data.
• USBEndpointDataGet:-This is API is used to retrieve data from the given endpoint's FIFO. This API is used by the individual device stack.

 

Device Core Layer

The Device Core Layer is responsible for the device enumeration and handling all the control transfers. The ISR is a part of the core and hence interrupt handling is also done by the core. The typical task of device core layer is as follows.

• Initialize the device controller driver.
• Enable the clocking to the USB controller.
• Switch on the UBS PHY.
• Enumeration handling.
• Handle the interrupts
• Handle the standard request.
• Terminate the device controller driver.

The standard request which can handle by the device core As follows.

• USBDGetStatus.
• USBDClearFeature.
• USBDSetFeature.
• USBDSetAddress.
• USBDGetDescriptor.
• USBDSetDescriptor.
• USBDGetConfiguration.
• USBDSetConfiguration.
• USBDGetInterface.
• USBDSetInterface.
• USBDSyncFrame.

Following are the list of interrupts which can handle by the device core layer.

• Reset
• Suspend
• Resume
• Disconnect
• Start of Frame (SOF)
• Endpoint Interrupt

The Init API in the core will be called by the class driver in order to start the enumeration. Once the enumeration is started, all the standard request routines will be called from the ISR based on the arrival of appropriate Interrupt. For any class specific request, the application / class driver has to register the call back handler with the core so that when the interrupt comes, the ISR can call it.

The device core layer is implemented using single file (usbdenum.c ). Following are the major APIs in this layer.

• USBDCDInit:- This API initialize the USB library device control driver for a given hardware controller. This is used by the individual class stack.
• USBDCDTerm:- This API free the USB library device control driver for a given hardware controller.
• USBDCDSendDataEP0:- This API requests transfer of data to the host on endpoint zero.
• USBDCDStallEP0:- This function generates a stall condition on endpoint zero.
• USBDeviceEnumHandler:- This is interrupt handler for endpoint zero.
• USBDeviceIntHandlerInternal:- The internal USB device interrupt handler.

 

USB Configuration Layer

This layer contains all the parameters to configure the USB device. The parameters are such as VID, PID, Descriptors, event handlers and buffers etc. These are the parameters decided by the application writer. Once all the information is fed in to this layer, the config layer can give a device instance structure to the inner layers. This device instance will contain all the information regarding the device and the required information will be extracted based on the request/ need.

This layer is a part of application, and most of the data is decided by the application programmer. This layer is implemented by the file usb_serial_structs.c. and following are the list of parameters which configurable by the application programmer for a USB device.

• A global instance for the USB device structure
• Rx and Tx Buffers
• Vendor ID
• Product ID
• Power Configuration parameters
• Control event call backs
• Application event call backs
• String descriptors
• Language descriptor.

 

System Configuration Layer

This layer provides APIs which can be used to configure the platform related parameters such as the clock speed, timers, pinmux etc. These parameters are used by the application developers as well as the driver developers. Some times the entire system behavior is depend on such parameters (Clock speed), hence it very important to select these parameter value carefully.

 

CDC Device Class design

The USB Communication Device Class (CDC) class driver supports the CDC Abstract Control Model variant and allows a client application to be seen as a virtual serial port to the USB host system. The driver provides two channels, one transmit and one receive. The channels may be used in conjunction with USB buffers to provide a simple read/write interface for data transfer to and from the host. Additional APIs and events are used to support serial-link-specific operations such as notification of UART errors, sending break conditions and setting communication line parameters The data transmission capabilities of this device class driver are very similar to the generic bulk class but, since this is a standard device class, the host operating system will likely be able to access the device without the need for any special additional device drivers. On Windows, for example, a simple INF file is all that is required to make the USB device appear as a COM port which can be accessed by any serial terminal application. This device class uses three endpoints in addition to endpoint zero. Two bulk endpoints carry data to and from the host and an interrupt IN endpoint is used to signal any serial errors such as break, framing error or parity error detected by the device. Endpoint zero carries standard USB requests and also CDC-specific requests which translate to events passed to the application via the control channel callback . This layer is implemented in file Usbdcdc.c

CDC Device class example application

CDC device enumeration

The Application main has to do the following steps

• Configure the system interrupts
• Register the Interrupt handler
• Initialize the buffers
• Call the USBDCDCInit with the device instance structure as a parameter.

With this call, the control is given to the CDC device class layer.

The device class layer has to do the following steps

• Assign the endpoints to the device instance structure
• Assign the configuration descriptor to the device instance structure.
• Call the USBDCDInit and pass the device instance structure to the core.

With this call the control is passed to the core layer.

The core layer has to do the following steps in order to complete the enumeration

• Enable the PSC clock
• Rest the USB module
• Switch on the phy
• Initialize the USB tick module
• Clear all the pending interrupts
• Enable the required interrupts
• Set the configuration parameters
• Disconnect the device
• And connect the device

Now the device will start receiving interrupts from the Host. The interrupt handler in the core layer will identify all the Ep0 interrupts and call the appropriate handler. By this way once if all the standard requests are serviced by the device then the enumeration is complete and the device is ready for communication. Now the control will wait in the application main for the data interrupts.

 

CONNECT / DISCONNECT

If required, the MUSB can be configured to allow its connection to the USB bus to be controlled by software When the Soft Connect/Disconnect option is selected, then when the MUSB is operating in Peripheral Mode, the UTMI+-compliant PHY used alongside the MUSB can be switched between normal mode and non-driving mode by setting/clearing bit 6 of the Power register (which is identified as the Soft Conn bit). When this Soft Conn bit is set to 1, the PHY is placed in its normal mode and the D+/D- lines of the USB bus are enabled. At the same time, the MUSB is placed in ‘Powered’ state, in which it will not respond to any USB signaling except a USB reset.When this feature is enabled and the Soft Conn bit is zero, the PHY is put into non-driving mode, D+ and D- are tri-stated and the MUSB appears to other devices on the USB bus as if it has been disconnected.

After a hardware reset (NRST = 0), Soft Conn is cleared to 0. The MUSB will therefore appear disconnected until the software has set Soft Conn to 1. The application software can then choose when to set the PHY into its normal mode. Systems with a lengthy initialization procedure may use this to ensure that initialization is complete and the system is ready to perform enumeration before connecting to the USB. Once the Soft Conn bit has been set to 1, the software can also simulate a disconnect by clearing this bit to 0.

 

USB Tick module

The USB tick module contains the functions related to USB stack tick timer handling. It has functions to initialize the variables used in processing timer ticks, function handles registering OTG, Host, or Device SOF timer handler functions. This module is implemented in file usbtick.c

 

CDC Application Data Flow

 

Data out Flow (From Host to Device)

When there are data from host, the device will receive an interrupt from the host. The interrupt handler is going to do the following steps on reception.

• Read the interrupt status register
• Identify the interrupt
• Call the appropriate handler (Read Data handler)
• Read handler will check if the RX Packet Ready bit is set.
• Check the number of byte available in the buffer.
• Read the data to buffer
• Clear the RX Packet Ready bit
• Give the read data to the application

 

Count Register

RxCount is a 13-bit read-only register that holds the number of received data bytes in the packet currently in line to be read from the Rx FIFO. If the packet was transmitted as multiple bulk packets, the number given will be for the combined packet. The value returned changes as the FIFO is unloaded and is only valid while RxPktRdy

 

Data in Flow (From Device to Host)

When the device side application needs to send data to the host, the device hast to follow the below steps.

• Application should call the Write data API and pass the data buffer to the CDC layer
• Write Data API checks the amount of data to be send
• Copy the data the TX buffer
• Set the TX Packet Ready bit
• On completion of transmit, Host will send TX completion Interrupt
• TX Packet Ready bit will be cleared automatically
• Up on reception of the TX Complete Interrupt, the ISR will sent an event to the application which indicating the completion of data transfer.

 

How to write a new CDC Application

The CDC application should take the following steps in order to add the CDC transmit and receive capability.

• Define the 6 entry string descriptor table which is used to describe various features of your new device to the host system.
• Define a tCDCSerInstance structure which the USB CDC serial device class driver uses to store its internal state information. This should never be accessed by the application. tCDCSerInstance g_sSerialInstance;
• Define a tUSBDCDCDevice structure and initialize all fields as required for your application.
• Add a receive event handler function to your application taking care to handle all messages which require a particular response. For the CDC device class, USB_EVENT_RX_AVAILABLE and USB_EVENT_DATA_REMAINING MUST be handled by the receive event handler.
• Add a transmit event handler function to your application taking care to handle all messages which require a particular response. For the CDC device class, there are no events sent to the transmit callback which MUST be handled but applications will usually want to note SB_EVENT_TX_COMPLETE since this is an interlock message indicating that the previous packet sent has been acknowledged by the host and a new packet can now be sent.
• Add a control event handler function to your application and ensure that you handle USBD_CDC_EVENT_GET_LINE_CODING, returning a valid line coding configuration even if your device is not actually driving a UART. Handle the other control events as required for your application.
• From your main initialization function call the CDC device class driver initialization function to configure the USB controller and place the device on the bus. pDevice = USBDCDCInit(0, &g_sCDCDevice);
• Assuming pDevice returned is not NULL, device is now ready to communicate with a USB host
• Once the host connects, your control event handler will be sent USB_EVENT_CONNECTED and the first packet of data may be sent to the host with following packets transmitted as soon as USB_EVENT_TX_COMPLETE is received via the transmit event handler.

 

Power Configuration

The power configuration for the CDC class device is held in two of the tUSBDCDCDevice members variables, usMaxPowermA and ucPwrAttributes. The usMaxPowermA variable holds the maximum power consumption for the device and is expressed in milliamps. The power configuration is held in the ucPwrAttributes member variable and indicates whether the device is self or bus powered. Valid values are USB_CONF_ATTR_SELF_PWR or USB_CONF_ATTR_BUS_PWR.

 

How to execute

• As this is the device (USB peripheral) mode of operation the target(EVM) has to be connected to HOST (e.g. Windows PC).
• The CDC device requires an INF file at the host side in order to enable as virtual COM port. Please use the INF provided with package.
• The INF file is required only with a windows based host.
• If the user is planning to use different VID and PID, then INF file needs to be updated with the new VID and PID.
• Once the device is connected to the host, the host will ask for INF file. User needs to point to the location where the INF file is stored.

• The INF file is available at SitaraWare\tools\usb_inf
• Once the proper INF file is pointed out by the user, then virtual COM port will appear in the device manager

• Now open an hyper terminal and Chose the virtual comport

• Set the parameters

• Open another hyper terminal and chose COM1 for UART
• Now user can start typing in one hyper terminal which will appear in the other hyper terminal

• Modules used in this example
  • USB
  • Interrupt

 

HID Device Class design

Please note that in the current EVM we have only touchscreen hardware as the pointer device. But we use HIDMouse term interchangeably all through the text to be generic enough.

The USB Human Interface Class device class is architecture for supporting a wide variety of input/output devices regardless of whether or not they actually deal with "Human Interfaces". Although typically thought of in the context of keyboards, mice and joysticks, the specification can cover practically any device offering user controls or data gathering capabilities. Communication between the HID device and host is via a collection of "report" structures which are defined by the device in HID report descriptors which the host can query. Reports are defined both for communication of device input to the host and for output and feature selection from the host.

In addition to the flexibility offered by the basic architecture, HID devices also benefit from excellent operating system support for the class, meaning that no driver writing is necessary and, in the case of standard devices such as keyboards and joysticks, the device can connect to and operate with the host system without any new host software having to be written. Even in the case of a nonstandard or vendor-specific HID device, the operating system support makes writing the host-side software very much more straightforward than developing the device using a vendor-specific class.

Despite these advantages, there is one downside to using HID. The interface is limited in the amount of data that can be transferred so is not suitable for use by devices which expect to use a high percentage of the USB bus bandwidth. Devices are limited to a maximum of 64KB of data per second for each report they support. Multiple reports can be used if necessary but high bandwidth devices may be better implemented using a class which supports bulk rather than interrupt endpoints (such as CDC or the generic bulk device class).

This device class uses one or, optionally, two endpoints in addition to endpoint zero. One interrupt IN endpoint carries HID input reports from the device to the host. Output and Feature reports from the host to the device are typically carried via endpoint zero but devices which expect high host-to-device data rates can select to offer an independent interrupt OUT endpoint to carry these. Endpoint zero carries standard USB requests and also HID-specific descriptor requests. This layer is implemented in files Usbdhid.c and Usbdhidmouse.c

 

HID Device class example application

HID device enumeration

The Application main has to do the following steps

• Configure the system interrupts
• Register the Interrupt handlers
• Initialize the buffers
• Call the USBDHIDMouseInit with the device instance structure as a parameter.

With this call, the control is given to the HID mouse layer.

• Initialize the various fields in our instance structure.
• Initialize the HID device class instance structure based on input from
  the caller.
• Initialize the lower layer HID driver by calling USBDHIDInit.

With this call, the control is given to the HID device class layer.

The device class layer has to do the following steps

• Assign the endpoints to the device instance structure
• Assign the configuration descriptor to the device instance structure.
• Call the USBDCDInit and pass the device instance structure to the core.

With this call the control is passed to the core layer.

The core layer has to do the following steps in order to complete the enumeration

• Enable the PSC clock
• Rest the USB module
• Switch on the phy
• Initialize the USB tick module
• Clear all the pending interrupts
• Enable the required interrupts
• Set the configuration parameters
• Disconnect the device
• And connect the device

Now the device will start receiving interrupts from the Host. The interrupt handler in the core layer will identify all the Ep0 interrupts and call the appropriate handler. By this way once if all the standard requests are serviced by the device then the enumeration is complete and the device is ready for communication. Now the control will wait in the application main for the touch screen inputs.

 

HID Track pad (Pointer device) application Flow

The above figure shows how the mouse application works. The application shall be always polling for a touch event. Once a touch event is detected, read the x and y values. A touch event can be identified by reading the pressure on the touch screen. Before passing the x and y values to the touch handler, read the pressure again to confirm that there is a real touch event occurred.

In touch handler check if this is a button press or not. This shall be identified by comparing the x and y coordinates. If the x and y coordinates belongs to the button area, then update the button status.

If this is not a button presses then read the x and y values multiple times. This will help to avoid the re bouncing effect and also to confirm the touch event. After this using the current and previous x and y values calculate how much we moved from the last point and send the values to the host through HID report.

 

In Data Flow (Device to Host)

 

How to write a new HID Application

To add a USB HID mouse interface to your application using the HID Mouse Device Class API, take the following steps.

• Add the following header files to the source file(s) which are to support USB:
  • 1. include "src/usb.h"
    2. include "usblib/usblib.h"
    3. include "usblib/device/usbdhidmouse.h"
• Define the string table which is used to describe various features of your new device to the host system. This table must include a minimum of 6 entries - string descriptor 0 defining the language(s) available and 5 strings for each supported language.
• Define an area of RAM of for the private data for the HID mouse class driver. This structure should never be accessed by the application. static tHIDMouseInstance g_sMouseInstance;
• Define a tUSBDHIDMouseDevice structure and initialize all fields as required for your application.
• Add a mouse event handler function to your application. A minimal implementation can ignore all events though USB_EVENT_TX_COMPLETE can be used to ensure that mouse messages are not sent when a previous report is still in transit to the host. Attempts to send a new mouse report when the previous report has not yet been acknowledged will result in return code MOUSE_ERR_TX_ERROR from USBDHIDMouseStateChange().
• From your main initialization function call the HID mouse device API initialization function to configure the USB controller and place the device on the bus. pDevice = USBDHIDMouseInit(0, &g_sMouseDevice);
• Assuming pDevice returned is not NULL, your mouse device is now ready to communicate with a USB host
• Once the host connects, your mouse event handler will be sent USB_EVENT_CONNECTED after which calls can be made to USBDHIDMouseStateChange()to inform the host of mouse position and button state changes.

 

How to execute

• As this is the device (USB peripheral) mode of operation the target(EVM) has to be connected to HOST (e.g. Windows PC).
• Once the device is connected to the host, the device will enumerate as HID mouse.
• User can check the device manager of the host to confirm the completion of the enumeration.
• Touch screen will be initialized and buttons will we displayed
• Now user can use the touch screen to move the cursor and press the mouse button
• Modules used in this example
  • USB HID
  • Graphic Lib
  • Touch Screen
  • Interrupt

Mass Storage class Design

The USB mass storage device class allows an application to act as a physical storage device for use by another USB application or for a host operating system. Because the type of storage can vary per application, the mass storage class abstracts the storage with a set of block based APIs that are provided by the application to the USB library. These APIs allow the USB mass storage class to call an external set of functions that actually perform the operations on the physical storage media. The storage APIs are given to the USB library’s mass storage device class initialization function and are called by the USB library whenever it needs to access the physical media.

 

 

 Initialization and Data Flow

The USB library’s mass storage class provides a simple interface to initialize the mass storage classand pass it the needed functions to access a device without having any knowledge of the physicalmedia. The USBDMSCInit() function is the only initialization required by the mass storage class and it uses the structure tUSBDMSCDevice to hold all customizable values for the mass storage class.

The USB library’s mass storage class provides the ability to customize how the device is reported to the USB host controller in the tUSBDMSCDevice structure. The members of this structure containall of the customizable parameters.

The below pictures shows how the data and command flow is happening in MSC device.The diagram is drown without considering the DMA .

 Block  Media Access 

The media access functions are passed in to the USB mass storage device class in the sMedia- Functions member variable. This structure holds the access functions for the media used by this instance of the mass storage class device. All of the functions in this structure are required to be filled out with valid functions. These function will be called by the USB mass storage device class whenever it needs to read or write the physical media and will assume fixed block sizes of 512 bytes for the media.

In some cases the application may need to be informed when the state of the mass storage device has changed. The pfnEventCallback member of the  MSCDevice structure provides event notification to applications for the following events: USBD_MSC_EVENT_IDLE, USBD_MSC_EVENT_READING, and USBD_MSC_WRITING. When the function of type tUSBCallback is called, only the first two parameters pvCBData and ulEvent parameters are valid. The pvCBData is the value that was returned when the application called USBDMSCInit() and can be used with other APIs.These events are not used in the application provided with package, application writer can make use of these events as required

RAM Disk Support

The MSC is provided with a RAM disk implementation as block media. The current size supported by the RAM disk is 16 MB. User can change it by simply changing the RAMDISK_SIZE macro in ramdisk.c file,  depending on the RAM availability.

DMA support

CPPI 4.1 DMA engine is interfaced with MUSB controller and MSC support DMA mode of transaction as a default mode. Currently two DMA modes are supported for RX and TX transactions, that are transparent mode and GRNDIS mode. In current implantation, the GRNDIS mode will not work if the packet size is more than 512 byte. Please note that, to switch to PIO mode, the DMA_MODE macro need to be disabled from the compiler options

Sequence in MSC device Application

• Application calls USBDMSCInit with device instance structure as parameter
•  Application also initializes the DMA, MUSB interrupts, MMU etc.
• The MSC init , which is an API in MSC stack, will populate the device info structure with Endpoint numbers , descriptors, device state etc.
•  MSC init will call DCDInit, with the device instance structure as parameter
•  DCDInit is an API in device core. The core layer has to do the following steps in order to complete the enumeration

1.  Enable the PSC clock
2.  Rest the USB module
3.  Switch on the phy
4.  Initialize the USB tick module
5. Clear all the pending interrupts
6. Enable the required interrupts
7. Set the configuration parameters
8. Disconnect the device
9. And connect the device

• Once the enumeration is complete, the device will appear as mass storage device.
• When the user try to access the MSC first time, the host will format the Disk.
• Once the format is finished, the device is ready for data transaction..
• If any command comes form Host, the device will be notified through an interrupt.
• The interrupt handler in device core (HandleEndpoint)will read the CBW and process it to know the command op code . 
• This Op-code will pass to the command handler and command hanler will call the appropriate command.
• The data transaction will happen through DMA by default.
•  At the end of transaction., The device will send a CSW(command Status Word) to indicate the end of command.

To port this MSC application to use different media than RAM disk

The current package is provided with 16 MB of RAM Disk. If the user wants to use another block media, then following are the steps.

• Rename the usbdmscglue.c and usbdmscglue.h file appropriately
• The block media should have minimum the following APIs

1. Disk_read()
2. Disk_write()
3. Disk_ioctl()

• Repalce these files in the following API of the glue file

1. Disk_Read should be replaced in USBDMSCStorageRead() API
2. Disk_Write should be replaced in USBDMSCStorageWrite() API
3. Disk_ioctl should be replace in USBDMSCStorageNumBlocks() API with appropriate parameters to return the total number of blocks.
   

The default block size is 512 bytes, in case the block media has a different block size, then this hast to updated in the stack . This can be achieved by updating macros DEVICE_BLOCK_SIZE, MAX_TRANSFER_SIZE with the appropriate size.

How to execute

• As this is the device (USB peripheral) mode of operation the target(EVM) has to be connected to HOST (e.g. Windows PC).
• Once the device is connected to the Host, the device will enumerate as MSC device
• The user can check the disk drives to see the mass storage device
• • When the user try to access the MSC first time, the host will format the Disk.
• After formating user can try to do any file transaction operation .
• Currently the device supports 16MB of RAM disk
• Modules used in this example

1. USB MSC application
2. Interrupt module
3. USBLib (including Cppi 4.1 DMA)

Limitations

1. The stack does not provide abstractions for multiple instances of USB hardware.
2. SOF counter approach for timer can’t be used in HIGH Speed mode. Need to see other options for the functionalities where SOF counter/timer is used
3. Concurrent class support of host is not yet analyzed.