Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

Introduction

How to write C++ programs using the new Simplified DLL starting from the old DEWESoft DLL.

...

There are some major differences between the two DLLs.

Scroll Title
titleFeatures comparison

feature

Dewesoft C++ DLL

Simplified Trenz Electronic C++ DLL

programming language

C, C++, Python

C, C++, Python

architecture

standard
(TE0300DLL.dll)

Standard (the stacked nature of the solution is hidden)
(TE_USB_FX2_CyAPI.dll requires Cypress CyAPI.lib);

Handles

present

absent

structures

embedded

Embedded (defined in Cypress CyAPI.h but invisible to user)

parameters*

less

more

freedom*

less

more

...

buffer size

...

2 Kbyte (fixed)4 Kbyte or more (it can be changed)
Note

Both

...

the Simplified Trenz Electronic C++ DLL and this porting guide are fully working developer versions but are not supported by Trenz Electronic till the official release, currently not yet planned.

Function Declarations

#define TE_USB_FX2_CYAPI extern "C" __declspec(dllexport) //typedef int (WINAPI *_TE_USB_FX2_ScanCards)();

Exported function (from DLL)

  • TE_USB_FX2_CYAPI int TE_USB_FX2_ScanCards

...

  • (

...

  • );
  • TE_USB_FX2_CYAPI int TE_USB_FX2_Open (int CardNumber, unsigned long TimeOut, int DriverBufferSize);

...

  •  TE_USB_FX2_

...

  • CYAPI int TE_USB_FX2_Close

...

  • (

...

  • );
  • TE_USB_FX2_CYAPI int TE_USB_FX2_SendCommand ( byte* Command, long CmdLength, byte* Reply, long ReplyLength, unsigned long Timeout);

...

  • TE_USB_FX2_

...

  • CYAPI int TE_USB_FX2_GetData ( byte* DataRead, long DataReadLength);

...

  • TE_USB_FX2

...

  • _

...

  • CYAPI int TE_USB_FX2_SetData ( byte* DataWrite, long DataWriteLength);

Internal Function (not exported from DLL)

The two functions that follow appear in the header but are used only internally by the DLL (TE_USB_FX2_CyAPI.dll) and are not exported to the user:

  • int TE_USB_FX2_GetData_InstanceDriverBuffer (CCyUSBDevice *USBDeviceList, CCyBulkEndPoint **BulkInEPx, PI_PipeNumber PipeNo, unsigned long Timeout, int BufferSize);
  • int TE_USB_FX2_SetData_InstanceDriverBuffer (CCyUSBDevice *USBDeviceList, CCyBulkEndPoint **BulkOutEPx, PI_PipeNumber PipeNo, unsigned long Timeout, int BufferSize);

These two functions are called internally by function TE_USB_FX2_Open(). Internal note: With this declaration, TE_USB_FX2_CyAPI.dll has been successfully verified in a Python program (Open_FWUT) using ctypes (used

Note
This Simplified DLL is not thread safe.
Info

This Simplified DLL is successfully used in the Python (using ctypes to import/export c types)

...

program Open_

...

FUT (Gen3) to program USB FX2 microcontroller's firmware and SPI Flash/FPGA's bitstream.

This Simplified DLL is full extern C (C compatible).

Function Translation

Scroll Title
titleFunction translation between DLLs

Dewesoft C++ DLL

Simplified Trenz Electronic C++ DLL

HANDLE m_handle = 0;

Nothing (you must charge the DLL)

cout << endl << TE0300_ScanCards() << endl;

cout << endl << TE_USB_FX2_ScanCards() << endl;

TE0300_Open(&m_handle, 0)

...

!=0

...

TE_USB_FX2_Open(0,

...

TimeOut, DriverBufferSize)!

...

=0
TE0300_Open(&m_handle, 1)

...

!=0

...

TE_USB_FX2_Open(1,

...

TimeOut, DriverBufferSize)!

...

=0

TE0300_Close(&m_handle);

TE_USB_FX2_Close();

TE0300_SendCommand(handle, cmd, cmd_length, reply, &reply_length, timeout)

TE_USB_FX2_SendCommand( cmd, cmd_length, reply, reply_length, timeout)

...

TE0300_SetData(handle, data, packetlen, PI_EP8)
TE_USB_FX2_

...

SetData(data, packetlen)
TE0300_GetData(handle, data, &packetlen, PI_EP6, 1000)TE_USB_FX2_

...

GetData(data, packetlen)
Note
The instantiation of driver buffer happens in TE_USB_FX2_Open(): the user must specify TimeOut and DriverBufferSize.
Info

TimeOut, DriverBufferSize: it is possible to move these parameters to another function like TE_USB_FX2_SetTimeOut and TE_USB_FX2_SetDriverBufferSize or erase them (fix the value inside the DLL).

A future possible extension is

...

to set TimeOut = 1000 (1 ms) and DriverBufferSize = 131,072 if the respective value passed to the function is 0.

...

Dewesoft C++ DLL

...

Simplified Trenz Electronic C++ DLL

...

Scroll Title
titleRead Data example

...

Dewesoft C++ DLL

...

Simplified Trenz Electronic C++ DLL

...

Dewesoft C++ DLL

Simplified Trenz Electronic C++ DLL

void ReadData(unsigned int handle)
{
     int packetlen = RX_PACKET_LEN;
     unsigned int packets = 1200;
     byte * data;

     unsigned int total_cnt = 0;
     unsigned int errors = 0;
     data = new byte [RX_PACKET_LEN*packets];
     //allocate memory
     SetData (data);
     ResetFX2FifoStatus(handle);
     SendFPGAcommand(handle,FX22MB_REG0_START_TX);
     //starts test
     ElapsedTime.Start();
     //StopWatch start
     for (unsigned int i = 0; i < packets; i++)
     {
         packetlen = RX_PACKET_LEN;
   
         if (TE0300_GetData(handle, data+total_cnt,
&packetlen, PI_EP6,TIMEOUT_MS))
         {
             cout << "ERROR" << endl;
             errors++;
             break;
         }
         total_cnt += packetlen;
     }
     //StopWatch timer
     TheElapsedTime = ElapsedTime.Stop(false);
       //

...

stops test
     SendFPGAcommand(handle,FX22MB_REG0_STOP);  

...

    delete data;
}

void ReadData(unsigned int handle)
{

...

     int packetlen = RX_PACKET_LEN;
     unsigned int packets = 1200;
     byte * data;
     byte * data_temp = NULL;
     unsigned int total_cnt = 0;
     unsigned int errors = 0;
     data = new byte [RX_PACKET_LEN*packets];
     //allocate memory
     SetData (data);
     ResetFX2FifoStatus(handle);
     SendFPGAcommand(handle,FX22MB_REG0_START_TX);
     //starts test
     ElapsedTime.Start();
     //StopWatch start
     for (unsigned int i = 0; i < packets; i++)
     {
         packetlen = RX_PACKET_LEN;
         data_temp = &data[total_cnt];

         if (TE_USB_FX2_GetData(data_temp,packetlen))
         {
             cout << "ERROR

...

" << endl;
             errors++;
             break;
         }
         total_cnt +=

...

packetlen

...

;
     }
     //StopWatch timer
     TheElapsedTime = ElapsedTime.Stop(false);
       //

...

stops test
     SendFPGAcommand(handle,FX22MB_REG0_STOP);  

...

    delete data;
}
Scroll Title
titleWrite Data example

Dewesoft C++ DLL

Simplified Trenz Electronic C++ DLL

void WriteData(unsigned int handle)
{
     int packetlen = TX_PACKET_LEN;
     unsigned int packets = 1200;
     byte * data;

     unsigned int total_cnt = 0;
     unsigned int errors = 0;
     data = new byte [TX_PACKET_LEN*packets];
     //allocate memory
     SetData (data);
     ResetFX2FifoStatus(handle);
     SendFPGAcommand(handle,FX22MB_REG0_START_RX);
     //starts test
     ElapsedTime.Start();
     //StopWatch start
     for (unsigned int i = 0; i < packets; i++)
     {
         packetlen = TX_PACKET_LEN;
        
         if (TE0300_

...

SetData(handle, data+total_cnt,
&packetlen, PI_EP8,TIMEOUT_MS))
         {
             cout << "ERROR" << endl;
             errors++;
             break;
         }
         total_cnt += packetlen;
     }
     //StopWatch timer
     TheElapsedTime = ElapsedTime.Stop(false);
       //

...

stops test
     SendFPGAcommand(handle,FX22MB_REG0_STOP);  

...

    delete data;
}

void WriteData(unsigned int handle)
{

...

     int packetlen = TX_PACKET_LEN;
     unsigned int packets = 1200;
     byte * data;
     byte * data_temp = NULL;
     unsigned int total_cnt = 0;
     unsigned int errors = 0;
     data = new byte [TX_PACKET_LEN*packets];
     //allocate memory
     SetData (data);
     ResetFX2FifoStatus(handle);
     SendFPGAcommand(handle,FX22MB_REG0_START_RX);
     //starts test
     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_

...

SetData(data_temp,packetlen))
         {
             cout << "ERROR

...

" << endl;
             errors++;
             break;
         }
         total_cnt +=

...

packetlen

...

;
     }
     //StopWatch timer
     TheElapsedTime = ElapsedTime.Stop(false);
       //

...

stops test
     SendFPGAcommand(handle,FX22MB_REG0_STOP);  

...

    delete data;
}

...

A Note on the Header File TE_USB_FX2_CyAPI.h

Two different header files exist.
One is used for the creation of TE_USB_FX2_CyAPI.dll DLL.
Another header file (with the same name) is exported for the creation of application programs that use TE_USB_FX2_CyAPI.dll DLL.
The latter has some additional lines with regard to the former. This happens to solve some problems with the include files in applications.
The lines of difference are the followings (added to TE_USB_FX2_CyAPI.h used for applications).
#pragma once
//#include <WinDef.h> NO, it fails at 32 bit
#include <windows.h>
#include "CyAPI.h"
typedef unsigned char byte;
Internal note: The file to use is in C:\Project3264bit\TE_USB_FX2_CyAPI\FileToExportForApplication

Procedure for the Creation of a New Project Using Simplified TE_USB_FX2_CyAPI.dll

See document "C++ TE_USB_FX2 API reference manual"
http://www.trenz-electronic.de/download/d0/Trenz_Electronic/d1/TE-USB-Suite/d2/generation_3/d3/APIs.html
section 3.0 "API Functions" ("Exported function list" excluded).

Appendix A : Open the Visual Studio 2010 project

See document "C++ TE_USB_FX2 API reference manual"
http://www.trenz-electronic.de/download/d0/Trenz_Electronic/d1/TE-USB-Suite/d2/generation_3/d3/APIs.html
section 7 "Appendix A : Open the Visual Studio 2010 project".

Appendix B : Use of pdb File (Symbolic Debugging)

See document "C++ TE_USB_FX2 API reference manual"
http://www.trenz-electronic.de/download/d0/Trenz_Electronic/d1/TE-USB-Suite/d2/generation_3/d3/APIs.html
section 8 "Appendix B : use of pdb file (symbolic debugging)".

Document Change History

...

version

...

date

...

author

...

description

...

0.1

...

2012-09-24

...

SP, FDR

...

Release Preview.

...

0.2

...

2013-04-09

...

FDR

...

Updated documentation links.

...

0.3

...

2013-04-12

...

FDR

...