Demo of Vendor USB for ADSP-SC573 under FreeRTOS

Overview

This example demonstrates the use of the µC/USB Device™ Vendor device class for vendor specific bulk transfers between an embedded application on the ADSP-SC589 EZ-Board and a Windows host PC running a WinUSB based host application. Two use-cases are demonstrated:

• A loopback operation where throughput can be measured, as well as reading and writing memory on the device.
• Access of files on the host PC via the USB extension to the STDIO service.

See Using the Vendor Bulk Example for further details on the operation of these use cases.  

Hardware Requirements and Setup

The requirements of the USB software are as follows:

•     ADSP-SC589 EZ-Board and appropriate emulator ICE.
•     Windows 7, 8.1 (32 or 64 bit)
•     PC with available USB port.

We recommend using a host PC with a built-in USB 2.0 controller, otherwise performance will be greatly reduced. Even USB 2.0 plug-in controllers will show a decrease in performance compared to systems with built-in USB 2.0 controllers.

Also note that using other USB devices simultaneously may slow down the performance of the example. Shutting down CCES after loading the firmware will allow the device to operate as fast as possible.

No particular switch settings are required on the EZ-Board to run the USB application. 

Using the Arm USB 2.0 Connection

1. Be sure you have read the Hardware Requirements and Setup section above and have followed its instructions.
2. Connect to your target board with CrossCore® Embedded Studio (CCES). If you need help configuring CCES, refer to the CCES documentation.
3. Configure, build and launch the example application (VendorDemoSC589).
4. For optimal throughput when connected to the same PC as your emulator, you may wish to run the example without connection to the emulator. To do this select the "Target->Settings->Target Options" menu option and change the "On Emulator Exit" option to "Run from current PC". Then exit from the emulator by right-clicking on the application in the Debug window and select "Terminate", "Terminate and remove" or "Terminate/Disconnect all". Closing CCES will also have the same effect.
5. Otherwise, start executing the Arm application from CCES in the usual way.
6. Connect the standard A end of your USB cable to the host PC and the micro-B end of your USB cable to the EZ-Board USB OTG micro-B (USB0) or the USB HS micro-B USB1 connector. You can switch between these two ports while application is running, if required. However, support for connection to both the USB0 and USB1 ports at the same time is restricted as mentioned in the Section 5.4.
7. For first use, and after changing the USB port, Windows' will locate and install the driver. This can take some time; this is usual. For XP and Vista, please respond affirmatively to all prompts and allow it to search and install automatically.
8. Once the driver installation is finished you can check the Windows Device Manger to make sure you see a new "ADI Vendor Specific USB Device" is listed under "ADI Development Tools".
9. Your EZ-Board is now ready to communicate with a host, and you can execute the Windows' applications described in Section 5 below as appropriate.

Note: if you want to shut down CCES after loading the firmware, ensure that you have performed step 4 beforehand, otherwise CCES will stall the processor on exit and USB communication will not be functional.

Using the Vendor Bulk Example

The same host application C:\Analog Devices\CrossCore Embedded Studio 2.9.0\Blackfin\Examples\demo\hostapp\hostapp.exe is used for both use cases; It must be run from a Windows command line. Use the -h switch for a list of available options. In addition to headline functions, support is provided for other simple commands such as dumping memory, filling memory, getting firmware version, etc.

Note: setting breakpoints in the firmware may cause the host utility to timeout, depending on the method used by the host to open a connection with the device. The loopback example uses asynchronous I/O and is capable of timing out while the redirect_IO example uses synchronous I/O and will not time out. If you execute an asynchronous Read() or Write() from the host and hit a breakpoint on the device before completing the transaction, you will timeout. Be sure not to place breakpoints in code that performs the read or write and you it not timeout.

General Operation

The hostapp and the Vendor bulk device application maintains the following protocol of host initiated transfers:

1. Command Phase - a 12 byte command block is sent down with a command, the data size, and an optional 4-byte value.
2.     Data Phase - this phase will either be an IN (device to host) or OUT (host to device) transfer or a combination of both.

For each command given, the hostapp:

1. Transmits a command block to query support.
2. Receives a command block conforming support.
3. Transmits a command block with the details of the action.
4. Performs the action required by the command.

Loopback Operation

The loopback function involves data being send from the host to the device and back again. The host verifies that the data is correct and performs some throughput calculations which it displays to the user. The loopback program flow is as follows:

Running hostapp -l displays a continuously updated screen such as the following:

The header information should be self-explanatory, but note that the "Transfer size" will either be constant with -l or -c options and variable with -r option.

The bottom table gives the throughput figures (in Mbytes per second, 1MB = 1024*1024 bytes) in both directions and is detailed as follows:

File I/O and STDIO Operation

The File I/O function allows the device to open files on the host and read and write these files. It redirects stdio from the device to the host window for viewing by the user. The redirect_IO example can be used to allow users to get debug (printf) information from the device faster and even without CCES running. The File I/O program flow is as follows:

This example demonstrates File operations as well as STDIO operations between SC589 EZ-Board and a Windows host PC.
All messages from device will be shown with < DEVICE > header in the GREEN color. Similarly all messages from host will be shown with < HOST > header in CYAN color.
All errors will be printed in RED color with respective < DEVICE > and < HOST > headers.

To run the demo:

1. Open the command prompt and enter hostapp.exe -u
2. The following message is displayed:
                                         
3. Now control is waiting for an input from user. This input name will go to the device and will be printed back on the host console.
   
4. As seen above, User has given the input name as abcd and number of test lines as 2. After that the device application has opened test.txt and a bulee.jpg files located at C:\Analog Devices\CrossCore Embedded Studio 2.9.0\Blackfin\Examples\demo\hostapp\data on host PC. These files are read by device and then written back to host in the same location with different names (txt2.txt and jpg2.jpg).
5. After device terminated USBIO redirection, you must see "See this back to CCES Console" message in the CCES console. This shows that all STDIO from the device will be printed in the CCES console again.

Details of USBIO redirection usage

This section explains the example files used for USBIO redirection.

VendorDemo.c

This contains main() function which calls the following functions:

• BSP_Init() - Initialize board specific settings
• OsInit(&err) - Initialize the RTOS
• adi_initComponents() - Initialize managed drivers and/or services including USB
• App_TaskCreate() - Creates USBIO_TaskStart
• OSStart(&err) - Starts the RTOS 

app_usbio.c

This defines a USBIO task module "USBIO_TaskStart" which is created by VendorDemo.c:App_TaskCreate()

• This task pends on a semaphore by calling app_bulktest.c:USBIO_WaitForHost()
• It calls following APIs (defined in libucusbd.dlb) to intialize the stdio service and redirection of STDIN, STDOUT, STDERR and file operations to USB.
  • adi_stdio_USBD_InitUsb() - Initializing the STDIO service and USB device as STDIO
  • adi_stdio_USBD_RedirectUsb() - Redirecting all streams to USB 
• After these calls IO operations can be performed over USB.
• The following APIs need to be called after USBIO operation is completed-
  • adi_stdio_USBD_StopUsb() - Inform host that we are done with USBIO
  • adi_stdio_USBD_CloseUsb(): Closing USB as STDIO service and terminating STDIO service 
• Returns back control to app_bulktest.c:App_USBD_BulkTestApp for receiving more commands from host by calling app_bulktest.c:USBIO_ReturnControl(). 

app_bulktest.c

This defines the App_USBD_BulkTestApp task

• This is created inside prebuilt libucusbd.dlb library and waits for command block from host.
• After receiving the command block it responds according to the request of host.
• In demo example, once "hostapp -u" command is received, App_USBD_BulkTestApp task posts the semaphore and wait for signal from app_usbio.c:USBIO_TaskStart task after USBIO operation are done. 

usb_redirect_io.c

This defines PerformIO function for demonstrating the IO operations. 

Connection to both USB OTG (USB0) and USB HS(USB1) ports available on the ADSP-SC589 EZ-Board

ADSP-SC589 EZ-Board comes with an additional USB port i.e. USB HS (USB1) port . This port supports Device mode only. VendorDemoSC589 demo example application allows you to use USB HS (USB1) port in following two ways:

• You can connect the Host PC with USB HS port instead of USB OTG port. Follow Sections 5 to run the Vendor Bulk Example.
• You can use two host PCs to connect to each of the USB ports and follow Sections 5 to run the Vendor Bulk Example. This time you need to run the Host application on both the Host PCs. It will allow you to use both USB ports simultaneously. Only restriction is you can not run STDIO and File IO redirection operations simultaneously. Even if you try, Host PC which starts the "Hostapp -u" operation later will wait until the other Host PC runnning "Hostapp -u" command is done. 

USB HS (USB1) port is not supported for any other USB Device or Host class yet.