Versions Compared

Old Version 4

changes.mady.by.user Sergio Pavesi

Saved on

compared with

New Version 5

changes.mady.by.user Sergio Pavesi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

This document describes two different sets of API:

TE USB FX2 module is able to communicate with host computer's USB using

  • SW C++ API (TE_USB_FX2_CyAPI.dll) and
  • TE USB API

...

  • Commands.

 

Info

In order to provide a user interface for driver functions, dynamic link library "TE_USB_FX2_CyAPI.dll" and "CyAPI.lib" have been used.

C++ applications (running on host computer) 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.

 

API Functions descriptions

Info
All these API functions have some parameters to set: Timeout, BufferSize and others.

The first set of API is a set of DLL functions mainly used to open/close/enumerate the TE USB FX2 module connected through host computer's USB ports; this API uses the Cypress C++ CyAPI.lib as a basis.

The second set of API is a set of DLL functions mainly used to communicate (data transfer using EP6 and EP8) 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

The third set of API is a single API function. TE_USB_FX2_SendCommand() ) is able to communicate with:

  • the EZ-USB FX2 microcontroller endpoint EP1; 
  • the MicroBlaze implemented on the FPGA

...

  • the SPI Flash.

The connection with EP1 command is used to:

  • send command to EZ-USB FX2 microcontroller (for example, reset the FPGA or power on/off the FPGA);
  • interrogate registers;
  • dipatching of API Commands to MicroBlaze and SPI Flash;
  • read/write from MicroBlaze I2C bus address;
  • read/write from SPI Flash.

 

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)

...

Scroll Title
titleExported function list
SetSW C++ API function exported
FirstTE_USB_FX2_ScanCards()

TE_USB_FX2_Open()

TE_USB_FX2_Close()
SecondTE_USB_FX2_GetData_InstanceDriverBuffer()
TE_USB_FX2_GetData()
TE_USB_FX2_SetData_InstanceDriverBuffer()
TE_USB_FX2_SetData()
Third
TE_USB_FX2_SendCommand()

...

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

Synchronous Functions

These All these functions use a synchronous version for the data transfer (Cypress XferData() function). 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.

Info
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 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

Note
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-38 Mbyte/s for read and 25-28 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.

See Data Transfer Throughput Optimization for some insights into this kind of influence.

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.

Note
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)

See section Data Transfer Throughput Optimization for further insights on this influence.

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.

...

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

...