FX3/FX2LP XferData() API Usage - KBA226200

Author: SrinathS_16      Version: **

 

Question:

What is the significance of the ‘Packet Mode’ parameter in the XferData() API function?

 

Answer:

The KBA discusses the condition in which the device sends data packets in multiples of the MaxPcktSize parameter of the endpoint descriptor.

The XferData() API function is defined in the CyUSB library. The source files of this library are in http://www.cypress.com/documentation/software-and-drivers/ez-usb-fx3-software-development-kit.

This API function is used for synchronous data transfer between the host and devices which are bound to the CyUSB3 driver. To use this API function, refer to the CyUSB.NET guide/Cypress USB Control Center source code. Cypress USB Control Center calls this API when the ‘Transfer Data’ button is pressed.

XferData() returns when one of the following occurs:

  1. The requested number of data bytes has been transferred.
  2. When a short packet or zero-length packet is transferred.
  3. When the timeout (set while calling the function) has occurred.

The XferData() declaration is as follows:

public bool XferData(ref byte[] buf, ref int len, bool PacketMode);

 

During an IN transfer, when the requested bytes of data from the host is not a multiple of the MaxPcktSize parameter of the endpoint in the descriptors, the XferData() function fails with an error code 997 indicating a failed transaction. Under these conditions, the significance of the ‘PacketMode’ parameter is explained as follows:

Consider an FX3 device programmed with the USBBulkSourceSink firmware. This firmware configures an IN endpoint with MaxPcktSize as 1024 bytes. Cypress USB Control Center is used to read data from the device. The PacketMode parameter of the XferData function is set to true when the PktMode check box in Cypress USB Control Center is selected.

Case A:

  1. ‘PktMode’ check box is unchecked.
  2. ‘Bytes to transfer’ box is filled with 16387 bytes (non-multiple of MaxPcktSize)

When the ‘Transfer Data’ button is pressed, the XferData() function keeps waiting until the timeout and then returns with an error code 997 indicating a failed transaction.

Case B:

  1. The ‘PktMode’ check box is checked
  2. ‘Bytes to transfer’ box is filled with 16387 bytes (non-multiple of MaxPcktSize)

When the ‘Transfer Data’ button is clicked, the data transfer request is split into multiple XferData() function  calls, each with a data length equal to the MaxPcktSize parameter of the endpoint. In this case, the data until the previous multiple (i.e., 16384 bytes in this case, 0x4000) of requested data length is received on the host application.

Under both these conditions, the endpoint gets halted and must be cleared using the ResetPipe() function and the pending I/O transactions from the application must be cleared using the AbortPipe()function before performing a new transfer.