Description

Brief Description

This function instantiate the driver buffer (host computer buffer) for a single TE USB FX2 module read connection.

This function has not been included in TE_USB_FX2_GetData() for throughput reasons; if the driver buffer instantiation were repeated at every data reception, the data throughput would be halved.

This function shall be used only one time to instantiate the driver buffer; after instantiation, TE_USB_FX2_GetData() can be used repeatedly without re-instantiating the driver buffer.

Longer Description

This function takes an already initialized USB device list (USBDeviceList previously selected by TE_USB_FX2_Open()) and a not initialized CCyBulkEndPoint double pointer, BulkInEP. This function selects the endpoint to use: you shall choose EP6 (0x86) (endpoints EP4(0x84) or EP2(0x82) are also theoretically possible).

Currently (April 2012), only endpoint 0x86 is actually implemented in Trenz Electronic USB FPGA modules, so that endpoints EP2 and EP4 cannot be read or , more precisely, they are not even connected to the FPGA. That is why attempting to read them causes a function failure after Timeout expires.

Description of internal procedure

TE_USB_FX2_GetData_InstanceDriverBuffer() function instantiates the class used by CyAPI to use bulk endpoint (CCyBulkEndPoint, see pages 9 to 11 of CyAPI.pdf (Cypress CyAPI Programmer's Reference)) and initializes the parameters of this class instantiation. The parameters are :

  1. Timeout
  2. XMODE_DIRECT (this parameter set the driver to single buffering, instead of the slower double buffering)
  3. DeviceDriverBufferSize.

The last parameter force the instantiation of the driver buffer (SW side, on the host computer) for the endpoint 0x86; this buffer has a size in byte given by DeviceDriverBufferSize. This value is of great importance because the data throughput is strongly influenced by this parameter (see Data Transfer Throughput Optimization).

Use of the code

Declaration

TE_USB_FX2_CYAPI int TE_USB_FX2_GetData_InstanceDriverBuffer (CCyUSBDevice *USBDeviceList, CCyBulkEndPoint **BulkInEP, PI_PipeNumber PipeNo,unsigned long Timeout, int BufferSize);

Function Call

Your application program shall call this function like this:

TE_USB_FX2_GetData_InstanceDriverBuffer (USBDeviceList, &BulkInEP, PipeNo, TimeOut, BufferSize);

Parameters

CCyUSBDevice *USBDeviceList

CCyUSBDevice is a type defined in CyAPI.lib. Its name is misleading because it is not a class that represents a single USB device, but it rather represents a list of USB devices. CCyUSBDevice is the list of devices served by the CyUSB.sys driver (or a derivative like TE_USB_FX2_xx.sys). This parameter is passed by pointer. See page 7 and pages 23-49 of CyAPI.pdf (Cypress CyAPI Programmer's Reference).

CCyBulkEndPoint **BulkInEP

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

PI_PipeNumber PipeNo

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

unsigned long Timeout

It is the integer time value in milliseconds assigned to the synchronous method XferData() of data transfer used by CyAPI.lib. Timeout is the time that is allowed to to the function for sending/receiving the data packet passed to the function; this timeout shall be large enough to allow data/command transmission/reception.Otherwise the transmission/reception will fail. See Timeout Setting.

int BufferSize

It is the dimension (in bytes) of the driver buffer (SW) used in data reception of a single endpoints (EP6 0x86 in this case); the total buffer size is the sum of BufferSize of every endpoint used. 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 36 Mbyte/s for read transactions to an actual value of 18 Mbyte/s). See 6 TE_USB_FX2_CyAPI.dll: Data Transfer Throughput Optimization.

Return Value

int : integer type

This function returns true (ST_OK=0) if if the selected BulkEndPoint exists in the firmware (it is able to instantiate the driver buffer). If unable to do so, it returns false (ST_ERROR=1).

enum ST_Status
{
     ST_OK = 0,
     ST_ERROR = 1
};

Code example

int RX_PACKET_LEN = 51200;//102400;
int packetlen = RX_PACKET_LEN;
unsigned int packets = 500;//1200;//1200;
unsigned int DeviceDriverBufferSize = 102400;//409600;//131072;
unsigned long TIMEOUT= 200;
byte * data;
byte * data_temp = NULL;
unsigned int total_cnt = 0;
unsigned int errors = 0;
data = new byte [RX_PACKET_LEN*packets]; //allocate memory
PI_PipeNumber PipeNo = PI_EP6;
//test starts 
SendFPGAcommand(USBDeviceList,FX22MB_REG0_START_TX);
CCyBulkEndPoint *BulkInEP = NULL;
TE_USB_FX2_GetData_InstanceDriverBuffer (USBDeviceList, &BulkInEP, PipeNo, TIMEOUT, DeviceDriverBufferSize);
ElapsedTime.Start(); //StopWatch start
for (unsigned int i = 0; i < packets; i++)
{
	packetlen = TX_PACKET_LEN;
	data_temp = &data[total_cnt];
	if (TE_USB_FX2_GetData(&BulkInEP, data_temp, packetlen))
	{
		cout << "ERROR read" << endl;
		errors++;
		break;
	}
	total_cnt += packetlen;
}
//StopWatch ends
TheElapsedTime = ElapsedTime.Stop(false);
//test stops
SendFPGAcommand(USBDevicelist,FX22MB_REG0_STOP);
  • No labels