Description

TE_USB_FX2_GetData() reads data from the USB FX2 microcontroller endpoint EP6 (0x86) and transfers this data to the host computer. This data is generated by the FPGA.

This function takes an already initialized CCyBulkEndPoint double pointer. The device has been previously selected by TE_USB_FX2_Open().

EP6's buffer is an HW buffer inside USB FX2 microcontroller, not the SW driver's buffer (on host computer) whose size is given by BufferSize parameter.

It is necessary that a FW/HW routine reads USB FX2 microcontroller's EP8 buffer.

If the EP6's buffer is not is not properly written by the FPGA(reference design)/other(custom design) the EP6's buffer will become empty and the host computer will be no longer able to receive further packets. In this case the TE_USB_FX2_GetData() function could experience strange behaviors. For example, a very low throughput (9-10 Mbyte/s even if a 31-38 Mbyte/s are expected) could be measured or the function TE_USB_FX2_GetData() fails returning false.

During USB read transmission test (RX: host computer perspective) the EP6's buffer writing is carried out by MicroBlaze (inside the FPGA); this behavior is setted by MicroBlaze API command FX22MB_REG0_START_TX (TX: USB FX2 microcontroller perspective)

SendFPGAcommand(USBDeviceList,FX22MB_REG0_START_TX);

Expected Data Throughput 

The maximum data throughput expected (with a DataReadLength= 120*10^6) is 38 Mbyte/s (PacketSize = BufferSize = 102400), but in fact this value is variable between 31-38 Mbyte/s (the mean value seems 33.5 Mbyte/s); so if you measure this range of values, the data reception can be considered as normal.

The data throughput is variable in two ways:

  • depends on the used host computer;
  • varies with every function call (computer loading dependent).

DataRead Size Shall Not Be Too Large

TE_USB_FX2_GetData() seems unable to use too large arrays or, more precisely, this fact seems variable by changing host computer. To be safe, do not try to transfer in a single packet very large data (e.g. 120 millions of byte); transfer the same data with many packets instead (1,200 packets * 100,000 byte) and copy the data in a single large data array if necessary.

DataRead Size Shall Not Be Too Small

There are two reasons why DataRead size shall not be too small.

The first reason is that PacketSize has a strong influence on DataThroughput. If PacketSize is too small (e.g. 512 byte), you can have very low DataThroughput (2.2 Mbyte/s) even if you use a large driver buffer (driver buffer size = 131,072 bytes). See section 6 TE_USB_FX2_CyAPI.dll: Data Transfer Throughput Optimization.

The second reason is that probably the FPGA imposes your minimum packet size. In a properly used read test mode (using FX22MB_REG0_START_TX and therefore attaching the FPGA), TE_USB_FX2_GetData() is unable to read less than 1024 byte. In a improperly used read test mode (not using FX22MB_REG0_START_TX and therefore detaching the FPGA), TE_USB_FX2_GetData() is able to read a packet size down to 64 byte. The same CyAPI method XferData() used (under the hood) in TE_USB_FX2_SendCommand() is able to read a packet size of 64 byte. These facts prove that the minimum packet size is imposed by FPGA. To be safe, we recommend to use this function with a size multiple of 1 kbyte.

Use of the code

For a code example see TE_USB_FX2_GetData_InstanceDriverBuffer().

Declaration

TE_USB_FX2_CYAPI int TE_USB_FX2_GetData(CCyBulkEndPoint *BulkInEP, byte DataRead, long DataReadLength);

Function Call

Your application program shall call this function like this:

TE_USB_FX2_GetData(&BulkInEP, DataRead, DataReadLength);

Parameters

CCyBulkEndPoint **BulkInEP

This parameter is used to pass to TE_USB_FX2_GetData() the parameter of BulkEndPoint used. This parameter is a double pointer to CCyBulkEndPoint. The double pointer is used because if single pointer is used the data modification of TE_USB_FX2_GetDataInstanceDriverBuffer() cannot be passed to TE_USB_FX2_GetData().

byte* DataRead

C++ applications use directly TE_USB_FX2_CyAPI.dll based on CyAPI.lib. This parameter is passed by pointer to avoid copying back and forth large amount of data between these two DLLs. This parameter points the byte array that, after the function return, will contain the data read from the buffer EP6 of USB FX2 microcontroller. The data contained in EP6 is generated by the FPGA. If no data is contained in EP6, the byte array is left unchanged.

long DataReadLength

This parameter is the length (in bytes) of the previous parameter.

Return Value

int : integer type

This function returns true (ST_OK = 0) if it is able to receive the data from buffer EP6 within Timeout milliseconds. This function returns false (ST_ERROR = 1) otherwise.

enum ST_Status
{
     ST_OK = 0,
     ST_ERROR = 1
};
  • No labels