/*	
 *	clipacm.h
 *
 *	USB CDC ACM (Communication Device Class Abstract Control Model)
 *
 *	CLiP - Common Library for P/ECE
 *	Copyright (C) 2001-2007 Naoyuki Sawa
 *
 *	* Tue Oct 30 17:22:39 JST 2007 Naoyuki Sawa
 *	- 1st リリース。
 *	- clipuioモジュールを基にして作成しました。
 *	  関数の仕様はclipuioと完全に同じなので、説明を省きました。
 *	  clipuio.hのコメントを参照してください。
 *	* Sat Dec 08 14:51:28 JST 2007 Naoyuki Sawa
 *	- clipusbの仕様変更に追従し、受信オーバーランを回避する実装としました。
 *	  もう、cdcacm_recv()が、受信オーバーランを示すマイナス値の戻り値を返すことは無くなったので、
 *	  アプリケーションが戻り値を見て、必要に応じてcdcacm_reset()を呼び出す処理は不要となりました。
 *		[変更前]
 *			len = cdcacm_recv(dat, sizeof dat);
 *			if(len < 0) {
 *				受信オーバーラン時の処理();
 *				cdcacm_reset();
 *			}
 *			if(len > 0) {
 *				正しく受信できた時の処理();
 *			}
 *		[変更後]
 *			len = cdcacm_recv(dat, sizeof dat);
 *			if(len > 0) {
 *				正しく受信できた時の処理();
 *			}
 *	  受信オーバーランの概念が無くなったので、アプリケーションの処理が大分簡単になったと思います。
 *	- 今回の変更により、基にしたclipuioと関数仕様の一部相違が生じたので、コメントを追記しました。
 */
#ifndef __CLIP_ACM_H__
#define __CLIP_ACM_H__

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

#define CDCACM_PRODUCT_ID	(PCE_PRODUCT_ID+0x17)	/* 重複禁止!! */

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

/* USB CDC ACMを開始します。
 * [in]
 *	rxcap		受信バッファサイズ。
 *	txcap		送信バッファサイズ。
 *	rxdone		受信完了コールバック。(NULL:無し)
 *	txdone		送信完了コールバック。(NULL:無し)
 * [note]
 *	* cdcacm_start()を呼び出したアプリケーションは、終了する前に必ず、
 *	  cdcacm_stop()を呼び出してください。
 *	  cdcacm_stop()を呼び出さずに終了すると、P/ECEシステムが異常動作となります。
 *	* 受信(送信)バッファサイズにEP2_NONISO_PACKET_SIZE未満の値を指定した場合、
 *	  受信(送信)バッファサイズはEP2_NONISO_PACKET_SIZEとなります。
 *	* 受信完了コールバックは、USBコントローラの受信完了割り込みに同期します。
 *	  ゼロバイト受信であっても受信完了割り込みは発生するので、
 *	  受信完了コールバック時に、必ずしも受信データがあることが保証されません。
 *	* 送信完了コールバックは、USBコントローラの送信完了割り込みに同期します。
 *	  送信完了割り込み発生時に、送信バッファが空だった場合にのみ、送信完了コールバックを行います。
 *	  送信完了コールバック時、cdcacm_start()で指定した送信バッファサイズ全部の空きが保証されます。
 */
void cdcacm_start(int rxcap, int txcap, void (*rxdone)(), void (*txdone)());

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

/* USB CDC ACMをリセットします。
 * [note]
 *	* リセットする項目は、次のとおりです。
 *	- 送受信バッファを空にします。
 *	- 通算送受信バイト数をゼロに戻します。
 */
void cdcacm_reset();

/* 受信バッファからデータを取り出します。
 * [in]
 *	_dat		取り出したデータを格納するバッファ。
 *	maxlen		取り出すデータの最大バイト数。
 * [out]
 *	戻り値		実際に取り出したデータのバイト数。
 */
int cdcacm_recv(void* _dat, int maxlen);

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

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

#endif /*__CLIP_ACM_H__*/
