/*	
 *	clipuio.h
 *
 *	USB I/O (バルク転送による、単純なI/O)
 *
 *	CLiP - Common Library for P/ECE
 *	Copyright (C) 2001-2005 Naoyuki Sawa
 *
 *	* Fri Jul 08 06:00:00 JST 2005 Naoyuki Sawa
 *	- 作成開始。
 *	* Sat Jul 09 23:23:00 JST 2005 Naoyuki Sawa
 *	- uio_stat()を追加しました。
 *	* Fri Jul 22 07:40:00 JST 2005 Naoyuki Sawa
 *	- インタラプト転送→バルク転送に変更しました。
 *	  インタラプト転送はバススケジューリングの優先度が高く、他のデバイスの通信が阻害される
 *	  可能性があるので、バススケジューリングの優先度を下げるためにバルク転送に変更しました。
 *	  "念のため"の措置であり、インタラプト転送でも特に問題があったわけではありません。
 *	  バルク転送への変更後も、特に動作に違いは感じられません。
 *	* Mon Aug 22 04:24:00 JST 2005 Naoyuki Sawa
 *	- uio_open(),uio_close()->uio_start(),uio_stop()に名前変更しました。
 */
#ifndef __CLIP_UIO_H__
#define __CLIP_UIO_H__

/****************************************************************************
 *	
 ****************************************************************************/

/* P/ECE UIOデバイスのプロダクトIDを、次のように定義しました。
 * 他のP/ECE USBプログラムと重複しないよう、注意してください!!
 */
#define UIO_PRODUCT_ID	(PCE_PRODUCT_ID+0x15)

/****************************************************************************
 *	
 ****************************************************************************/

/* USB I/Oを開始します。
 * [in]
 *	rxcap		受信バッファサイズ。
 *	txcap		送信バッファサイズ。
 *	rxdone		受信完了コールバック。(NULL:無し)
 *	txdone		送信完了コールバック。(NULL:無し)
 * [note]
 *	* uio_start()を呼び出したアプリケーションは、終了する前に必ず、
 *	  uio_stop()を呼び出してください。
 *	  uio_stop()を呼び出さずに終了すると、P/ECEシステムが異常動作となります。
 *	* 受信(送信)バッファサイズにEP2_NONISO_PACKET_SIZE未満の値を指定した場合、
 *	  受信(送信)バッファサイズはEP2_NONISO_PACKET_SIZEとなります。
 *	* 受信完了コールバックは、USBコントローラの受信完了割り込みに同期します。
 *	  ゼロバイト受信であっても受信完了割り込みは発生するので、
 *	  受信完了コールバック時に、必ずしも受信データがあることが保証されません。
 *	* 送信完了コールバックは、USBコントローラの送信完了割り込みに同期します。
 *	  2005/07/08現在の実装では、次の送信処理を行った後にコールバックするので、
 *	  送信バッファに少なくともEP2_NONISO_PACKET_SIZE以上の空きが保証されます。
 *	  しかし、今後の実装変更により動作が変わる可能性があるので、
 *	  送信完了コールバック時の送信バッファの空きサイズを仮定しないでください。
 *	  ↓2005/07/31追記
 *	- 送信完了割り込み発生時に、送信バッファが空だった場合にのみ、送信完了コールバックを行うよう変更しました。
 *	  これまでは、1パケット送信完了毎(0バイトパケットの送信完了時含む)に送信完了コールバックを行っていました。
 *	- この変更により、送信完了コールバック時、uio_start()で指定した送信バッファサイズ全部の空きが保証されます。
 */
void uio_start(int rxcap, int txcap, void (*rxdone)(), void (*txdone)());

/* USB I/Oを切断します。
 * [note]
 *	* uio_stop()は、常に安全に呼び出すことができます。
 *	  uio_start()を呼び出していなくても、uio_stop()を呼び出しても構いません。
 */
void uio_stop();

/* USB I/Oをリセットします。
 * [note]
 *	* リセットする項目は、次のとおりです。
 *	- 送受信バッファを空にします。
 *	- 受信オーバーランエラーを解除します。
 */
void uio_reset();

/* 受信バッファからデータを取り出します。
 * [in]
 *	dat		取り出したデータを格納するバッファ。
 *	len		取り出すデータの最大バイト数。
 * [out]
 *	戻り値		実際に取り出したデータのバイト数。
 *			受信オーバーランが発生していた場合、マイナス値を返します。
 */
int uio_recv(void* dat, int len);

/* 送信バッファへデータを追加します。
 * [in]
 *	dat		送信するデータ。
 *	len		送信するデータのバイト数。
 *			-1を指定すると、AsciiZ文字列と見なしてデータサイズを自動判断します。
 * [out]
 *	戻り値		実際に送信したデータのバイト数。
 *			送信バッファに充分な空きがない場合は、len未満となります。
 */
int uio_send(const void* dat, int len);

/* 送受信バイト数や、エラー状態を取得します。
 * [in]
 *	stat		結果を格納するUIOSTAT構造体へのポインタ。
 */
typedef struct _UIOSTAT {
	int rxlen;	/* 受信バッファ内にある受信済みデータバイト数(現在) */
	int rxlog;	/* 受信バイト数            (リセット時点からの通算) */
	int rxerr;	/* 受信オーバーランバイト数(リセット時点からの通算) */
	int txlen;	/* 送信バッファ内にある送信待ちデータバイト数(現在) */
	int txlog;	/* 送信バイト数            (リセット時点からの通算) */
} UIOSTAT;
void uio_stat(UIOSTAT* stat);

#endif /*__CLIP_UIO_H__*/
