APIの説明

通常、EZ-USB FX3のコントロールソフトはCyAPI.dllを使って制御します。

しかし、CyAPI.dllはクラスライブラリなので、古いコンパイラ（Borland C++ Builder 2006など）では使えません。そこで、CyAPI.dllを普通のWindowsのネイティブDLLにラッパするためのDLLを作りました。

また、CyAPIの関数をラッパするだけではなく、特電IPコアを使った高レベルなデータ転送をサポートするための関数が追加されています。

関数の一覧

定義されている関数の一覧を示します。

関数名	機能
TKUSBFX3Open	ライブラリをオープンする
TKUSBFX3Close	ライブラリをクローズする
TKUSBFX3DeviceCount	見つかったFX3デバイスの数を返す
TKUSBFX3WriteToRAM	FX3の内蔵RAMにイメージファイルを書き込む
TKUSBFX3WriteToSPIROM	FX3のSPI ROMにイメージファイルを書き込む
TKUSBFX3BulkOut	FX3に対する低レベルなバルクOUTの発行
TKUSBFX3BulkIn	FX3に対する低レベルなバルクIN転送の発行
USBWriteData	IPコアに対する高レベルな送信(BulkOut)
USBReadData	IPコアに対する高レベルな受信(BulkIn)
USBReset	USBリセット

非常にシンプルですが、これだけでほとんどの処理が実現できます。

関数リファレンス

関数名	TKUSBFX3Open
書式	bool TKUSBFX3Open(int num, unsigned short vid, unsigned short pid, char *DeviceName, int MaxDevnameLength);
機能	ライブラリをオープンする
引数	num 何のパラメータか忘れた。0を指定すればいい vid 見つかったデバイスのベンダIDが格納される pid 見つかったデバイスのプロダクトIDが格納される DeviceName 見つかったデバイスの名前が格納される MaxDevnameLength 名前が格納されるバッファの長さ
戻り値	見つかったらtrueを返す。見つからなかったらfalseを返す
注意点

関数名	TKUSBFX3Close
書式	void TKUSBFX3Close(void);
機能	ライブラリをクローズする
引数	なし
戻り値	なし
注意点

関数名	TKUSBFX3DeviceCount
書式	int TKUSBFX3DeviceCount(void);
機能	見つかったFX3デバイスの数を返す
引数	なし
戻り値	見つかったデバイスの数
注意点

関数名	TKUSBFX3WriteToRAM
書式	bool TKUSBFX3WriteToRAM(const char ImageFileName, char ErrorReason, int ErrorReasonLength);
機能	FX3の内蔵RAMにイメージファイルを書き込む
引数	ImageFileName 書き込むイメージファイル(*.img) ErrorReason エラーの原因が文字列で入るバッファ ErrorReasonLength 文字列バッファの長さ
戻り値	成功したらtrueを返す
注意点

関数名	TKUSBFX3WriteToSPIROM
書式	bool TKUSBFX3WriteToSPIROM(const char ImageFileName, char ErrorReason, int ErrorReasonLength);
機能	FX3のSPI ROMにイメージファイルを書き込む
引数	ImageFileName 書き込むイメージファイル(*.img) ErrorReason エラーの原因が文字列で入るバッファ ErrorReasonLength 文字列バッファの長さ
戻り値	成功したらtrueを返す
注意点

関数名	TKUSBFX3BulkOut
書式	int TKUSBFX3BulkOut(int ep, unsigned char *data, int length);
機能	FX3のAPIを呼び出し、任意のEndPointに任意の長さのデータを転送する
引数	ep エンドポイント番号 data 送信したいデータ length 送信したいデータの長さ(バイト単位)
戻り値	成功したら、送信した長さを返す。 USBデバイスがなければ-1を返す。 EZ-USB Loaderのままであれば-2を返す。データ転送で失敗したら-3を返す。
注意点

関数名	TKUSBFX3BulkIn
書式	int TKUSBFX3BulkIn(int ep, unsigned char *data, int length);
機能	FX3のAPIを呼び出し、任意のEndPointから任意の長さのデータを受信する
引数	ep エンドポイント番号 data 受信したデータが格納されるバッファ length 受信したいデータの長さ(バイト単位)
戻り値	成功したら、送信した長さを返す。 USBデバイスがなければ-1を返す。 EZ-USB Loaderのままであれば-2を返す。データ転送で失敗したら-3を返す。
注意点

関数名	USBWriteData
書式	int USBWriteData(unsigned long addr, unsigned char *data, int len, unsigned short flag);
機能	FPGAの中のIPコアを呼び出し、データを送信する。
引数	addr コアから出力されるaddr信号の値 data 送信したいデータが格納されるバッファ len 送信したいデータの長さ flag コアから出力されるflag信号の値
戻り値	成功したら、送信した長さを返す。失敗したら、0を返す。
注意点

関数名	USBReadData
書式	int USBReadData(unsigned long addr, unsigned char *data, int len, unsigned short flag);
機能	FPGAの中のIPコアを呼び出し、データを受信する。
引数	addr コアから出力されるaddr信号の値 data 受信したいデータが格納されるバッファ len 受信したいデータの長さ(4の倍数に切り上げられる) flag コアから出力されるflag信号の値
戻り値	成功したら、受信した長さを返す。失敗したら、0を返す。
注意点

関数名	USBReset
書式	void USBReset(void);
機能	USBデバイスのリセットと、USBエンドポイントのリセット
引数	なし
戻り値	なし
注意点

プログラムの作り方

デバイスのオープン

デバイスをオープンするには、TKUSBFX3Open関数を呼び出します。

TKUSBFX3Openの使い方の例を次のリストに示します。

    char DeviceName[100];
unsigned short pid,vid;
int status = TKUSBFX3Open(0,&vid,&pid,DeviceName,sizeof(DeviceName));
if(status) {
printf("USB open success. VID=%04x PID=%04x DeviceName=¥"%s¥"¥n"
,vid,pid,DeviceName);
}
else {
printf("USB open failed.");
}
if((vid == 0x2129) && (pid == 0x0520)) {
printf("NP1052(特電FX3ボード)を発見しました¥n");
}

TKUSBFX3Open関数の引数にある、vidとpid、DeviceNameは、見つかったデバイスのベンダIDや名前を格納して返します。

このTKUSBFX3Open関数は、CyAPIが実行されるすべてのデバイスがオープンできます。

もし、1つのPCに複数個のFX3デバイスがつながっている場合、そのどれもがTKUSBFX3Openでオープンできてしまいます。したがって、目的の特電FX3ボードがどうかを判断するため、VIDとPIDを活用してください。

TKUSBFX3Open関数の第一引数は、PCにつながっている何個目のFX3デバイスをオープンするかを指定します。PCに接続されているFX3デバイスの個数を調べるには、TKUSBFX3DeviceCount関数を使います。

イメージファイルの転送

ファームウェアのイメージファイル(*.img)を転送するには、TKUSBFX3WriteToRAMまたはTKUSBFX3WriteToSPIROMを使います。

TKUSBFX3WriteToRAMの使い方の例を次のリストに示します。

char ErrorReason[100];
if(TKUSBFX3WriteToRAM("SlaveFifoNP1052.img",ErrorReason,100)) {
printf("ファームウェアを書き込みました¥n");
Sleep(1000);
}
else {
printf("ファームウェアの転送に失敗しました 理由:%s¥n",ErrorReason);
return false;
}

BulkIN、BulkOut

FX3のエンドポイントにデータを転送するには、TKUSBFX3BulkOutとTKUSBFX3BulkInを使います。

TKUSBFX3BulkOut(2, wbuf, 1024);
TKUSBFX3BulkIn(6, rbuf, 1024);

ただし、これらの関数は低レベルなパケットの送信を行うものなので、特電IPコアでは使いません。

高機能データ送受信

特電IPコアにデータを送受信するには、USBWriteDataとUSBReadDataを使います。

unsigned long addr = 0x10000;
unsigned short flag = 1;
unsigned long len = 0x8000;
USBWriteData(addr,wdata,len,flag);
USBReadData(addr,wdata,len,flag);

これらの関数のaddrに指定した値は、IPコアのaddr_o[31:0]ポートから出力されます。

これらの関数のflagに指定した値は、IPコアのflga_o[15:0]ポートから出力されます。

addrとflagはアプリケーションでに自由に使うことができます。