You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This document describes the API supported by standard Trenz Electronic FPGA modules equipped with Cypress EZ-USB FX2 microcontroller (currently: TE0300, TE0320 and TE0630).

This document describes two different sets of API:

  1. TE_USB_FX2_CyAPI.dll
  2. TE USB API commands

C++ applications use directly TE_USB_FX2_CyAPI.dll based on CyAPI.lib. To avoid copying back and forth large amount of data between these two DLLs, data is passed by reference and not by value.

The first set of API is a set of DLL functions mainly used to communicate between the host computer and the EZ-USB FX2 microcontroller endpoints; this API uses the Cypress C++ CyAPI.lib as a basis. In fact, one API function (namely TE_USB_FX2_SendCommand()) is able to communicate with the MicroBlaze implemented on the FPGA.

These API functions have some parameters to set: Timeout, BufferSize and others.

In order to provide a user interface for driver functions, dynamic link library "TE_USB_FX2_CyAPI.dll" and "CyAPI.lib" have been used.
The API for 32 and 64 bit operating systems are located in two different folders:

  • "TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication\TE_USB_FX2_CyAPI_SampleApplication\DLL32"
  • "TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication\TE_USB_FX2_CyAPI_SampleApplication\DLL64"

These folders come from the folder "FileToExportForApplication" in the project folder "TE-USB-Suite\TE_USB_FX2_CyAPI".
"FileToExportForApplication" contains "TE_USB_FX2_CyAPI.h", "CyAPI.h" and two folders; "DLL32" and "DLL64". "DLL32" and "DLL64" folders contain files with the same name but compiled respectively for 32 or 64 bit operating systems.

You shall select 32 or 64 bit for the compilation. To do this you shall:

  1. in "Explore Solution" panel (top right window), right click the second line (between "Solution" and "External Dependencies")
  2. select "Properties"
  3. left click "Configuration Management" (top right)
  4. in "Active Solution Platform", select Win32 or x64
  5. click "Close"
  6. click "OK"

To create a program, you shall copy these files to the project folder.

User programs should load these libraries and initialize module connection to get access to API functions. To do this, you shall:

  1. copy "TE_USB_FX2_CyAPI.h", "TE_USB_FX2_CyAPI.dll", "TE_USB_FX2_CyAPI.lib", "CyAPI.h" and "CyAPI.lib" to the project folder (for example "TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication\TE_USB_FX2_CyAPI_SampleApplication");
  2. open the C++ project (double click the "TE_USB_FX2_CyAPI_SampleApplication" icon in the folder "TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication");
  3. open "Explore Solution" if it is not already open (Ctrl +W or left click "Visualize>Explore Solution");
  4. in the right panel "Explore Solution", right click "Header File";
  5. select "Add". A new window "Add Header File" will opens;
  6. the term "Look In" shall have automatically selected the correct folder ("TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication\TE_USB_FX2_CyAPI_SampleApplication"). If it is not so, you shall select the folder where you have copied the previous DLLs and header files;
  7. left click one of the two header files ("CyAPI.h" or "TE_USB_FX2_CyAPI.h");
  8. select "OK";
  9. repeat steps from 4 to 8 for the second header file;
  10. in the right panel "Explore Solution", right click "Resource File";
  11. select Add. A new window "Add Resource File" will opens;
  12. the term "Look In" shall have automatically selected the correct folder ("TE-USB-Suite\TE_USB_FX2_CyAPI_SampleApplication\TE_USB_FX2_CyAPI_SampleApplication"). If is not so, you shall select the folder where you have copied the previous DLLs and header files;
  13. left click one of the three DLL files ("TE_USB_FX2_CyAPI.dll", "TE_USB_FX2_CyAPI.lib" or "CyAPI.lib");

Note To compile the project it is strictly necessary only "TE_USB_FX2_CyAPI.dll", the two lib files are optional.

  1. select "OK";
  2. repeat steps from 10 to 14 for the second and third DLL file (if you want add the *.lib file also).

API Functions (First API Set)

The first set of API is a set of DLL functions mainly used to communicate between the host computer and the EZ-USB FX2 microcontroller endpoints; this API uses the Cypress C++ CyAPI.lib as a basis. In fact, one API function (namely TE_USB_FX2_SendCommand()) is able to communicate with the MicroBlaze implemented on the FPGA.

These API functions have some parameters to set: Timeout, BufferSize and others.

Synchronous Functions

These functions use a synchronous version for the data transfer (Cypress XferData()). They perform synchronous (i.e. blocking) I/O operations and do not return until the transaction completes or the endpoint TimeOut has elapsed. A synchronous operation (aka blocking operation) is an operation that owns (in an exclusive way) resources and CPU until its job is done. A synchronous function monopolizes resources until its end, even during idle time.

If the program uses the synchronous XferData() function (both in C# with TE_USB_FX2_CyUSB.dll and C++ with TE_USB_FX2_CyAPI.dll), the array of data to transfer is the only one that is subdivided into packets (with packet length ≤ MaxPktSize = 512 byte) and scheduled over the USB buffer for data transmission. Until the data array is completely transferred, no other data array can be scheduled into packets over the USB, even if there is free packet time to be used by other data. The array of data passed to the XferData() function is the only owner of the USB bus until all data of this array are transferred (successfully or unsuccessfully). While using XferData() method, the OS will schedule the next XferData() only after the previous XferData() completes, leading to delay.

XferData() just calls asynchronous functions BeginDataXfer(), WaitForXfer() and FinishDataXfer() in sequence and does error handling accordingly. WaitForXfer() is the one which implements the timeout period for larger transfers. Cypress recommends the following: "You will usually want to use the synchronous XferData method rather than the asynchronous BeginDataXfer / WaitForXfer / FinishDataXfer approach.".

The API uses the synchronous version because it is more suitable to be included in a DLL and it is already fast. With synchronous version, the API functions are simpler to use.

BufferSize (also called XferSize)

BufferSize is the size of the buffer used in data/command transmission/reception of a single endpoint; the total buffer size is the sum of BufferSize of every endpoint used. See section 6 TE_USB_FX2_CyAPI.dll: Data Transfer Throughput Optimization for some insights into this kind of influence
BufferSize has a strong influence on DataThroughput. If BufferSize is too small, the DataThroughput can be 1/3 to 1/2 of the maximum value (36 Mbyte/s for read and 25 Mbyte/s for write transactions). If the BufferSize has a large value (a roomy buffer), the application should be able to cope with the non-deterministic behavior of C# without losing packets.

PacketSize

PacketSize is the size of packets used in data/command transmission/reception of a single endpoint. See section 6 TE_USB_FX2_CyAPI.dll: Data Transfer Throughput Optimization for further insights on this influence.
PacketSize has also a strong influence on DataThroughput. If PacketSize is too small (512 byte for example) you can achieve very low data throughput (2.2 Mbyte/s) even if you use a large BufferSize (driver buffer size = 131,072 byte)

Timeout Setting

Timeout is the time that is allowed to the function for sending/receiving the data packet passed to the function; this timeout shall be large enough to allow the data/command transmission/reception. Otherwise the transmission/reception will fail.

TimeOut shall be set according to the following formula:

TimeOut (ms) = [DataLength / DataThroughput] + 1 ms.

Note: TimeOut is integer so you shall round up the result.

For write transactions, assume DataThroughput ≈ 20 Mbyte/s (it is lower than actual value, give some margin).

For read transactions, assume DataThroughput ≈ 30 Mbyte/s (it is lower than actual value, give some margin).

For SendCommand() assume DataThroughput ≈ 1 Mbyte/s (close to actual value).

These values have been verified for a Core i7 processor at 2.20 GHz with Microsoft Windows 7. Other configuration may require others value. An AMD Athlon II at 1.30 GHz with Microsoft Windows 7 might require much (e.g. two or three times) larger values. If your host computer is not highly responsive, you should set TimeOut to even larger values : e.g 20, 50, 200, 1000 ms (the less responsive the host computer is, the higher the recommended values shall be).

Exported function list

  • TE_USB_FX2_ScanCards()
  • TE_USB_FX2_Open()
  • TE_USB_FX2_Close()
  • TE_USB_FX2_SendCommand()
  • TE_USB_FX2_GetData_InstanceDriverBuffer()
  • TE_USB_FX2_GetData()
  • TE_USB_FX2_SetData_InstanceDriverBuffer()
  • TE_USB_FX2_SetData()

 

  • No labels