/*******************************************************************
 * DMW_ChannelAPI.h
 *
 *   Channel Middleware main header file
 *
 * Copyright 2004 Digital STREAM Technology, Inc.
 * All Rights Reserved
 *
 * $Id: DMW_ChannelAPI.h, v?? 2004 cafrii Exp $
 *
 ********************************************************************/

#ifndef __DMW_ChannelAPI_H__
#define __DMW_ChannelAPI_H__

#ifdef __cplusplus
extern "C" {
#endif


#include "DMW_Channel.h"
#include "DMW_Status.h"  // 각종 status 상수 값.







//***************************************************************
//
//  Channel Specific Data DB
//
//  041126 add 

// 각 CSD entry를 구분하는 tag 
enum {
	CSD_TAG_END = 0x00,
		// csd list의 맨 마지막을 의미하는 terminator.
		// csd를 list 형태로 사용할 경우 맨 마지막 end를 의미하도록 사용 할 수 있다.
		
	CSD_TAG_SHORT_NAME = 0x10,
		// Channel Short Name, from VCT
		//    format: 16-bit Unicode, Null (0x0000) terminated
		//    ptr: Unicode string of short name, should be null-terminated.
	
	CSD_TAG_EXTENDED_NAME = 0x11,
		// Channel Extended Name, (A.K.A. long channel name) from VCT descriptor
		//    format: MSS
		//    ptr: byte string of extended name
	
	CSD_TAG_EXTENDED_TEXT = 0x12,
		// Channel description, from Channel-Ett
		//    format: MSS
		//    ptr: byte string of extended text
		
	CSD_TAG_SI_SOURCE_NAME = 0x13,
		// Source name, from NTT-SNS (source name subtable)
		//    format: MTS
		//    ptr: byte string of source name
	
	
	// cafrii 041221 add
	CSD_TAG_XDS_CALL_LETTER = 0x14,
		// XDS call letter (Station ID)
		//    format: ASCII (4 or 6 character)
		//    ptr: byte string of call letter
	
	CSD_TAG_XDS_NETWORK_NAME = 0x15,
		// XDS Network Name
		//    format: ASCII (max 32 bytes) with null termination (total max 33 bytes)
		//    ptr: byte string of network name

	CSD_TAG_EXTENDED_NAME_UC = 0x16,
		// Channel Extended Name from VCT descriptor
		// MSS 전체를 다 지정하는 대신 english 만을 따로 추출하여 저장하고자 할 경우 사용한다.
		//    format: Unicode-16, null-terminated
		//    ptr: UC16 string pointer of extended name
	
	CSD_TAG_USER_CHANNEL_NAME = 0x80,
		// User Channel Name, from user input via GUI
		//    format: Ascii
		//    ptr: byte string of user channel name
	
};


typedef struct ChannelSpecificData_t
{
	UINT8 tag;
		// meaning what kinds of data it is..    CSD_TAG_XXX 
		// 'ptr'이 어떤 내용의 데이터인지를 나타낸다.

	UINT16 byte_len;
		// byte length of data pointed by 'ptr'
		// 'ptr' buffer의 크기이다. null terminate 된 경우는 null byte도 포함한다.
	
	UINT8 *ptr;
		// pointer of CSD data..
		// OS_Malloc 에 의해서 할당된 메모리.
		//
	
} ChannelSpecificData;






// cafrii 060630 add

#define DMW_PID_NOT_EXIST 0  // elementary stream not exist..
#define DMW_PID_NO_INFO 1    // we do not have information.

/*
	special pid:
		다음과 같은 경우, 특별한 의미를 부여하고자 할 때 사용.

		- DB의 pid field에 저장할 때 
		
	* 해당 stream이 존재하지 않는 경우는 DMW_PID_NOT_EXIST를 지정한다.

	* PID 정보가 유효하지 않은 경우는 DMW_PID_NO_INFO를 지정한다.
	
		- DB에 저장된 내용이 의미가 없어진 경우 (audio language를 변경한다던가 등)
		- NvRam load한 후..
		- 시간이 많이 경과해서 저장한 pid 정보를 믿을 수 없는 경우 등..

	* 하나라도 DMW_PID_NO_INFO pid가 지정되면
	  Rf Tune을 할 때 pid를 이용한 fast tuning은 불가능하다.

*/






/*******************************************************************************
	Channel Map Definition

	Terminology Definition

	-MCM(Master Channel Map)
	-UCM(User Channel Map)

	DB Generation
		Temp. MCM -> UCM

*******************************************************************************/


/*******************************************************************************
	UCM_DB_T

	기본적인 채널 정보이다.
	모든 채널 관련 API들의 기본이 된다.

	Auto Scan할 경우
		temp M.C.M에 의해 중복성 제거되고, Major/Minor sorting해서 생성된다.

	Channel Add를 할 경우
		minor channel 추가: append --> insert로 변경.
		major channel 추가: append --> insert로 변경. 항상 sort 상태를 유지.
		RF channel 추가: update

	참고: DCM이라고 이름을 변경하는 건은 현재 아직 적용이 안되어 있음.

*******************************************************************************/

// Some restriction:
//   ordered by Major/Minor/Rf/Vf
//   only 1 channel info should be "active" among same Mj/Mn/Rf/Vf group
//
/*
	ShortName과 LongName은 모두 16-bit unicode string이다.
	이 두 string은 (가능하면) null 종료 되어야 한다.
	최대 길이가 7자, 30자 등으로 제한이 되어 있으므로, string 길이가 최대 길이인 경우 
	null 종료가 안될 수 있음에도 유의해야 한다.

	--> 다음 MW design 시에는 null 종료 문자를 포함하여 array를 할당하고 
		string은 반드시 null 종료하도록 하는 것이 바람직함.
*/
typedef struct UserChMap_DB
{
	UINT16  Major;    // Major channel number
	UINT16  Minor;    // Minor channel number
	UINT8   RF;       // RF channel number
	UINT8   VctFlag;  // True if this info come from VCT.

	UINT16  Prog_number;  // prog_number
	UINT8   Service_type; // 0: NTSC, 1: ATSC-VSB, 2: ATSC-64QAM, 3: ATSC-256QAM

	UINT8   Skipped; //	0: retained (active), 1: skipped
	UINT16  SurfIndex; // surf channel index in Surf Channel Map
					// 	0: not included in Surf list
					// 	>=1: included in Surf list and Surf channel index

	UINT16  ShortName[7];  // channel short_name (from VCT)

	INT32   freqOffset;    // signed value, unit: Hz
	UINT16	source_id;     // source_id

	UINT16   Uid;     // UCM element UID. (uniquely distinguishable ID).
	void    *pEpgDB;  // pointer to EPG DB

	// temporary values. 이하 값들은 NvRam에 저장되지 않으므로 휘발성이다.
	//
	UINT16  Pcr_pid;    // pcr pid
	UINT16  Video_pid;  // video pid
	UINT16  Audio_pid;  // preference audio pid
	tDHL_VideoCodingType Video_type;
	tDHL_AudioCodingType Audio_type;
	
	//neverdai add 101018
	tDHL_DispFormat video_format;

	UINT16 pmt_pid; // cafrii 070201 add. if 0, this pid info is invalid.
	
	UINT8	signal_strength;  // strength of signal whose tsid is 'TSID'
	UINT16 	TSID;             // TSID of the channel which contains this PSIP info.
	UINT16 	channel_tsid;     // channel TSID of this descriptive target channel
	BOOL    hidden;           // this channel is hidden in VCT.

	// cafrii 031205 add
	BOOL    blocked;          // if TRUE, this channel is blocked. (application use)
	
	// cafrii 041129 add
	BOOL	scrambled;        // if TRUE, one of streams is scrambled

	// cafrii 060724 add
	BOOL	fresh;
		// 기존에 존재했던 채널인지, 새롭게 추가된 채널인지 
		// 알고 있으면 도움이 되는 경우가 있어서
		// 이를 구분하기 위해 추가함.
		// NvRam에는 저장되지 않는 temporary value

	// cafrii 101208 add
	BOOL	disabled;
		// 이 flag가 true이면 이 채널은 안전한 시점에 채널이 삭제되어야 함을 의미.
		// 바로 삭제하지 않는 이유는 이 채널이 현재 시청 채널일 수도 있기 때문.

	//-------------------------
	// Channel specific data structure
	//
	// cafrii 041125 add for extended channel from VCT.. it is temporary data for MCM only
	//extendedChannelNameDescriptorPtr_t xcnd;
	
	int num_csd; 	// number of csd data
	int max_csd;  // array size of 'csd'

	ChannelSpecificData *csd;
	//-------------------------

	UINT16 LongName[30];  // extended channel name (from VCT)
		// max 30 wide characters (UC16)
		// null terminated or length limited (by 30)

} UCM_DB_T;   // User Channel Map DB

//   NvRam에는 이 모든 정보가 저장되는 것이 아니다.
//


//------------------------------------------
// cafrii 031205, add UCM CORE functions..
//
typedef struct UCM_CORE_ENTRY_t {
	
	// IDs to distinguish each channels..
	UINT16 major;
	UINT16 minor;
	UINT8 rf;
	
	// channel parameters to be persistent between Autoscan..
	BOOLEAN skip;
	BOOLEAN block;
	UINT16 surf;
	
} UCM_CORE_ENTRY;

typedef struct {
	
	int num;                // number of ucm core entries
	UCM_CORE_ENTRY *entry;
	
} UCM_CORE;

UCM_CORE *DMW_CDB_BackupUcmCore(void);
	// Make ucm core from UCM DB.
	// if NULL returned, memory resource is not sufficient to allocate memory..
	// Caller should call FreeUcmCore after use.
		
STATUS DMW_CDB_UpdateUcmCore(UCM_CORE *core);
	// update UCM core so that channel parameters can be unchanged..

void   DMW_CDB_FreeUcmCore(UCM_CORE *core);
	// free ucm core
//------------------------------------------
	

extern char *ShortNameString(UINT16 *src, char *dst);
	// unicode문자를 ascii char로.. (영문만..)

extern const int g_sizeUcmExtension;
	// user가 원하는 만큼 UCM은 확장될 수 있다.
	// ChannelLib을 초기화 할 때 지정가능하다.
	//
#define UcmItemMemorySize() (sizeof(UCM_DB_T) + g_sizeUcmExtension)
	// 실제로 UCM 하나가 메모리에서 차지하고 있는 바이트 크기.

#define UcmExt(p) ((p)+sizeof(UCM_DB_T))
	//
	// UCM Extension 부분을 접근하기 위한 매크로.
	// 이 포인터를 다시 application별로 준비된 (UCM_EXT *)로 캐스팅 해서 사용하면 된다.
	// 예)
	// typedef struct UCM_EX_t {
	//     UINT32 var1;
	//     UINT8 var2[3];
	// } UCM_EX;
	//
	// #define XUCM(p) ((UCM_EX *)UcmExt(p))  // to reach ucm extension use this.
	//
	// DMW_CDB_InitializeChannelLib(ChannelType_Air, sizeof(UCM_EX));
	//
	// XUCM(&g_UCM[i])->var1 = 10;
	//


//
//***************************************************************
//
//  4.4 API
//

//***************************************************************
//
//  4.4.1-1  Tuning 관련 기본사항.
//
//
//


STATUS	DMW_CDB_InitializeChannelLib(ChannelType type, int sizeExtionsion);
	//
	// 채널 타입을 바꾼다.
	//  - 현재 ucm이 새 채널 타입과 맞지 않을 경우 ucm을 폐기한다.
	//  - ucm sema4가 없으면 새로 만든다.
	//    ucm을 NvRam에서 자동으로 load하지는 않는다. 그것은 application의 몫이다.

STATUS  DMW_CDB_TerminateChannelLib(void);
	// 채널 라이브러리를 닫는다.
	// 각종 태스크, 세마포어를 해제한다.
	//
	



//------------------------------
// UCM DB pointer

extern UCM_DB_T *g_UCM;          // DB pointer
extern INT32    g_UCM_number;   // number of DB element stored in RAM, not NvRam!!!
extern INT32    g_UCM_max;      // max number of DB (unit: element)
	//
	// UCM DB는 1차원 배열 구조를 갖는다.
	// UCM DB를 위한 메모리의 할당/재할당은 M/W에서 담당한다.
	//
	// Application에서는 DB 내용 수정을 하면 안된다. 오직 API를 이용하여야 한다.
	//   application에서 원한다면 DB를 직접 읽어서 참조하는것은 가능하지만,
	//   그럴경우 sema4로 보호된 상태에서 읽어야 한다. Lock/Unlock()함수 이용.
	//
	// Application에서는 Read-Only로 간주한다. M/W에 의해서만 수정된다.
	//
	// UCM DB는 원칙적으로 AutoScan에 의해 MCM으로부터 생성되므로 그 순간 크기가 결정되지만,
	//   Update 관련 API에 의해 추가 확장될 수 있다. DWM_TUN_xxx()..
	//
	// 참고:
	//  Application에서 DB의 내용을 직접 수정하는 방법은 아직 없으나,
	//  향후 'Skipped' flag와 같이 application 정책에 많이 의존적인 일부 필드를 수정하는 함수가
	//  제공되기 전까지 수정을 임시방편으로 허용하고 있다. 이 경우 반드시 Lock으로 보호하기 바람.
	//

extern BOOL g_bReserveUcmIndex0;
	// 이 값은 index 0을 특별한 용도로 사용하길 원하는 platform을 위한 flag이다.
	// TRUE이면 UCM index 0 (g_UCM[0])은 특수 용도로 reserve된다.

void DMW_MSC_LockUcm(void);
void DMW_MSC_UnlockUcm(void);

STATUS DMW_MSC_LockUcmWait(UINT32 tick);
	// cafrii 060804 add
	// Ucm mutex를 lock하기 위해서 무한정 기다리지 않고 지정된 시간만 기다린다.
	// dead lock을 방지하기 위해서 간단하게 체크를 할 때 유용.



// 각종 채널 서핑 함수들..
// 기존 채널 튜닝 정책에서 제공되던 함수이임.

STATUS DMW_MSC_FindUcmByRF(int rf, int *returnIndex); // cafrii 050528 add

#if 0  // cafrii 051031 delete, do not use any more

STATUS DMW_MSC_FindUpperUcm(int curMajor, int curMinor, int *returnIndex, int *returnRF);
STATUS DMW_MSC_FindLowerUcm(int curMajor, int curMinor, int *returnIndex, int *returnRF);

STATUS DMW_MSC_FindUpperMajor(int curMajor, int flag, int *returnIndex, int *returnRF);
STATUS DMW_MSC_FindLowerMajor(int curMajor, int flag, int *returnIndex, int *returnRF);

#endif // 0


// UCM 오류를 체크하는 디버그 함수. 테스트 용도임.
//
BOOL DMW_MSC_IsUcmValid(void);


STATUS DMW_MSC_EnableChannel(int uid, BOOL bEnable);
	// Skipped flag 설정하는 함수.


void DMW_MSC_SortUcm(void);
	// UCM을 다시 정렬하는 함수.


void DMW_CDB_PrintUcm(int detailLevel); // 메모리에 있는 UCM을 리스트한다.
void DMW_CDB_PrintOneUcm(int i, int detailLevel);

//------------------------------------------
// 새로운 Tuning Policy에 의한 채널 서핑 함수.
//
//


// 새 Tuning Policy 요구사항을 적용한 코드.

// UCM 채널 정보의 Uid (Unique ID)
//
// 새 Tuning Policy에는 Uid라는 새 id값을 사용한다.
// 더이상 Major/Minor/RF 데이터 쌍이 unique 함을 보장할 수 없고,
// UCM의 index 값은 UCM lock을 할 경우에만 의미가 있으므로 새로운 ID가 필요하게 된 것.
//
// Uid는 16bit unsigned 값으로서 채널 정보가 메모리에 존재하는 동안은 그 정보를 유일하게
// 구별할 수 있도록 부여된 값이다.
// NvRam에는 저장되지 않는 휘발성 값이다. NvRam에서 load될 경우에는 새롭게 ID가 할당된다.
//
// 현재 구현 정보:
//    현재 구현은 1부터 시작하는 일련 번호이며, 중간에 UCM 데이터 일부를 삭제할 경우 빈 번호가
//    존재하기도 한다.
//    UINT16의 최대값인 65535를 넘어가면 wrap-around되지만 '0'의 값은 사용하지 않고 있다.
//

int DMW_MSC_Uid2Index(int uid);
int DMW_MSC_Index2Uid(int index);
	//
	// index <--> Uid간의 변환에 사용한다. 두 데이터는 UCM안에서 1:1로 매칭이 되어 있다.
	// 해당 채널이 없으면 -1을 리턴한다.
	//
	// 주의1:
	// Uid의 타입은 원래 UINT16이나, -1과 같은 에러를 알려주기 위해 리턴값 'int'가 사용되었다.
	//
	// 주의2:
	// index를 함수인자나 리턴값으로 사용하는 모든 함수는 caller에서 Ucm을 lock을 걸어 보호해 줄 필요가 있다.
	// 이 두 함수도 예외가 아님.


int DMW_MSC_GetMaxMinorNumber(int major);
	//
	// 해당 'major' 값을 메이저 번호로 갖는 채널 정보들 중에서 최대 minor값을 찾는다.
	// 이는 PSI로부터 추출된 채널 정보에 Major-Minor 스타일의 채널 번호 명명을 하기 위해
	// application에서 사용할 수 있다.
	//
	// 예를 들어 현재 major 9를 갖는 채널 정보들 중, minor 값의 최대값이 3이라고 하면
	// applicaiton에서는 PMT에서 알아낸 채널 정보 두개를 9-4, 9-5로 명명할 수 있을 것이다.
	//
	// PSI 채널 정보의 명명법은 application의 자유이므로 위의 예는 강제사항이 아니다.
	//



//--------------------------------
//  채널 up/down 함수들.
//

//   format of CSF_Xxx
//
//                    5  4  3  2  1  0
//    +-------------+--+--+--+--+-----+
//    |          Res      |IS|PF|  MF |
//    +-------------+--+--+--+--+-----+
//
//    MF: modulation filter
//        00 : all
//        01 : ATSC only
//        10 : NTSC only
//
//    PF: PSI filter
//        0 : do not include channel info from PSI table
//        1 : all info including PSI
//
//    IS: Ignore Surf Order
//        1 : ignore surf index value.
//

#define CSF_Default         0

#define CSF_Mask_MF         3
#define CSF_ATSC_Only       1  // search only ATSC channel.
#define CSF_NTSC_Only       2  // search only NTSC channel.

#define CSF_Include_PSI     4  // include PSI channel as well as PSIP channel.

#define CSF_IgnoreSurfOrder 8  // do not count on surf index number. just use zero/non-zero info.
                               // used in SurfUp/Down() API only.

#define CSF_Include_Skipped 0x10  // include skipped (disabled) channel also.

#define CSF_Include_Hidden  0x20
	// cafrii 050602 add
#define CSF_DontWrapAround  0x40  // do not wrap around if not found..
	// cafrii 050602 add

#define CSF_Include_Disabled 0x80 // include disabled channel. by default, they are skipped.


int DMW_MSC_FindChannelMajorMinor(int major, int minor, int flag, int szBuf, int *uidBuf);
int DMW_MSC_FindChannelMajor(int major, int flag, int szBuf, int *uidBuf);
	//
	// 해당 major[또는 minor]에 대응하는(같은 값을 갖는) 채널 정보를 리턴한다.
	// 함수의 리턴값은 일치하는 채널 정보의 갯수.
	// bIncludePsi는 PSI로부터 얻은 채널 정보도 같이
	// 일치하는 모든 채널 정보를 받을려면 인자로 uid 저장 버퍼를 넘겨주면 된다.
	// 버퍼 크기는 'szBuf'이며, 이 이상 데이터가 많을 경우 truncate된다.
	//  리턴 값 > szBuf 이면 truncate 된 경우이므로 다시 호출해서 정확한 정보를 알아내야 할 것이다.


int DMW_MSC_FindMajorUp(int uidCurrentOrMajor, int flag, int szBuf, int *uidBuf);
int DMW_MSC_FindMajorDown(int uidCurrentOrMajor, int flag, int szBuf, int *uidBuf);

int DMW_MSC_FindMinorUp(int uidCurrentOrMajorMinor, int flag, int szBuf, int *uidBuf);
int DMW_MSC_FindMinorDown(int uidCurrentOrMajorMinor, int flag, int szBuf, int *uidBuf);
	//
	// uidStart를 기준으로 upper/lower channel 정보를 찾는다.
	//  (uidStart 자체는 포함하지 않는다. 그냥 시작점일 뿐임)
	//
	// 리턴되는 결과 역시 uid (또는 uid의 버퍼)이다.
	// Major의 경우 하나가 아니므로 복수개의 uid가 검색된다.
	// 리턴값으로 검색된 uid의 갯수를 넘겨준다.


int DMW_MSC_FindRfUp(UINT16 rfCurrent, int flag, int szBuf, int *uidBuf);
int DMW_MSC_FindRfDown(UINT16 rfCurrent, int flag, int szBuf, int *uidBuf);
	//
	// rfCurrent를 기준으로 upper/lower RF "채널들"을 찾는다.
	// rfCurrent보다 크거나 작은 채널을 찾는다.
	// 리턴되는 결과 역시 uid (또는 uid의 버퍼)이다.
	// 리턴값으로 검색된 uid의 갯수를 넘겨준다.


//-----------------------------
// surf 채널 관련.. 3/21 추가
//
// surf 채널이란 UCM의 SurfIndex가 non-zero 값을 가지는 채널로서
// 이 채널들은 surf channel list에 등록이 되어 있는 채널이다.
// surf-up, surf-down 명령으로 surf 채널 서핑을 할 수 있다.
//
// surf 채널의 등록 및 해제는
// DMW_CDB_SetSurfChannel()/DMW_CDB_ReleaseSurfChannel() 함수를 이용한다.
//

int DMW_MSC_FindUidFromSurfIndex(int surfIndex); // return uid.
	//
	// 원하는 surf_index를 가진 active 채널을 찾아서 그 Uid를 되돌려준다.
	//


int    DMW_MSC_Surf2Index(int surf); // surf --> index.  require caller's UCM lock.
UINT16 DMW_MSC_FindSurfIndexFromUid(int uid);  // don't require caller's umc lock.

UINT16 DMW_MSC_FindMaxSurfIndex(int *returnUcmIndex); // return value: surfIndex
UINT16 DMW_MSC_FindMinSurfIndex(int *returnUcmIndex); // return value: surfIndex
	//
	// 많은 경우에 있어서 min surf index는 아마도 1일 것이다.
	// surf 채널이 하나도 발견되지 않으면 0을 리턴한다.


int DMW_MSC_FindSurfUp(int uidCurrent, int flag);  // return uid.
int DMW_MSC_FindSurfDown(int uidCurrent, int flag);  // return uid.
	//
	// uidCurrent 다음부터 찾기 시작하여 가장 가까운 upper/lower surf 채널을 찾는다.
	// flag는 CSF_IgnoreSurfOrder 만 사용 가능하다.
	// 현재 uidCurrent가 invalid이거나, uidCurrent의 채널이  surf list에 있는 채널이
	// 아니라면 동작은 아래 경우에 따라 나눠진다.
	//  - CSF_IgnoreSurfOrder set 인 경우:
	//       find lowest index channel which is in surf list. (아마도 surfIndex == 1)
	//  - 디폴트 세팅인 경우:
	//       uidCurrent의 채널로부터 가장 근처에 있는 (minor 기준으로 nearest)
	//       채널을 되돌려준다.
	// 모든 경우에 inactive channel은 검색하지 않는다.






//***************************************************************
//
//  4.4.1-2  Tuning 관련 APIs
//
//

typedef DMC_FN_TUNE_COMPLETED ChannelTuneCallback;

//
// 모든 Tuning 작업은 궁극적으로 Dmc_Task에서 이루어진다.
// 별도의 전담 태스크로 구성함으로써 리소스 사용의 충돌을 방지할 수 있다. (tuner설정 등)
//

STATUS DMW_TUN_TuneChannelByUid(UINT16 uid, BOOL bSkipPrescanPids,
		BOOL bWaitForCompletion, ChannelTuneCallback fn, UINT32 userparam);
	//
	// UID를 받아서 튜닝을 한다.
	// 모든 다른 형태의 요구 (RF, Major-Minor, Up/Down 등..)는 Uid의 형태로 변경되어
	// 이 함수의 인자를 통해 전달된다.
	// 필요한 경우 M/W의 다른 helper 함수를 사용할 수 있다.
	//
	// bWaitForCompletion이 TRUE일 경우 Tuning이 완전히 끝날때까지 block된다.
	// FALSE이면 Dmc_Task로 command messge를 전달만 하고 바로 리턴된다.
	//

STATUS DMW_TUN_TuneChannelByUidAndFlag(UINT16 uid, UINT32 flag,
		BOOL bWaitCompletion, ChannelTuneCallback fn, UINT32 userparam);
	//
	// cafrii 041202 add
	// more specific UidTune API
	

// 채널 튜닝의 Smartness에 관하여:
//
// UCM에는 pre-scanned pids, Major-Minor, RF 등의 많은 정보들이 있는데
// 튜닝을 하는 절차는 아래와 같다.
//
// 1. pre-scan pid 정보의 video_pid 또는 audio_pid가 non-zero이면 이 값을 이용하여 시청.
//
// 2. 1)의 방법이 실패할 경우에는 pre-scan pid가 잘못 수집되었거나 out-of-date인 경우이다.
//    이때는 그 채널 정보의 형태에 따라 대응이 달라진다.
//
// 2-A. VCT로부터 얻어진 채널 정보라면, VCT를 분석하여 Major-Minor 번호로 시청을 한다.
// 2-B. PSI로부터 얻어진 채널 정보라면, PMT의 Program number로 시청을 한다.
//
//      채널 정보 내용에 따라 위의 두 방법중 한가지 방법만이 시도된다.
//      실패 할 경우 더 이상의 처리는 하지 않는다.
//


// Dmc_Task에서 발생한 에러 값을 Application에서 알려고 할 경우에는 두가지 방법을 사용할 수 있다.
//
//  1) API의 리턴값.
//     blocking call에서만 가능하며, DMW_TUN_Xxx() 함수의 리턴값(STATUS)을 이용하여 제한적인
//     정보를 얻을 수 있다.
//  2) Application callback
//     미리 등록한 callback 함수를 이용하여 여러가지 정보를 알려줄 수 있다. (todo..)
//  3) Polled watch
//     마지막으로 call한 함수가 성공적으로 수행되었는지 application에서 주기적으로 체크한다. (todo..)
//





//***************************************************************
//
//  4.4.2 Auto channel search API
//
//


typedef BOOL (*ChannelScanCancelCheckFn)();



// cafrii 061219 add
typedef enum
{
	// 일반적인 경우에는 analog/digital 총합해서 한번에 진행된다.
	ScanOnePassStage,

	// Analog Separate scan flag를 지정하면 아래 두가지 Stage로 진행된다.
	ScanAnalogStage,
	ScanDigitalStage,

} ScanStage;

#define ScanStageString(s) ( \
	(s)==ScanAnalogStage ? "Analog" : \
	(s)==ScanDigitalStage ? "Digital" : "All" )



// structure
//  


typedef struct
{
	int flag;   // CBTF_XXX

	ScanStage stage;
	
}  ScanStartedCbParam;

typedef struct
{
	BOOL bStoppedByUser;
	BOOL bUpdate;

		// param1: bStoppedByUser, TRUE이면 StopScan() 명령에 의해 중단된 경우임.
		// param2: bUpdate,
		//            TRUE이면 StopScan(bUpdate==TRUE, ..)로 호출되었음.
		//            bStoppedByUser가 TRUE일때만 의미가 있음.

	int flag;   // CBTF_XXX

	ScanStage stage;
	
}  ScanCompleteCbParam;

typedef struct 
{
	// input parameter;
	//
	int  channel;          // current RF channel number to check
	//ModulationType demod;  // modulation
	
	UINT32 flag;        // scan flag:  CBTF_XXX
	
	ChannelScanCancelCheckFn chkfn;    // cancel check function
		// application code should repeatedly check cancel calling this function.
		// if this function returns TRUE (meaning autoscan is cancelled),
		// then application should exit scan immediately 
		// with 'return_value' to 'statusCancelled' 

	BOOL one_channel_scan;  // true if this scan is quick scan (one channel scan)
	
	// output parameter;
	//
	BOOL locked;          // TRUE if signal locked.
	ModulationType mode;  // detected modulation type. valid if 'locked' is TRUE
	int strength;         // signal strength 
	int  freq_offset;     // frequency offset detected in Hz unit
	STATUS return_value;
	
	
}  ScanTunerSetCbParam;



typedef struct
{
	int current_rf;
	BOOL after_scan;  // TRUE if this 'rf' is completed.
	
	int channel_idx;  // 몇번째 channel인가?
	int total_channel;

	ScanStage stage;
	
	//
	// 진행 상황 정도
	// (channel_idx+1) * 100 / total_channel
	
} ScanProgressCbParam;

// Note! 
//   이 event는 'rf' 시작하기 직전에 한번 (after_scan = 0),
//   종료하고 나서 한번 (after_scan = 1), 이렇게 두번 불린다.


typedef struct
{
	UCM_DB_T *ucm;

	BOOL (*fn_lookup_mj_mn)(int major, int minor);
	BOOL (*fn_lookup_rf_pn)(int rf, int program_number);
	// ...

} ScanNewChannelCbParam;


typedef struct
{
	STATUS status;
	
	int rf;
	UINT32 flag;
	
	//UINT32 userparam; // cafrii 060804 no more used
	
	int nUid;
	int *uidBuf;  // 이 buffer는 event callback 직후에 free될 것이므로 주의.
	
} OneChannelScanCompleteParam;

//
//  Callback 함수의 인자로 전달될 이벤트 타입과 동반되는 parameter 정의.
//
typedef enum 
{
	evtScanStarted,
		// 채널 검색 작업이 시작되었음.
		// param1: ScanStartedCbParam *
		// param2: NULL

	evtScanComplete,
		// 채널 검색이 모두 끝났음. 
		// UCM 생성 작업도 모두 완료 되었기 때문에 이후 application에서
		// UCM 데이터를 사용할 수 있다.
		// param1: ScanCompleteCbParam *
		
	evtScanTunerSet,
		// param1: ScanTunerSetCbParam *

	evtNewChannel,
		// 새로운 채널이 발견되었음.
		// param1: ScanNewChannelCbParam *

	evtOnProgress,
		// 채널 검색 진척 상황. 상태 진행 그래프를 표시하기 위해서 사용한다.
		// param1: ScanProgressCbParam *

	//evtError,
		// 에러가 발생하였음.
		// param1: 에러 정보.. 에러 종류를 설명하는 스트링.
		//   ex)  "out of memory for MCM. some channel info will be dropped"
	
	//evtOneChannelComplete,  // cafrii 060804 delete
		// scan one channel 함수를 사용할 때에만 전달되는 이벤트.
		// param: OneChannelScanCompleteParam*
	

} ChannelScanEventType;


typedef STATUS (*ChannelScanCallback)
			(ChannelScanEventType evt, UINT32 param);
	// 콜백 함수의 prototype.



typedef struct SparseChannelMap_t
{
	int num_seg;
	
	struct   // describe channel from 'rf_start' to 'rf_start' + 'rf_num' - 1
	{
		int ch_start;
		int ch_num;
		
	} seg[10];
	
} ChannelScanSparseMap;




//-----------------------------------------------------------------------
// Channel Broadcast Type Flag definition.
// this flag is used as an argument of StartScan function.


#define CBTF_ChannelTypeMask 0x0001

#define CBTF_Air             0x0000
#define CBTF_Cable           0x0001
	// Only one of above two flag option should be selected.
	//    use of (CBTF_Air | CBTF_QAM) is illegal.
	// NOTE!
	// UpdateMode (DMW_CDB_UpdateDB) 에서는 이 플래그는 사용되지 않는다.
	//

#define CBTF_NTSC      0x0002  // NTSC
#define CBTF_8VSB      0x0004  // ATSC 8VSB
#define CBTF_QAM       0x0008  // ATSC QAM (64, 256 cannot be distinguished.)
	// 검색할 Modulation Mode를 지정한다.
	// 플랫폼에 따라 지원되지 않는 모드가 있겠으나 MW API에서 체크하지는 않는다.

#define CBTF_Ext       0x0010  // extended channel Air: 69 -> 83, Cable: 125 -> 130
	// Start Scan을 하면서 시작/끝 채널 번호를 지정하도록 한 새로운 API를 사용하면
	// 이 flag는 필요하지 않다.
	// 더 이상 지원하지 않는다.

#define CBTF_ForcePSI  0x0020  // force scan using PSI as well as VCT.
	// VCT의 유무와 상관없이 PSI 채널을 검색하여 정보를 모은다.

#define CBTF_IgnoreNtscInVct      0x0040
	// VCT안의 analog 채널 정보를 무시한다.
	// Digital Only Moduel/STB에서는 꼭 세팅해서 call해야 한다.
	// 아니면 Autoscan이 종료된 후에 Analog 채널 정보를 삭제해야 한다.

//#define CBTF_IgnoreRemoteChannelInVct      0x0080
	// VCT안의 remote 채널 정보를 무시한다.
	// DMW_CDB_UpdateDB 에서는 MW API내에서 이 플래그를 자동적으로 세팅한다.
	// 이 API는 현재 시청 채널만 update하는 것이므로 다른 RF 채널의 link 정보는 
	// 참조하면 안되기 때문이다.

#define CBTF_EnableNewChannelInUpdateMode      0x0100
	// UpdateMode (DMW_CDB_UpdateDB)에서만 사용되는 플래그
	// 새로 발견된 채널은 모두 Enable 시킨다. (skipped FALSE)
	// 기존 정보에 overwrite되는 채널은 그대로 둔다.

//#define CBTF_QuerySignalInfo  0x0200
	// JVC 모듈처럼 매 채널/modulation 마다 signal strength 등의 정보를
	// 알고 싶을때 ON.
	// evtSignalInfo 이벤트가 발생된다.
	// cafrii 060616 
	//  이 flag는 더이상 지원하지 않고 있었음. 삭제함.
	
#define CBTF_IgnoreTvctInCable      0x0400
	// 케이블 모드에서 TVCT는 완전히 무시한다.
	
#define CBTF_CheckScrambleByVideoContext 0x0800  // cafrii 041130 change name
	// Video Context 생성 여부로 scramble 여부를 결정한다.
	//
	// scramble 된 채널을 바로 ignore 하는 것이 아니고 일단 DB에 넣되
	// scrambed flag를 set 한다.
	// 이런 채널이 필요 없는 경우라면 autoscan 이 끝난 뒤에 삭제하면 된다.

#define CBTF_IgnorePidsInfo  0x1000
	// PID 값은 수집하지 않는다. Major-Minor 정보만 수집하도록 한다.
	//
	// cafrii 060710, not used any more
	// pid는 사용하지 않더라도, scramble check는 하지 않더라도
	// VCT recover 기법이 항상 사용되므로
	// 이를 위해서 반드시 pid 정보는 필요하다.

//#define CBTF_AnalogCableSystemDetect  0x2000
	//
	// Analog 검색을 수행하면서 CableSystem 을 자동으로 결정한다. (STD/IRC/HRC)
	// 채널 검색이 수행되는 동안은 잠정적으로 STD 모드로 설정이 되어 검색을 하고,
	// 채널 검색이 다 종료되면 검색된 결과를 바탕으로 CableSystem을 결정하게 된다.
	// 이때 HRC나 IRC로 결정이 되면 모든 채널 맵들의 frequency offset도 모두 자동으로 조절된다.
	// 
	// 유의 사항
	//
	// * Cable 모드에서만 사용 가능하다. (CBTF_Cable only)
	// * 아날로그 (NTSC) 만 단독으로 사용해야 한다. (CBTF_NTSC | CBTF_8VSB 이런 식으로 사용 불가)
	// * 반드시 ChannelDB를 모두 clear 한 상태에서 Autoscan을 시작해야 한다. 
	//   기존의 DB data가 남아있은 상태에서 시작할 경우 제대로 동작함을 보장하지 않는다.
	// 

// cafrii 050718 delete, not used any more
//#define CBTF_DigitalCableSystemDetect  0x4000  // cafrii 050603 add
	//
	// Digital 검색을 수행하면서 CableSystem을 결정한다.
	// 채널 검색이 수행되는 동안은 잠정적으로 STD 모드로 설정이 되어 검색을 하고,
	// 채널 검색이 다 종료되면 검색된 결과를 바탕으로 CableSystem을 결정하게 된다.
	// 이때 HRC나 IRC로 결정이 되면 모든 채널 맵들의 frequency offset도 모두 자동으로 조절된다.
	//
	// 유의 사항
	//
	// * Cable 모드에서만 사용 가능하다. (CBTF_Cable only)
	// * Digital만 단독으로 사용해야 한다. (CBTF_NTSC | CBTF_QAM 이런 식으로 사용 불가)
	// * 반드시 ChannelDB를 모두 clear 한 상태에서 Autoscan을 시작해야 한다. 
	//   기존의 DB data가 남아있은 상태에서 시작할 경우 제대로 동작함을 보장하지 않는다.
	// 
	// 이 플래그를 사용하면 CBTF_8VSB 와 CBTF_QAM이 기본으로 설정된 것 처럼 동작한다.
	//


// cafrii 050721 add	
#define CBTF_DontSelectMaxChannel 0x8000
	//
	// Set 되면 Autoscan 완료 후 MCM을 UCM으로 변환할 때
	// 대표 채널 선택을 하지 않는다.
	//

// cafrii 050802 add
//#define CBTF_IgnoreVctWithoutPid  0x10000
	//
	// SLD의 PID 정보가 완벽하지 않은 VCT 테이블은 무시한다.
	//

#define CBTF_PsiOnlyMode 0x10000
	// cafrii 050902
	// 이 flag가 Set 되면 autoscan 할 때에 PSIP 정보를 전혀 사용하지 않고
	// 오로지 PSI 테이블만을 사용한다.
	// Major, Minor 번호는 RF.program_number 값을 사용하게 된다.

// cafrii 060626 add
#define CBTF_SkipTunerSet 0x20000
	//
	// 이 flag가 set 되면 tuner설정은 전혀 하지 않고
	// 현재 tuner 설정된 상태에서 Table 수신 검색만 수행한다.
	// 따라서 이 flag는 tuner가 이미 설정된 후 
	// one channel scan 모드로만 사용이 가능하다.
	//

// cafrii 061219 add
#define CBTF_AnalogSeparateScan 0x40000
	//
	// 이 flag가 set되면 analog scan을 먼저 진행한 후 
	// 나중에 digital scan을 따로 수행 한다.
	// CBTF_NTSC 가 사용되어야 의미가 있다.
	//


#define CBTF_IncludeSpecialHidden 0x80000
	// KBS 향 K-View의 요구사항을 만족시킨다.
	// Hidden 채널 중, 특정 pid를 가지는 채널은 hidden을 푼다.

#define CBTF_IgnoreScrambledChannel 0x100000
	// scramble 걸린 채널들은 아예 채널 DB에 집어넣지 않는다.

//-----------------------------------------------------------------------
	
STATUS DMW_ASC_InitScan(void);
	//
	// 채널 검색 모듈을 초기화 한다.
	//

STATUS DMW_ASC_StartScan(int flag, ChannelScanCallback fn,
							int chStart, int chEnd);

STATUS DMW_ASC_StartScanEx(int flag, ChannelScanCallback fn,
							UINT8 *rfMap, int numRf);

STATUS DMW_ASC_StartSparseScan(int flag, ChannelScanCallback fn, 
							ChannelScanSparseMap *map);

	//
	// 자동 채널 검색을 시작한다.
	// 1) flag : 검색하고자 하는 환경 등 각종 설정...
	// 2) blind == TRUE이면 화면을 보면서 scan한다.
	//     이 모드는 디지털 채널의 경우 속도 문제때문에 거의 현실적이지 못함.
	//     아날로그 채널의 경우는 가능할 것 같음.
	//    blind == FALSE이면 scan 작업 중에는 화면이 blank로 아무것도 보이지 않는다.
	// 3) fn: 콜백 함수 포인터. NULL이 아니어야 함.

	// 이 함수들은 모두 non-blocking 함수이다. 필요한 작업만 수행하고 바로 리턴한다.
	// 실제 scanning 작업은 다른 태스크에서 이루어진다.

	// 이 함수를 사용하기 위한 여러가지 제약사항이 있다.
	//  (아래 Application 사용 예 설명 참조)

	// 검색된 채널 정보는 이벤트를 통해서 application으로 전달된다.
	//    (아래 이벤트전달구조 설명 참조)


STATUS DMW_ASC_StopScan(BOOL bUpdate);  // stop auto scan
	//
	// 검색 작업 도중에 채널 검색 작업을 종료한다.
	//
	// bUpdate가 TRUE이면 이 시점까지 검색된 채널 정보를 이용하여 UCM이 update된다.
	//   지금까지 검색 결과를 완전히 cancel하려면 FALSE 지정.
	//  ChannelScanComplete 이벤트가 전달 되고 난 이후에 불린 StopScan()의 bUpdate는
	//   무시된다. (이미 update가 된 이 후에 이벤트가 전달되므로..)
	//


STATUS DMW_ASC_ScanChannel(int rf, int flag, 
				BOOL bWaitComplete,
				ChannelScanCallback eventcb,
				DMC_FN_COMPLETED pfnComplete, UINT32 userParam,
				BOOL bCancelPrevCmds);


STATUS DMW_ASC_UpdateChannel(int rf, int flag, 
				BOOL bWaitComplete, 
				DMC_FN_COMPLETED pfnComplete, UINT32 userParam,
				BOOL bCancelPrevCmds);

int DMW_ASC_ProgramNumberToMinor(UINT16 program_number);


//------------------------

/*
	참고) 이벤트 전달 구조
		Channel search 도중에, 관련된 event message가 application으로 전달된다.
		Callback 함수를 이용한다.
		callback 함수 포인터는 start scan 할때 인수로 전달한다.

		Application은 이 callback 함수 내에서 필요한 작업을 수행할 수 있다.
			예) eventNewChannel 이벤트가 오면 GUI에 적당한 메시지 표시 또는 Host에 알려줌.

	사용예)
		1) 기존 채널 정보를 모조리 삭제하고 처음부터 검색하는 경우.
			먼저 DMW_CDB_ClearAll()을 호출하여 UCM을 초기화한다.

		2) 기존 채널 정보를 유지한 상태에서 변경사항을 검색하는 경우
			그냥 auto scan을 시작한다.
*/


//***************************************************************
//
// 5.3.1  Update Channel DB
//
//
//
//	이 섹션의 API 함수는 오직 UCM에 대해서만 동작한다. (메모리상에 존재하는 인스턴스)
//
//	NvRam 상의 데이터에는 적용하지 "않는다".
//  -----
//	NvRam의 데이터는 Application에서 명시적인 호출이 있는 경우에만 변경된다. (see 5.3.2)
//


STATUS	DMW_CDB_ClearAll(void);	// initialize channel DB
	// UCM을 다 지운다.
	// NvRam은 지우지 않는다.
	// NvRam의 channel dB를 지우고 싶으면 이 함수 호출 후 DMW_CDB_WriteUCM()을 호출한다.
	// 그러나 UCM과 NvRam의 동기화 정책은 각 product마다 다르므로 알아서 한다.
	// 예: 전원 off 할때만 동기화,  또는 매 1시간마다 동기화 등등..

STATUS DMW_CDB_UpdateChannel(xvctPtr_t vct, MPEG_PAT *pat, MPEG_PMT **pmtlist, 
						int rf, int scan_flag, 
						int *pnUid, int **puidBuf);
	// 주어진 테이블 정보를 이용하여 채널 맵을 구성하고 UCM에 추가한다.
	// 새롭게 추가된 채널의 uid buffer를 리턴하므로, 
	// caller는 후속 처리 작업을 할 수 있다.
	//
	// puidbuf는 DHL_OS_Free를 이용하여 free 되어야 한다.

int DMW_CDB_MakeNewUcm(int major, int minor, int rf, int vf, int st);
	// 주어진 인자를 키값으로 갖는 새로운 Ucm entry를 생성한다.
	// 리턴값은 새로 생성된 Ucm entry의 index이다. 이 값을 사용하려면 이 함수 call 전에
	// UcmLock을 해야 한다.

void *DMW_CDB_RegisterUcmDeleteHook(STATUS (*fn)(int idx));
	// Channel Delete를 수행할 때 호출되는 hook function을 등록한다.
	// Ucm entry가 삭제될때 꼭 수행해야 하는 clean-up 루틴이 있을 경우 등록하면 된다.
	// EPG DB 와 같이 Ucm entry에 system resource가 link된 경우 같이 삭제되도록 하기 위해 사용됨.
	// 리턴값은 previous hook function이므로 이를 기억했다가 
	// hook chain 끝까지 제대로 call될 수 있도록 관리해야 한다.

STATUS DMW_CDB_DeleteUcmChannel(int index);
	// UCM index를 지정하여 해당 ucm entry를 삭제한다.
	// caller측에서 Ucm lock을 해야 한다.

STATUS DMW_CDB_DeleteChanInfoUid(UINT16 uid);
	// 해당 uid 값을 가지는 채널 정보를 삭제한다.

STATUS DMW_CDB_DeleteRFChanInfo(int RF_number);
	// 해당 RF 값을 가지는 모든 채널을 삭제한다.
	// 출처가 VCT/PSI 구분하지 않고 다 삭제한다.

STATUS DMW_CDB_DeleteMajorChanInfo(int major_number);
STATUS DMW_CDB_DeleteMajorMinorChanInfo(int major, int minor);
	// 해당 채널을 삭제한다.
	// 삭제되는 대상은 VctFlag==1인 채널에만 해당한다.
	// 기타 다른 필드는 관계없다. (inactive channel도 삭제)

STATUS DMW_CDB_DeleteAllAnalogChannel(void);
	// UCM에서 analog 채널 정보를 모두 삭제한다.
	// digital only stb에서 유용한 함수.

void DMW_CDB_DeleteDisabledChannel(void);
	// disabled flag set 된 채널만 모두 삭제.

STATUS	DMW_CDB_SetFavChannel(int index);
	// set a channel as active channel
STATUS	DMW_CDB_ReleaseFavChannel(int index);
	// set a channel as inactive channel
	//
	// UCM에 있는 channel list 중에서 일부를 선택하여 Favorite channel list를 만든다.
	// channel Up/Down 키로 채널 변경을 할 수 있는 채널 리스트이다.
	// UCM의 skip field를 이용하여 구분한다. skip이 FALSE이면 FavList에 포함된 것이다.
	//

STATUS DMW_CDB_SetSurfChannel(int index, int prev_index);
	// insert a channel in Surf channel link
STATUS DMW_CDB_ReleaseSurfChannel(int index);
	// delete a channel in Surf channel link
	//
	// Surf channel list (SCM)를 만든다.
	// 함수 인자로 사용되는 index 값들은 모두 UCM index이므로 caller의 lock이 필요한 함수들이다.
	//
	//

void DMW_CDB_InvalidateAllPidInfo(void);
	// cafrii 060630 add
	// prescan pid를 이용한 tuning을 하지 못하도록
	// DB에 있는 모든 pid 정보를 invalidate시킨다.

void DMW_CDB_RegisterChannelUcmSymbols(void);




//***************************************************************
//
//  Channel Specific Data Access API
//
//

const char *CsdTagString(int tag);
void DMW_CDB_PrintCsd(ChannelSpecificData *csd, int num_csd, int indent, int detailLevel);

void DMW_CDB_DeleteUcmCsd(int idx);
		// 해당 index의 UCM entry에 연결된 csd record를 삭제한다.
void DMW_CDB_DeleteAllUcmCsd(void);
		// 모든 csd 를 삭제한다.

STATUS  DMW_CDB_DeleteCsd(ChannelSpecificData *csd, int num_csd);
int     DMW_CDB_DeleteCsdEntry(ChannelSpecificData *csd, int num_csd, int tag);

ChannelSpecificData * DMW_CDB_DuplicateCsd(ChannelSpecificData *csd, int num_csd, int max_csd);

STATUS  DMW_CDB_UpdateCsd(ChannelSpecificData **pdst, int *pdst_num, int *pdst_max, 
                          ChannelSpecificData *src, int src_num);
                          
STATUS DMW_CDB_UpdateCsdEntry(ChannelSpecificData **pdst, int *pdst_num, int *pdst_max,
                              int tag, int len, UINT8 *ptr);
	// 한개의 CSD entry를 update 하는 함수

STATUS DMW_CDB_UpdateUcmCsdEntry(int rf, int source_id, int tag, int length, UINT8 *ptr);
	// DMW_CDB_UpdateCsdEntry 의 다른 parameter 버전


//***************************************************************
//
// 5.3.2  Read/Write Channel DB in NvRam
//
//

// NvRam은 크게 EEPROM (device_0)과 Flash memory (device_1)로 나누어져 있다.
// 제품에 따라서 Flash memory의 NvRam 용도 부분이 존재하지 않을 수도 있다. (eeprom only)
//

//-------------------------------------
// Level 1 API.
// HAL function 바로 위의 API.

//  NvRam Structure
//
//  device 0 (0x0 ~ )
//  +----------------------------+
//  |                            |  사용가능한 영역.
//  |        ...                 |
//  |                            |
//  +----------------------------+ <-- DMW_CDB_GetNvRamAvailableSize(0)
//
//  device 1 (0x80000000 ~ )
//  +----------------------------+
//  |        ...                 |  사용가능한 영역.
//  |                            |
//  +----------------------------+ <-- DMW_CDB_GetNvRamAvailableSize(1)


// device 0: EEPROM
// device 1: Flash
//
// Device 0:  0x0        ~ 0x7FFFFFFF
// Device 1:  0x80000000 ~ 0xFFFFFFFF.  Flash 영역 (device_1)은 address의 MSB가 1.
//

STATUS DMW_CDB_InitNvRam(void);

STATUS DMW_CDB_LowLevelFormatNvRam(void);
	// 공장 출하후 1회 실행해주기만 하면 된다.
	// 프로그램이 업데이트 될 경우 한번 더 포맷해줘야 안전하다.
	//

STATUS DMW_CDB_CheckNvRam(void);
	// NvRam이 제대로 포맷이 되었으며 사용 가능한지 체크한다.


UINT32 DMW_CDB_GetNvRamAvailableSize(int device);
	// 각 장치별 NvRam의 사용가능한 영역의 바이트 크기를 리턴한다.
	//

STATUS DMW_CDB_ReadNvRam(UINT32 address, UINT32 size, UINT8 *buf);
STATUS DMW_CDB_WriteNvRam(UINT32 address, UINT32 size, UINT8 *buf);
	// application에서 호출 가능한 NvRam access API.



//-------------------------------------
// Level 3 API.
//
//   Manages Ucm storing format and Raw DB.
//
//	아래 API는 모두 NvRam에 저장된 UCM정보를 대상으로 한다.

//extern const UINT8 gUcmStoringVersion;
	// see DMW_ChannelDB.c for ucm storing version.

UINT32 DMW_CDB_GetUcmItemStoringSize(void);
	// UCM storing format 구조에서 한 UCM item이 NvRam에 저장될 때 차지하는 크기.
	// sizeof(UCM_DB_T)와는 다를 수 있다.
	// application에서 NvRam에 들어갈 DB 크기 계산을 할 때에는
	// 이 함수의 리턴값을 사용하여야 한다.
	//
	// UCM은 메모리에 있는 상태 그대로 write하지 않는다는 점에 유의한다.



//-------------------------------------
//  Level 4 API
//
//  UCM Header 구조를 지원하는 새로운 UCM I/O API
//  
STATUS DMW_CDB_InitUCM2(UINT32 *paddr, int n_db, BOOL bSyncNow);
STATUS DMW_CDB_WriteUCM2(UINT32 address, int max_db_size, const char *description); // cafrii 041129 change
STATUS DMW_CDB_ReadUCM2(UINT32 address);

STATUS DMW_CDB_WriteRawDB2(UINT32 address, UINT8 *buf, int newsize);
STATUS DMW_CDB_ReadRawDB2(UINT32 address, UINT8 *buf, int newsize);


//  Utility API
//
STATUS DMW_CDB_SyncNvRam(UINT32 address);

UINT32 DMW_CDB_CalcCRC32(UINT32 crc_start, const UINT8 *data, UINT32 len);

BOOL DMW_CDB_IsNvRamSyncWorking(void); // cafrii 060802 add
void   DMW_CDB_WaitForNvRamSyncDone(void);
void   DMW_CDB_InvalidateNvRamCache(void);


//  Debugging API
//
void DMW_CDB_RegisterChannelNvRamSymbols(void);





//-------------------------------------
//
//  CSD DB Access API
//
//  
//
int DMW_CDB_FlattenCsd(ChannelSpecificData *csd, int num_csd, UINT8 *buf, int buf_limit);
	// WriteCSD에서 내부적으로 사용하는 함수


STATUS DMW_CDB_InitCSD(UINT32 *pAddrList, int n_csd_db);
STATUS DMW_CDB_WriteCSD(UINT32 db_start_address, int max_size);
STATUS DMW_CDB_ReadCSD(UINT32 db_start_address, int max_size);
	// 
	// 지정한 NvRam 영역 (시작 주소, 최대 크기) 에 전체 CSD 를 기록하고 읽어들인다.
	// 


/*
	UCM DB 크기 계산 도움말:
		16K : UCM entry 약 500개 분량 (overhead가 있으므로 정확한 숫자는 약간 달라질 수 있음)
		32K : UCM entry 약 1000개 분량
		
	CSD DB 크기 계산 도움말:
		16K : 한 UCM entry 당 최대 CSD 크기를 100 으로 하면, 163개 채널의 CSD를 저장 가능
			Analog 채널의 경우에는 CSD 는 User Channel Name 밖에 없음.
			
			만약 User Channel Name 이 없고 디지털 채널 중 약 절반 정도만 CSD를 가진다고 가정하면
			디지털 채널 약 320개, (아날로그 채널 갯수는 디지털 채널 갯수와 비슷하므로 역시 320개)
			총 640개 분량의 UCM entry 에 해당되는 크기라고 볼수 있음.
			
			POD UCM DB의 경우에는 Extended Channel Text 가 없다.
*/







// 독자적인 형식으로 DB를 관리하기 위해 사용하는 함수.
STATUS DMW_CDB_ReadRawDB(int dir_index, UINT8 *buf, int bufsize);
STATUS DMW_CDB_WriteRawDB(int dir_index, UINT8 *buf, int newsize);



/*
$$$$ 설계문서로부터의 변경사항: from 030117

	1. 모든 API의 마지막 인자로 BOOL air 가 추가됨.
		air == TRUE이면 지상파, FALSE 이면 케이블의 경우이다.
	2. ReadXX 함수의 인자를 모두 pointer 형으로 변경하여 결과를 리턴할 수 있도록 하였다.
		(ReadShortName함수의 인자는 제외함.)
		버퍼 포인터는 NULL이 아니어야 한다. (NULL 체크하지 않음)
	3. 새 API 추가.
		DMW_CDB_GetNvRamAvailableSize(device)
		DMW_CDB_GetUcmItemStoringSize
		DMW_CDB_Read/WriteRawDB
	4. Level1/2/3 API 분리. Level 1 API 추가.
	   UCM storing format이 UCM structure와 다름을 명확히 함.

*/


/*
참고)
	이 개개의 함수들은 사실 특별히 사용할 경우는 없다.
	ReadUCM(), WriteUCM()을 대부분 사용하여 전체 DB를 load/save 하도록 한다.

	그러나 다음과 같은 시나리오가 있을 수 있다.
	중간에 채널 정보가 변경되었다면 메모리에 있는 UCM DB를 수정하고 NvRam에 update를 해야 하는데,
	이 때 전체 내용을 write하려면 시간이 걸릴 경우가 있으므로 필드 단위로 update하는게 필요하다.

	NvRam의 실체(EEPROM 또는 Flash)에 관한 특성은 application에서 알아서 주의하여 코딩해야 한다.
*/




#ifdef __cplusplus
}
#endif


#endif


/********************************************************************
	$Log: DMW_ChannelAPI.h,v $

	2.04  2004/03/15 CBTF_AnalogCableSystemDetect 추가

	2.03	2004/12/21 cafrii XDS 관련 tag 추가
	2.02  2004/12/07 cafrii Cable System Detect 계열 evnet msg 추가
	2.01  2004/12/02 cafrii DMW_TUN_TuneChannelByUidAndFlag 추가

	2.00  2004/11/29  cafrii
		WriteUCM2 에 max_db_size 인자 추가
		CSD 데이터의 NvRam I/O API 추가
		UCM에 scrambled flag 추가
		CBTF_CheckScrambleByVideoContext 플래그 이름 변경 (혼란방지)

	041126 사용하지 않는 값들 모두 삭제.
	       CSD 관련 data structure, API 추가

	041122 MMode_XX 값들 삭제..

	040830 ChannelType/FreqStd, Freq.c 관련 코드 Channel.h로 이동
	
	040611 FindMultiStandardRF 추가
	040607 #include DMW_EEPROM.h 삭제함 (필요한 모듈에서만 선택적으로 include 해야함)

	Revision 1.10  ??
	pEpgDB added
	New channel tuning policy applied.

	Revision 1.03  2003/3/4  cafrii
	DMW_MSC_FindUpper[Lower]Major() 추가.
	DMW_ASC_StopScan()에서 killTask 기능 무시함.

	Revision 1.02  2003/02/17  cafrii
	FineTune type changed.
	some API added.

	Revision 1.01  2003/01/28  cafrii
	NvRam strategy, some prototype is changed.

	Revision 1.0  2003/01/13  cafrii
	Initial coding from ground, based on M/W API document

 ********************************************************************/