/** @file DHL_FE.h @brief FrontEnd (Tuner/Demodulator) functions implementation Copyright 2006~2010 Digital STREAM Technology, Inc. All Rights Reserved Release History: */ #ifndef __DHL_FE_H__ #define __DHL_FE_H__ #include "DHL_Types.h" #include "DHL_Config.h" #ifdef __cplusplus extern "C" { #endif #if COMMENT ____Overview____(){} #endif /** \file DHL_FE.h ----DHL_FE 헤더파일 내용 설명---- ======== 주요 Feature ======== 복수개의 튜너를 지원한다. -> 튜너 ID 지원. 많은 API들이 인자로 Tuner ID를 지정해야 함. 서로 성격이 다른 튜너들을 투명하게 지원. -> 각 튜너 별로 어떤 기능등을 지원하는지 query하는 API 지원. 예: Tuner_0 는 FAT, VSB, NTSC 지원 Tuner_1 은 FAT, VSB, QAM 지원. Tuner_2 는 FDC 지원.. 이 API는 사실 MW에서 필요로 하지는 않으며, Application에서는 특정 platform에 맞게 이미 결정되어 코딩함. Blocking API는 없다. lock 될 때 까지 기다리거나 하는 기능은 상위 계층에서 담당. Hz 주파수 방식으로의 튜닝만을 공식적으로 지원. 채널 번호를 이용한 튜닝은 HAL 에서는 고려하지 않는다. 대신 채널 Table은 제공하도록 하자. 표준화는 할 수 없지만 특정 platform에서 제공하는 각종 기능들 -> Generic Query, Generic Set API를 제공. 나중에 별도로 계속 API가 추가될 필요가 없도록.. ======== API 공통 사항들 ======== Tuner ID를 요구하는 API를 사용할 때, 잘못된 ID를 지정하는 경우에는 DHL_FAIL_INVALID_HANDLE 를 리턴한다. 적절하지 않은 상태에서의 API 호출은 DHL_FAIL_INVALID_STATE 를 리턴한다. 예: Open 하지 않은 상태에서 Start 등.. ======== Naming conventions ======== 데이터 타입 prefix: tDHL_ API 함수 이름 prefix: DHL_FE_ */ #if COMMENT ____Types____(){} #endif /** Tuner ID 0 부터 시작하는 ID 값. 최대 값은 DHL_CFG_NUM_TUNER-1. 대부분의 API에는 이 정보가 첫번째 인자로 전달된다. 참고 - DHL_CFG_NUM_TUNER 값은 API 에서 정의하지 않으며 - DHL_Config.h 같은 global/local config 부분에서 정의한다. */ typedef UINT8 tDHL_TunerID; /** @brief Demodulation 방식 enum. -# DHL_FE_Start 에서 동작 할 demod를 지정할 때 사용되거나, -# DHL_FE_GetModFormat 에서 현재 동작 중인 demod 값을 리턴할 때 사용된다. Start 에 사용 불가능한 항목, 또는 GetModFormat에서 사용 불가능한 항목 등이 기술되어 있으니 참조한다. */ typedef enum { eDHL_DEMOD_INVALID=-1, ///< 잘못된 모드. eDHL_DEMOD_8VSB=1, ///< ATSC 8VSB 모드 eDHL_DEMOD_64QAM, ///< ITU-T J.83 Annex B 64QAM eDHL_DEMOD_256QAM, ///< ITU-T J.83 Annex B 64QAM eDHL_DEMOD_QAM_AUTO, /*!< 64QAM 또는 256QAM 모드. QAM AUTO 값은 request API에서는 사용할 수 있으나 status API 결과로는 사용되면 안된다. */ eDHL_DEMOD_AUTODETECT, /*!< 자동 검색 모드. AUTODETECT 값은 request API에서는 사용할 수 있으나 status API 결과로는 사용되면 안된다. */ eDHL_DEMOD_NTSC=10, /* cafrii 이 부분은 논의가 더 필요하다. BTSC Audio 기능을 DHL_FE 에 어떠한 인터페이스로 추가해야 할지.. */ eDHL_DEMOD_AUDIO_US_BTSC, eDHL_DEMOD_AUDIO_A2_KOREA, eDHL_DEMOD_AUDIO_RADIO_FM, eDHL_DEMOD_FDCA=20, /* SCTE 55-1/DVS 178, OOB Mode A, by Motorola/GI */ eDHL_DEMOD_FDCB, /* SCTE 55-2/DVS 167, OOB Mode B, based on DAVIC, used by SA, CISCO */ eDHL_DEMOD_MAX } tDHL_Demod; /** Spectrum 방식 ?? */ typedef enum { eDHL_OOBSpectrum_Auto, eDHL_OOBSpectrum_NonInverted, eDHL_OOBSpectrum_Inverted } tDHL_OOBSpectrum; /** note: QPSK에서 symbol rate는 bitrate값의 절반이다. OC spec에서는 bitrate 단위로 지정되어 있다. */ typedef enum { eDHL_OOBSymbolRate_0772, /* 1,544 Kbps */ eDHL_OOBSymbolRate_1024, /* 2,048 Kbps */ eDHL_OOBSymbolRate_1544 /* 3,088 Kbps */ } tDHL_OOBSymbolRate; /** DHL_FE_Start() API 에서 사용 되는 OOB 의 셋팅값을 갖는 구조체. SCTE 55-1 or SCTE 55-2 규격에 맞는 값을 대입. */ typedef struct { tDHL_Demod demod; ///< [out] Modulation 값을 가짐. union { /* SCTE 55-1 or SCTE 55-2 OOB tuning param. */ struct { tDHL_OOBSpectrum spectrum; ///< [out] Spectrum 값을 가짐. tDHL_OOBSymbolRate symbol_rate; ///< [out] Symbol_rate 값을 가짐. } scte_55; /* 기타 다른 확장 tuning 방식을 지원하고자 하는 경우 아래에 추가한다. */ } u; } tDHL_DemodExtSettings; /** @brief 신호 상태 타입. DHL_FE_GetSignalStatus 에서 사용. DHL_FE_GetSignalStatus 함수에서 조회 하기를 원하는 정보의 종류를 지정한다. */ typedef enum { /*--------------------------------- 반드시 구현되어야 하는 부분 */ eDHL_SIGNAL_LOCK, ///< digital demod lock eDHL_SIGNAL_NTSC_LOCK, ///< NTSC 캐리어 or VSync lock. eDHL_SIGNAL_STRENGTH, /*!< Signal strength. OSD 상에 signal meter를 표시할 때 사용된다. 반드시 0 ~ 100 사이의 값으로 표시되어야 한다. */ eDHL_SIGNAL_SNR, /*!< Signal to Noise ratio. 원래 snr에 1000배를 한 수치이다. 실제로 OSD상에 이 값을 표시하는 곳은 없으며, 보통 디버그 목적으로 사용된다. */ eDHL_SIGNAL_SER, /*!< Symbol error rate. signal 상태가 좋지 않을 경우 화면을 mute시키는 모니터에서 사용. 최종 TS 출력 단의 에러 카운트 값을 ratio로 표현한 값이다. 에러가 없으면 0이 되고, 에러가 많을 수록 값이 커진다. 어느 정도의 값에서 시청 중단을 할 것인지는 pplication에서 실험적으로 구하는 것이 바람직하다. */ /*--------------------------------- 옵션으로 제공될 수 있는 부분 이 부분은 DHL API 에 있을 이유가 없다. 다른 방법으로 이런 기능을 제공할 수 있는지 체크 요망. */ eDHL_SIGNAL_SNR2, /* 원래 snr에 1000배를 한 수치임 */ eDHL_SIGNAL_SER_1SEC, eDHL_SIGNAL_SER_10SEC, eDHL_SIGNAL_PER, eDHL_SIGNAL_BER, eDHL_SIGNAL_QUALITY, eDHL_SIGNAL_METER, eDHL_SIGNAL_NTSC_FREQ_DEVIATION, /* KHz 단위의 주파수 deviation */ eDHL_SIGNAL_LOCK_PROGRESS /* 3114 direct control api 전용 */ } tDHL_SignalStatus; /** 채널 튜닝 이외에 Tuner 내부 설정값 변경을 위한 설정 type. */ typedef enum { eDHL_FECTL_CAP_VAL, eDHL_FECTL_AIR_CABLE, /* 이름을 더 구체적으로 변경하는 것이 바람직함. */ eDHL_FECTL_ATC_MODE /* CH. Search 모드(채널 Tune)와 Normal 모드(채널 Locked) 일때의 ATC 설정. */ } tDHL_FeControlType; /** GetDeviceInfo의 eDHL_FE_DEV_CAPABILITY_1 의 결과값으로 전달되는 capability에 사용되는 bit mask. 사용 예: if (capbits & eDHL_TUCAP_VSB) printf("this tuner supports vsb\n"); */ typedef enum { eDHL_TUCAP_POWERDOWN = 0x1, /* tuner power down 기능을 지원한다. */ eDHL_TUCAP_ANALOG = 0x2, eDHL_TUCAP_QAM = 0x4, /* eDHL_DEMOD_64QAM, eDHL_DEMOD_256QAM 튜닝을 지원한다. */ eDHL_TUCAP_VSB = 0x8, eDHL_TUCAP_SATELLITE = 0x10, eDHL_TUCAP_OOB = 0x20, eDHL_TUCAP_UPSTREAM = 0x40, eDHL_TUCAP_OFDM = 0x80, eDHL_TUCAP_QAMAUTO = 0x100, /* eDHL_DEMOD_QAMAUTO 튜닝을 지원한다. */ eDHL_TUCAP_CABLEAUTO = 0x200 /* eDHL_DEMOD_CABLEAUTO 튜닝을 지원한다. */ } tDHL_TunerCapBits; /** FE 에서 가져올 디바이스 정보 type. */ typedef enum { eDHL_FE_DEV_VENDOR_NAME, // tuner vendor name // value: const char *name eDHL_FE_DEV_MODEL_NAME, // tuner model name // value: const char *name eDHL_FE_DEV_CAPABILITY_1 // tuner capability // value: UINT32 *pMask } tDHL_TunerDeviceInfo; /** 이 값들은 DHL_FE_ChannelToFrequency 에서만 사용된다. DHL_FE에서의 튜닝은 주파수 값을 이용하므로, 다른 API에서는 이 값들을 사용할 필요가 없음. */ typedef enum { eDHL_FREQ_UNKNOWN=-1, eDHL_FREQ_AIR=0, // 지상파 eDHL_FREQ_STD, // 케이블 기본 eDHL_FREQ_IRC, // 케이블 IRC standard eDHL_FREQ_HRC, // 케이블 HRC standard eDHL_FREQ_MAX } tDHL_FreqStd; #if COMMENT ____Defines____(){} #endif /** 메세지 출력을 위한 각 상태별 String 값 정의. */ #define FE_SIGNAL_STATUS_STR(t) ( \ (t)==eDHL_SIGNAL_LOCK ? "Lock" : \ (t)==eDHL_SIGNAL_NTSC_LOCK ? "NtscLock" : \ (t)==eDHL_SIGNAL_STRENGTH ? "Strength" : \ (t)==eDHL_SIGNAL_SNR ? "Snr" : \ (t)==eDHL_SIGNAL_SER ? "Ser" : \ "?" ) /** 각 튜너의 정보. signal 과 직접적인 관련이 없는 정보들. DHL_FE_GetDeviceInfo 에서 사용된다. */ #define FE_VENDOR_NAME_LEN 32 /* minimum required buffer size, maximum string length */ /** @name 제공할 frequency table 에서 지원하는 channel number 범위 @{ */ #define FE_MIN_FAT_AIR_CH 2 #define FE_MAX_FAT_AIR_CH 69 #define FE_MIN_FAT_CBL_CH 1 #define FE_MAX_FAT_CBL_CH 135 /*@}*/ #if COMMENT ____API____(){} #endif /** @brief 튜너 모듈을 초기화 한다. @return - DHL_OK: 성공. - DHL_FAIL_: 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_Init(void); /** DHL_FE_Open / DHL_FE_Close: 튜너 사용을 준비하거나 (Open), 튜너 사용을 종료한다. (close) 동적으로 전원 제어가 가능한 경우라면 Open 시에 전원이 공급되고, Close 시에 전원이 차단된다. Close 후 다시 Open 하는 경우에는 Tuner가 정상 동작하기까지 시간이 좀 소요될 수도 있다. 예) Demodulator firmware download, AGC level settling. 만약 상시 동작 중인 platform에서는 Open, Close 가 아무 역할을 하지 않을 수도 있다. @param[in] id FE 채널 id. (2개일 경우 0,1 로 부여) @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_Open(tDHL_TunerID id); DHL_RESULT DHL_FE_Close(tDHL_TunerID id); /** @brief FE 의 디바이스의 상태를 가져온다. 디바이스 이름, 벤더, 기능등의 정보. @param[in] id FE 채널 id. @param[in] selector 요청할 정보. @param[out] pValue 디바이스 정보. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_GetDeviceInfo(tDHL_TunerID id, tDHL_TunerDeviceInfo selector, void *pValue); /** @brief 주어진 주파수, demod로 front end Tune 동작 실행. Setting 값은 OOB tune 을 위한 파라미터. In-band 튜닝시 NULL 값 처리. 이 함수는 non-blocking API 이다. lock 여부는 다른 API를 이용하여 caller가 체크 해야 한다. @param[in] id FE 채널 id. @param[in] freqKHz KHz 단위의 주파수. 디지털, 아날로그 상관 없이 항상 center frequency를 지정한다. @param[in] demod demodulation mode. @param[in] settings OOB 를 위한 부가적인 demodulator settings, NULL을 입력하면 default 값으로 동작해야한다. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_Start(tDHL_TunerID id, UINT32 freqKHz, tDHL_Demod demod, tDHL_DemodExtSettings *settings); /** @brief FE 동작 종료. 현재 이 API의 용도가 그다지 명확하지는 않다. 이 API는 채널 변경 직전에 MW에서 사용하는데, power control을 의미하지 않는다. tuner, demod 전원을 off/on 하면 시간이 많이 걸림. 전원 제어의 목적이라면 별도의 API를 이용하도록 한다. @param[in] id FE 채널 id. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_Stop(tDHL_TunerID id); /** @brief Lock 여부를 판단한다. VSB, QAMxx 의 경우: tuner, demod 동작, TS 출력이 가능한 상태. NTSC 의 경우: ?? @todo ntsc demod 에서 lock이 되었어도 ntsc video decoder 에서 동작 못할 수도 있다. 어떤 기준으로 lock을 할 것인지 좀 더 검토 필요. @param[in] id FE 채널 id. @param[out] pbLock lock 이면 TRUE를 리턴. @param[out] pDemod demod 정보가 리턴. lock 이 아니면 eDHL_DEMOD_UNKNOWN 리턴. caller는 이 정보가 필요하지 않다면 NULL을 지정할 수 있다. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_GetLockStatus(tDHL_TunerID id, BOOL *pbLock, tDHL_Demod *pDemod); /** @brief 어떤 demodultion 으로 동작하고 있는지를 리턴한다. 튜너가 lock 된 상태에서 사용 가능하다. Lock이 되지 않은 상태에서 이 함수를 사용하면 eDHL_DEMOD_UNKNOWN 을 리턴한다. @param[in] id FE 채널 id. @param[out] pDemod 현재 demod 정보가 리턴될 곳. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_GetModFormat(tDHL_TunerID id, tDHL_Demod *pDemod); /** @brief 신호와 관련된 각종 정보를 리턴한다. Lock, SNR, SER 등등의 상태 정보를 가져옴. @param[in] id FE 채널 id. @param[in] selector 조회하기를 원하는 정보 종류. @param[out] pValue 정보가 리턴되는 곳. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_GetSignalStatus(tDHL_TunerID id, tDHL_SignalStatus selector, UINT32 *pValue); /** @brief 신호 세기 정보 리턴. @todo "신호 세기"라는 말은 여러가지 의미로 해석될 수 있으므로 좀 더 명확한 설명이 필요함. 어떤 용도로 사용할 것인지에 따라 달라진다. meter bar 표시 용도: SNR monitor check 용도: error ratio 이 함수는 DHL_FE_GetSignalStatus 에 포함 가능하다. @param[in] id FE 채널 id. @param[out] pstrength 신호 세기 측정값 반환. @return - DHL_OK: 성공. - DHL_FAIL_ : 기타 FAIL 상태 반환. */ DHL_RESULT DHL_FE_GetSignalStrength(tDHL_TunerID id, UINT32 *pstrength); /** @brief RF 채널 번호에 해당되는 주파수 값을 KHz 단위로 리턴한다. 어떤 Table을 사용할 것인지에 따라 결과가 달라진다. @param[in] ch RF 번호. @param[in] freqTbl band. Air/Cable 또는 cable system Table 지정. @return - KHz 단위의 주파수 값. */ UINT32 DHL_FE_ChannelToFrequency(int ch, tDHL_FreqStd freqTbl); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* __DHL_FE_H__ */