/**
	@file
		DHL_COM.h

	@brief
		PHOENIX HAL library

	Communication API interface (UART, I2C, ..)

	Copyright 2006~2010 Digital STREAM Technology, Inc.
	All Rights Reserved
*/


#ifndef __DHL_COM_H__
#define __DHL_COM_H__


#include "DHL_OSAL.h"



#ifdef __cplusplus
extern "C" {
#endif



#if COMMENT
____Overview____(){}
#endif

/**
	@file DHL_COM.h
	
	이곳에 이 모듈에 대해 설명이 필요한 각종 내용 기술..
	
	module overview
		- 
		-

	APIs
	
	implementations
	
	dependencies		
	
	nv parameters
		
	
	
	테이블, 표, 그림 등도 필요하면 ascii code를 이용하여 작성..
	(참고) 제대로 보이려면 맨 왼쪽을 제외하고는 TAB 등의 사용을 하지 않아야 함.

	example)
	fifo queue diagram
	
	    start  rp  wp      end
		+------+---+------+
		|      |XXX|      |        <--- API call
		+------+---+------+
	                 

	@todo
		todo 사항은 코멘트 어느 부분이든지 이 명령어를 활용하자.
*/


#if COMMENT
____Config____(){}
#endif

/*
	이 부분은 별도의 DHL_XXX_Config configuration file 을 
	활용하는 것이 좋을 것 같음.
*/


#if COMMENT
____Types____(){}
#endif

/*
	다른 모듈들과 공유 되는 structure 및 enumerations.
*/


#if COMMENT
____Defines____(){}
#endif


/** @brief UART 내부에서 사용할 수 있는 에러 값들.

	그러나 API는 모두 DHL_RESULT 타입을 사용해야 하므로 
	직접적으로 이들을 사용할 수는 없음.
*/
typedef enum
{
	eDHL_COM_US__OK,
	eDHL_UART_ERROR,
	eDHL_UART_AlreadyOpen,
	eDHL_UART_OpenErr,
	eDHL_UART_WriteErr,
	eDHL_UART_UnknownCmd
	
} tDHL_COM_UartStatus;


/** @brief 데이터 수신 콜백 함수 타입.

*/
typedef void (*tDHL_COM_RX_CB)(UINT8 *pData, UINT32 size);


/** @brief 통신 포트 설정 타입.

	DHL_COM_Config API 에서 어떤 설정을 할 것인지 지정.
*/
typedef enum 
{
	/**	통신 속도 설정. 이 설정을 하기 전까지는 송수신이 제한된다.
		인자: UINT32 baudrate.
			값은 9600, 19200, 115200 과 같이 그냥 숫자를 사용한다.
	*/
	eDHL_COM_CT_Baudrate,

	/** 전송 모드 설정.
		인자: BOOL bAsyncTxMode.
			TRUE를 지정하면 async mode로 전송한다.
	*/
	eDHL_COM_CT_AsyncTxMode,
	
	
} tDHL_COM_ConfigType;


/** @brief 통신용 포트 식별자.

	많은 API들이 이 식별자를 첫번째 인자로 요구한다.
	보통은 하나의 통신 포트만 제공하는데, 그럴 경우 ID는 무시될 수 있다.
*/
typedef UINT32 tDHL_COM_ID;



#if COMMENT
____API____(){}
#endif

/**
	@brief 통신 모듈을 초기화 한다.
	
	주의사항:
		config api를 호출하여 통신 설정이 완료되기 전 까지는 실제 통신 작업은 이루어지지 않는다.
*/
void DHL_COM_Init(void);

/**
	@brief 통신 모듈을 닫는다.
*/
void DHL_COM_Uninit(void);


/**
	@brief Tx 전송이 지금 바로 가능한지 체크한다.

	@param[in] port 사용할 통신용 포트 번호.
	@return 
		TRUE:  busy. 현재는 전송 불가.
		FALSE: not busy. 전송 가능함.
*/
BOOL DHL_COM_IsTxBusy(tDHL_COM_ID port);

/**
	@brief 통신 포트를 통해 데이터를 전송한다.
	
	내부 옵션에 따라 blocking call이 될 수도 있고,
	인터럽트 또는 task에서 전송이 될 수도 있다.

	전송 방식 옵션은 eDHL_COM_CT_AsyncTxMode 를 사용하도록 한다.

	@param[in] port  사용할 통신용 포트 번호.
	@param[in] pData 전송할 데이터 버퍼.
	@param[in] size  전송할 데이터 길이. 바이트 단위.
*/
DHL_RESULT DHL_COM_StartTx(tDHL_COM_ID port, UINT8 *pData, UINT32 size);

/**
	@brief 현재 전송 작업을 중단한다.
	
	Tx 동작이 asynchrounous (non-blocking 방식) 이고,
	현재 전송 중인 패킷이 있다면 전송을 중단한다.
	
	Tx 동작이 synchronous 방식 (blocking call) 이라면 이 함수는 아무 일도 하지 않는다.
	(이 경우 설령 다른 task에서 abort를 시도하더라도 abort는 안됨)

	firmware update 등에서 대량의 큰 패킷을 보내는 중 중단하는 경우,
	이 API가 사용될 수 있다.

	@param[in] port 사용할 통신용 포트 번호.
*/
void DHL_COM_AbortTx(tDHL_COM_ID port);


/*

*/
BOOL DHL_COM_IsRxReady(tDHL_COM_ID port);

/*

*/
void DHL_COM_Receive(tDHL_COM_ID port, UINT8 *pBuf, UINT32 nBufSize, UINT32 *pReadSize);


/**
	@brief 수신 데이터를 전달해 주는 콜백 등록.

	데이터 수신에 관해서는 직접 Read, Receive 등의 API는 제공하지 않는다.
	HAL 내부에서 데이터 수신한 후에 상위 계층에 callback을 올려준다.
	패킷 하나 전체의 데이터가 다 수신된 이후에 callback이 호출된다.

	포트 당 하나의 콜백 만 등록 가능하다. 
	기존에 먼저 등록된 콜백이 있는 경우 기존 콜백 정보는 지워진다.

	@param[in] port     사용할 통신용 포트 번호.
	@param[in] callback 등록할 callback 함수.
*/
void DHL_COM_RegisterRxCallback(tDHL_COM_ID port, tDHL_COM_RX_CB callback);

/**
	@brief 통신 관련 각종 설정.
	
	config api를 호출하여 통신 설정이 완료되기 전 까지는 실제 통신 작업은 이루어지지 않는다.

	@param[in] port  설정을 할 통신 포트. global 한 설정인 경우 이 값은 무시된다.
	@param[in] type  설정 종류.
	@param[in] data  설정 값. 아래에는 타입이 void* 라고 되어 있지만 type 값에 따라 실제 타입은 달라진다.
*/
void DHL_COM_Config(tDHL_COM_ID port, tDHL_COM_ConfigType type, void *data);

/**

*/
void DHL_COM_Status(void);




#ifdef __cplusplus
} /* extern "C" */
#endif



#endif	/* __DHL_COM_H__ */