C# TE_USB_FX2_SetData()

Description

TE_USB_FX2_SetData() reads data from the host computer and writes them to the USB FX2 microcontroller endpoint EP8 (0x08). This data is then passed over to the FPGA.

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

SendFPGAcommand(ref TE_USB_FX2_USBDevice,MB_Commands.FX22MB_REG0_RX, TIMEOUT_MS)

Expected Data Throughput

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

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 (with Buffer.BlockCopy()).

DataRead Size Shall Not Be Too Small

There are two reasons why DataWrite 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 Data Transfer Throughput Optimization.

The second reason is that probably the FPGA imposes your minimum packet size. In a properly used write test mode (using FX22MB_REG0_START_RX and therefore attaching the FPGA), TE_USB_FX2_SetData() is unable to write less than 1024 byte. In a improperly used read test mode (not using FX22MB_REG0_START_RX and therefore detaching the FPGA), TE_USB_FX2_SetData() is able to write 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

Declaration

public static bool TE_USB_FX2_SetData(ref CyUSBDevice TE_USB_FX2_USBDevice, ref byte[] DataWrite, ref int DataWriteLength, int PipeNo, uint Timeout, int BufferSize)

Function Call

Your application program shall call this function like this:

TE_USB_FX2.TE_USB_FX2.TE_USB_FX2_SetData(ref TE_USB_FX2_USBDevice, ref DataWrite, ref DataWriteLength, PI_EP8, Timeout, BufferSize);

Parameters

ref CyUSBDevice TE_USB_FX2_USBDevice

This parameter is passed by reference (ref). It points to the module selected by TE_USB_FX2_Open(). See pages 70-93 of CyUSB.NET.pdf (Cypress CyUSB .NET DLL Programmer's Reference)

ref byte[] DataWrite

This parameter is passed by reference (ref). C# applications use directly TE_USB_FX2_CyUSB.dll based on CyUSB.dll. To avoid copying back and forth large amount of data between these two DLLs, data is passed by reference and not by value.

This parameter points to the byte array that contains the data to be written to buffer EP8 (0x08) of USB FX2 microcontroller. Data contained in EP8 are then read by the FPGA.

ref int DataWriteLength

This parameter is passed by reference (ref). This parameter is the length (in bytes) of the previous byte array; it is the length of the packet read from FX2 USB endpoint EP6 (0x86). Normally it is PacketLength.

int PipeNumber

This parameter is the value that identify the endpoint used for the data transfer. It is called PipeNumber because it identifies the buffer (pipe) used by the USB FX2 microcontroller.

uint Timeout

The unsigned integer value is the time in milliseconds assigned to the synchronous method XferData() of data transfer used by CyUSB.dll.
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. See Timeout Setting.

int BufferSize

The integer value is the dimension (in bytes) of the driver buffer (SW) used in data transmission of a single endpoint (EP8 0x08 in this case); the total buffer size is the sum of all BufferSize of every endpoint used.
The BufferSize has a strong influence on DataThroughput. If BufferSize is too small, DataThroughput can be 1/3-1/2 of the maximum value (from a maximum value of 24 Mbyte/s for write transactions to an actual value of 14 Mbyte/s). If BufferSize has a large value (a roomy buffer), the program shall be able to cope with the non-deterministic behavior of C# without losing packets.

Return Value

bool: logical type

This function returns true if it is able to write data to buffer EP8 within Timeout milliseconds. This function returns false otherwise.

Simplified Sample Code

PACKETLENGTH=100000;
packets=1200;
byte[] data = new byte[packetlen*packets];
byte[] buffer = new byte[packetlen];
for (int i = 0; i < packets; i++)
{
	Buffer.BlockCopy(data, total_cnt, buffer, 0, packetlen);
	TE_USB_FX2_SetData(ref TE_USB_FX2_USBDevice, ref buffer, ref packetlen, PI_EP8, TIMEOUT_MS,BUFFER_SIZE);
	total_cnt += packetlen;
}

Actual Sample Code

SendFPGAcommand(ref TE_USB_FX2_USBDevice, MB_Commands.FX22MB_REG0_START_RX, TIMEOUT_MS);
//ElapsedTime.Start(); //StopWatch starts
Stopwatch stopWatch = new Stopwatch();
stopWatch.Start();
for (int i = 0; i < packets; i++)
{
	packetlen = PACKETLENGTH;
	Buffer.BlockCopy(data, total_cnt, buffer, 0, packetlen);
	if (TE_USB_FX2.TE_USB_FX2.TE_USB_FX2_SetData(ref TE_USB_FX2_USBDevice, ref buffer, ref packetlen, PI_EP8, TIMEOUT_MS, BUFFER_SIZE) == false) errors++;
	else total_cnt += packetlen;
}
//StopWatch stops
stopWatch.Stop();