/** @file OSX_Task.h @brief OSAL 기반의 범용 태스크 API 범용으로 사용 가능한 태스크 Skeleton Copyright 2006~2010 Digital STREAM Technology, Inc. All Rights Reserved */ #ifndef __OSX_TASK_H__ #define __OSX_TASK_H__ #include "DHL_OSAL.h" #ifdef __cplusplus extern "C" { #endif #if COMMENT ____Overview____(){} #endif /** @file OSX_Task.h - 개념 관련 내용은 구글 문서 참고. - 문서 이름: - URL - module overview - dependencies - OSAL (Task, Tick, MsgQ, ...) 타이밍 정확도는 OSAL의 Tick 정확도에 따른다. 아주 정확한 계측 용으로는 적절하지 않을 수 있음. */ #if COMMENT ____Config____(){} #endif /* OSX Task 정보를 위한 영역은 미리 고정된 크기로 할당해 놓는다. */ #ifndef OSX_MAX_TASK #define OSX_MAX_TASK 32 #endif /* task command proc 에서 사용할 argument의 최대 갯수. 이 값은 외부에서 override 가능하다. */ #ifndef OSX_MAX_USER_PARAMS #define OSX_MAX_USER_PARAMS 4 #endif #if OSX_MAX_USER_PARAMS > 8 #error too many user params #endif #if COMMENT ____Types____(){} #endif /** @brief OSX 태스크 핸들. OSX_TaskStart 실행 결과로 리턴되는 값이다. */ typedef UINT32 H_OSX_TASK; /** @brief command id 타입. 일반 숫자 값이다. 이 영역 중에서 사용자가 사용할 수 없는 예약 영역이 있다. - cmd id 0은 사용 불가. - cmd id가 OSX_CMD_RESERVED 이상의 값 사용 불가. */ typedef UINT8 T_OSX_TASK_CMD; /** @brief 태스크 생성 파라미터. OSX_TaskStart 의 인자로 필요함. 디폴트 값은 OSX_TaskGetDefaultInitSetting API로 얻을 수 있으나 가능하면 각각 지정해 주는 것이 권장됨. */ typedef struct { char *name; ///< 이 태스트 이름. 최대 8자. /** this will be copied into internal DB. so local stack space can be used for name. */ int max_scheduled_cmd; ///< 이 태스크에서 동시에 지원하는 예약 명령어 최대 갯수. 0보다 커야 함. int priority; ///< 태스크의 우선 순위. int stack_size; ///< 태스크의 스택 크기. int num_cmd_param; ///< command 인자로 몇 개가 필요한지. ///< 0을 지정하면 1로 자동 설정된다. int msg_que_size; ///< task message queue의 크기. ///< 0을 지정하면 디폴트 20으로 재설정됨. } S_OSX_TASK_INIT_SETTING; /** @brief command proc. OSX_TaskSendCmd 에서 사용된다. param 가변 인자의 실제 갯수는 이 prototype 에서는 알 수없다. task start 할 때 지정한 갯수 만큼 사용 가능하다. */ typedef void (*F_OSX_TASK_PROC)(T_OSX_TASK_CMD nIdCmd, UINT32 param, ...); /** @brief OSX_TaskScheduleCmd 내부에서 지정하는 flag들. 실행 모드 관련해서는 */ typedef enum { /** 즉시 실행 옵션. 가장 일반적인 옵션. 지정하지 않으면 이 모드로 동작. */ eTASK_FLAG_Normal = 0x0, /** 지연 실행 옵션. 바로 실행하지 않고 지정한 delay만큼 기다린 후에 실행. */ eTASK_FLAG_Delayed = 0x1, /** 반복 실행 옵션. interval (주기)에 맞춰 반복 실행. */ eTASK_FLAG_Repeat = 0x2, /** 각종 파생 모드들 */ eTASK_FLAG_WaitAndRepeat = (eTASK_FLAG_Delayed | eTASK_FLAG_Repeat), eTASK_FLAG_NowAndRepeat = (eTASK_FLAG_Normal | eTASK_FLAG_Repeat), /* 모든 경우의 수: call ------------------------------------------> time Normal Action Delayed Action WaitAndRepeat Action Action Action ... NowAndRepeat Action Action Action Action ... |<-delay->|<-delay->|<-delay->|<-delay->| */ } E_OSX_TASK_CMD_FLAGS; /** @brief task의 간단한 정보 OSX_TaskGetInfo API 에서 사용. */ typedef struct { DHL_OS_TASK_ID tid; } S_OSX_TASK_INFO; #if COMMENT ____Defines____(){} #endif /* cmd id 중에서 예약 된 부분. 이 값 이상은 사용 금지임. */ #define OSX_CMD_RESERVED 0xf0 #if COMMENT ____LowLevel_API____(){} #endif /** @brief 태스크에서 명령을 직접 실행하도록 하거나, 예약 한다. nDelayMs가 0이면 바로 실행되며, 0보다 크면 지정 시간 만큼 지연되었다가 실행된다. - 반복 실행 - 주기적으로 계속 명령이 반복 실행된다. - 반복 실행 동작을 중지시키려면 반드시 Stop API를 호출해줘야 한다. - 1회 실행 (직접 실행 또는 예약 실행) - 지정 시간 경과 후 1회만 callback이 호출된다. - 별도로 stop API를 호출해 주지 않아도 된다. @param[in] handle 태스크 핸들. OSX_TaskStart 로 만들어진 것이어야 한다. @param[in] nIdCmd 명령 id @param[in] nDelayMs 밀리초 단위의 시간. 0이면 바로 실행. 0보다 크고 eTASK_FLAG_Delayed 플래그가 있으면 지연 실행. @param[in] flags E_OSX_TASK_CMD_FLAGS 플래그. @param[in] func 명령 실행시 호출될 콜백 함수. @param[in] param 콜백 함수로 bypass 전달 되는 사용자 파라미터 va list. */ DHL_RESULT OSX_TaskRegisterCmdV(H_OSX_TASK handle, T_OSX_TASK_CMD nIdCmd, UINT32 nDelayMs, UINT16 flags, F_OSX_TASK_PROC func, va_list param); /** @brief 태스크에서 즉시 명령 실행. @param[in] handle 태스크 핸들. OSX_TaskStart 로 만들어진 것이어야 한다. @param[in] nIdCmd 명령 id @param[in] flags E_OSX_TASK_CMD_FLAGS 플래그. 지연/반복 기능의 flag는 무시됨. @param[in] func 명령 실행시 호출될 콜백 함수. @param[in] param 콜백 함수로 bypass 전달 되는 사용자 파라미터 va list. 몇개의 param이 필요한지는 Start 할 때 init setting에서 지정. */ DHL_RESULT OSX_TaskRunCmd(H_OSX_TASK handle, T_OSX_TASK_CMD nIdCmd, UINT16 flags, F_OSX_TASK_PROC func, ...); /** @brief 태스크에서 지연/반복 명령 실행. @param[in] handle 태스크 핸들. OSX_TaskStart 로 만들어진 것이어야 한다. @param[in] nIdCmd 명령 id @param[in] nDelayMs 밀리초 단위의 시간. 0이면 바로 실행. 0보다 크고 eTASK_FLAG_Delayed 플래그가 있으면 지연 실행. @param[in] flags E_OSX_TASK_CMD_FLAGS 플래그. @param[in] func 명령 실행시 호출될 콜백 함수. @param[in] param 콜백 함수로 bypass 전달 되는 사용자 파라미터 va list. 몇개의 param이 필요한지는 Start 할 때 init setting에서 지정. */ DHL_RESULT OSX_TaskScheduleCmd(H_OSX_TASK handle, T_OSX_TASK_CMD nIdCmd, UINT32 nDelayMs, UINT16 flags, F_OSX_TASK_PROC func, ...); /** @brief 예약 되어 있는 대기 명령 강제 종료. 반복, 지연 명령의 경우에만 효과가 있다. @param[in] handle 태스크 핸들. OSX_TaskStart 로 만들어진다. @param[in] nIdCmd 정지 시킬 명령 */ DHL_RESULT OSX_TaskStopCmd(H_OSX_TASK handle, T_OSX_TASK_CMD nIdCmd); /** @brief Low-level 타이머 태스크 동기화. 모든 명령 실행 API들이 비동기적으로 수행되는데, 이 API를 이용하여 동기화 가능. task에서 이 명령을 인식하고 ack를 보낼 때 까지 blocking 된다. @param[in] handle 태스크 핸들. OSX_TaskStart 로 만들어진다. @return */ DHL_RESULT OSX_TaskSync(H_OSX_TASK handle); /** @brief 태스크 내부 정보 콘솔 출력. 지정한 태스크의 정보를 디버그 콘솔에 출력한다. DHL_OS_Printf 를 이용하여 출력된다. NULL을 지정하면 전체 osx 태스크 정보를 출력한다. @param[in] handle 태스크 핸들 */ void OSX_TaskShow(H_OSX_TASK handle); /** @brief 태스크 핸들 정보, 내부 상태 정보 query */ void OSX_TaskGetInfo(H_OSX_TASK handle, S_OSX_TASK_INFO *pinfo); /** @brief 태스크 생성. @param[in] setting 태스크 속성. @param[out] pHandle 생성된 태스크 핸들. @return */ DHL_RESULT OSX_TaskStart(S_OSX_TASK_INIT_SETTING *setting, H_OSX_TASK *pHandle); /** @brief 태스크 종료 그룹 내에서 현재 동작 중인 모든 타이머가 완전 종료 된 후에 삭제된다. - 현재 callback 실행 중인 명령은 완료 후 종료. - 등록 되어 있고 callback 준비 중인 명령은 그냥 cancel. @param[in] handle 태스크 핸들 */ void OSX_TaskShutdown(H_OSX_TASK handle); /** @brief 태스크 생성 파라미터의 디폴트 값 획득. @param[out] setting 디폴트 속성. */ void OSX_TaskGetDefaultInitSetting(S_OSX_TASK_INIT_SETTING *setting); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* __OSX_TASK_H__ */