/** @file DHL_Timer.h @brief OSAL 기반의 범용 타이머 API 범용으로 사용 가능한 구간 타이머. Copyright 2006~2010 Digital STREAM Technology, Inc. All Rights Reserved */ #ifndef __DHL_TIMER_API_H__ #define __DHL_TIMER_API_H__ #include "DHL_OSAL.h" #ifdef __cplusplus extern "C" { #endif #if COMMENT ____Overview____(){} #endif /** @file DHL_Timer.h - 개념 관련 내용은 구글 문서 참고. - 문서 이름: DHL API 매뉴얼 - URL http://docs.google.com/View?docid=0AQZYAjzYyTl_ZGdmcWJ4eDZfMjFjajZ6aGc0OA - module overview - 타이머: 타이머 아이디 - 타이머 이벤트: 지정 시간 경과 후 callback이 불리는 현상을 말함. - 타이머 그룹: 한 태스크에서 같이 처리되는 타이머들의 집합. - dependencies - OSAL (Task, Tick, MsgQ, ...) 타이밍 정확도는 OSAL의 Tick 정확도에 따른다. 아주 정확한 계측 용으로는 적절하지 않을 수 있음. */ #if COMMENT ____Config____(){} #endif /* 타이머 관련 내용 중에서 platform dependent 한 내용들은 아래 별도의 파일 아래 파일은 반드시 platform 헤더 폴더에서 제공되어야 한다. 필요한 내용들: DHL_TIMER_MAX_ENTRY DHL_TIMER_TASK_PRIORITY DHL_TIMER_TASK_STKSIZE 그리고 각 Timer ID 값들. */ #include "DHL_Timer_Config.h" #if COMMENT ____Types____(){} #endif /** @brief 타이머 그룹 핸들. DHL_TIMER_Initialize 실행 결과로 리턴되는 값이다. 동일 그룹에 속한 타이머 ID들은 같은 태스크에서 서비스된다. 따라서 타이머 성격에 따라 필요한 만큼의 태스크를 만들어 사용해야 한다. */ typedef void *DHL_TMHANDLE; /** @brief 타이머 그룹 생성 파라미터. DHL_TIMER_Initialize 의 인자로 필요함. */ typedef struct { char *name; ///< 이 타이머 그룹의 이름. 최대 8자. /** this will be copied into timer record DB. so local stack space can be used for name. */ int max_timer_entry; ///< 이 그룹에서 최대로 지원하는 타이머 갯수. 0보다 커야 함. int task_priority; ///< 타이머 태스크의 우선 순위. int stack_size; ///< 타이머 태스크의 스택 크기. BOOL use_mutex_lock; ///< 보호에 mutex를 사용할 것인지 여부. /** - if true, mutex is used for access timer record. - if false, interrupt is temporarily disabled during timer record access. if you want to use timer in ISR, set this FALSE. */ //--------- version 2 extension ------------- // if set to 0, it should be compatible to version 1 operation. int num_user_param; ///< 사용자 파라미터로 몇 개가 필요한지. ///< 기존에는 하나의 사용자 파라미터만 제공하였으나, 임의 갯수로 확장 할 수 있도록 함. ///< 0을 지정하면 1로 자동 설정된다. int msg_que_size; ///< timer task message queue의 크기. ///< 기존에는 소스 코드에 20 으로 fix 되어 있었음. ///< 0을 지정하면 디폴트 20으로 재설정됨. } DHL_TIMER_INIT_PARAM; /** @brief 사용자 타이머 callback 타입. DHL_TIMER_Start 및 DHL_SYS_StartTimer 에서 사용된다. 사용자는 아래와 동일한 prototype의 callback 함수를 제공해야 한다. */ typedef void (*DHL_TIMER_PROC)(UINT32 nIDTimer, UINT32 param); // 사용자 타이머 핸들러 /** @brief version 2의 타이머 callback 타입. DHL_TIMER_StartEx 에서 사용된다. param 배열의 실제 element 갯수는 이 prototype 에서는 알 수없다. timer init 할 때 지정한 갯수 만큼 사용 가능하다. */ typedef void (*DHL_TIMER_PROC_EX)(UINT32 nIDTimer, UINT32 *params); // 사용자 타이머 핸들러 /** DHL_TIMER_StartEx 에서 지정하는 flag들. */ typedef enum { /** continuous mode */ eTIMER_FLAG_Continue = 0x0, /** one shot mode */ eTIMER_FLAG_OneShot = 0x1, /** one shot 이 아닌 경우에만 의미가 있으며, 지금 바로 1회를 수행한 후에 지정된 시간 이후 interval timer를 기동한다. */ eTIMER_FLAG_NowAndContinue = 0x2, /** 내부용도로 사용되어 예약. */ eTIMER_FLAG_Reserved = 0xC0, } DHL_TIMER_FLAGS; #if COMMENT ____Defines____(){} #endif #if COMMENT ____LowLevel_API____(){} #endif /** @brief Low-level 타이머를 등록한다. timer 하나를 등록한다. 이후 일정 시간이 지나면 timer callback이 호출된다. 타이머의 세부 동작을 지정할 수 있다. - 인터벌 타이머 - 주기적으로 계속 타이머 callback이 호출된다. - 타이머 동작을 중지시키려면 반드시 Stop API를 호출해줘야 한다. - 원샷 타이머 - 지정 시간 경과 후 1회만 callback이 호출된다. - 별도로 타이머 cancel API를 호출해 주지 않아도 된다. @param[in] handle 타이머 그룹 핸들. DHL_TIMER_Initialize 로 만들어진 것이어야 한다. @param[in] nIdTimer 타이머 ID. 이 그룹 내에서 이 타이머를 대표할 수 있는 중복되지 않는 id 값. @param[in] nPeriodMs 밀리초 단위의 주기. @param[in] func 타이버 이벤트 발생 시 호출될 콜백 함수. @param[in] param 콜백 함수로 bypass 전달 되는 사용자 파라미터. @param[in] bOneShot TRUE 이면 지정된 시간 경과 후 1회만 호출 되는 원샷 타이머로 동작. FALSE 이면 주기적으로 호출되는 인터벌 타이머로 동작. @return */ DHL_RESULT DHL_TIMER_Start(DHL_TMHANDLE handle, UINT32 nIdTimer, UINT32 nPeriodMs, DHL_TIMER_PROC func, UINT32 param, BOOL bOneShot); /** @brief DHL_TIMER_Start API의 확장. param은 UINT32 값에서 UINT32 array pointer로 변경 되었음. OneShot 모드 외에 다양한 모드를 지원하기 위해 flag로 변경. @param[in] params 사용자 파라미터들의 배열 포인터. 몇 개의 파라미터가 사용 가능한지는 Initialize 할 때 결정된다. @param[in] flags DHL_TIMER_FLAGS 플래그 중에 하나. */ DHL_RESULT DHL_TIMER_StartEx(DHL_TMHANDLE handle, UINT32 nIdTimer, UINT32 nPeriodMs, DHL_TIMER_PROC_EX func, int numParam, UINT32 *params, UINT16 flags); /** @brief Low-level 타이머 등록 해제 지정 그룹에서 timer id를 제거한다. 더 이상 해당 타이머는 호출되지 않는다. 원샷 타이머의 경우 별도로 타이머 cancel API를 호출해 주지 않아도 된다. @param[in] handle 타이머 그룹 핸들. DHL_TIMER_Initialize 로 만들어진다. @param[in] nIdTimer 정지 시킬 타이머 ID @return */ DHL_RESULT DHL_TIMER_Stop(DHL_TMHANDLE handle, UINT32 nIdTimer); /** @brief Low-level 타이머 태스크 동기화. 타이머 태스크와 호출 태스크간의 동기를 맞춘다. 이 함수는 태생적으로 blocking mode로 동작한다. @param[in] handle 타이머 그룹 핸들. DHL_TIMER_Initialize 로 만들어진다. @return */ DHL_RESULT DHL_TIMER_Sync(DHL_TMHANDLE handle); /** @brief Low-level 타이머 정보 출력. 지정한 타이머 그룹의 정보를 디버그 콘솔에 출력한다. DHL_OS_Printf 를 이용하여 출력된다. @param[in] handle 타이머 그룹 핸들 */ void DHL_TIMER_Show(DHL_TMHANDLE handle); /** @brief Low-level 타이머 태스크 생성 (그룹 초기화) timer module을 초기화 한다. @param[in] param 타이머 그룹 속성. @param[out] pHandle 생성된 타이머 그룹 핸들. @return */ DHL_RESULT DHL_TIMER_Initialize(DHL_TIMER_INIT_PARAM *param, DHL_TMHANDLE *pHandle); /** @brief Low-level 타이머 태스크 제거 (그룹 삭제) 그룹 내에서 현재 동작 중인 모든 타이머가 완전 종료 된 후에 삭제된다. - 현재 이벤트가 발생되어 처리 중인 타이머는 이벤트 처리 후 종료. - 등록 되어 있고 callback 준비 중인 타이머는 그냥 cancel. @param[in] handle 타이머 그룹 핸들 */ void DHL_TIMER_Terminate(DHL_TMHANDLE handle); #if COMMENT ____HighLevel_API____(){} #endif /** @brief High-level 타이머 id 하나를 시작한다. DHL_SYS_TimerInit 에서 디폴트로 생성된 타이머 그룹에 추가된다. 각 인자 및 리턴값의 의미는 DHL_TIMER_Start 와 동일하다. */ DHL_RESULT DHL_SYS_StartTimer(UINT32 nIdTimer, UINT32 nPeriodMs, DHL_TIMER_PROC func, UINT32 param, BOOL bOneShot); /** @brief High-level 타이머 id 하나를 종료한다. DHL_SYS_TimerInit 에서 디폴트로 생성된 타이머 그룹에서 제거된다. 각 인자 및 리턴값의 의미는 DHL_TIMER_Stop 과 동일하다. */ DHL_RESULT DHL_SYS_KillTimer(UINT32 nIdTimer); /** @brief High-level 타이머 정보 출력. DHL_SYS_TimerInit 에서 디폴트로 생성된 타이머 그룹에 대한 정보다. */ void DHL_SYS_ShowTimer(void); /** @brief High-level 타이머 모듈 초기화 디폴트 priority, 디폴트 stack size 등은 일부 DHL_TimerConfig.h 내용을 참고하여 생성된다. */ DHL_RESULT DHL_SYS_TimerInit(void); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* __DHL_TIMER_API_H__ */