Include/vos_task.h

   1 /******************************************************************************
   2 ###############################################################################
   3 #   Copyright (c) [2017-2020] [ICT/CAS]                                        #
   4 #   Licensed under the ORAN Software License v1.0 (License)             #
   5 ###############################################################################
   6 ******************************************************************************/
   7
   8
   9 #ifndef __VOS_TASK_H__
  10 #define __VOS_TASK_H__
  11
  12 #include "vos_types.h"
  13 #include "vos_module.h"
  14
  15 #ifdef    __cplusplus
  16 extern "C"
  17 {
  18 #endif /* __cplusplus */
  19
  20 /** VOS任务的参数个数. */
  21 #define VOS_MAX_TASK_ARGS                     10
  22
  23 /** 任务的缺省栈大小. */
  24 #define VOS_DEFAULT_STACKSIZE                 __VOS_DEFAULT_STACKSIZE
  25
  26 /** 任务入口定义宏. */
  27 #define DECLARE_VOS_TASK(VOS_TASK_ENTRY)\
  28     VOID VOS_TASK_ENTRY(\
  29         ULONG ulArg1, ULONG ulArg2,\
  30         ULONG ulArg3, ULONG ulArg4,\
  31         ULONG ulArg5, ULONG ulArg6,\
  32         ULONG ulArg7, ULONG ulArg8,\
  33         ULONG ulArg9, ULONG ulArg10\
  34         )
  35
  36 /** 任务优先级枚举值，创建任务时请使用下面的枚举值，不要用立即数. */
  37 typedef enum VOS_task_pri_s
  38 {
  39     TASK_PRIORITY_TIME_CRITICAL   =  __TASK_PRIORITY_TIME_CRITICAL,
  40     TASK_PRIORITY_HIGHEST         =  __TASK_PRIORITY_HIGHEST,
  41     TASK_PRIORITY_HIGHER          =  __TASK_PRIORITY_HIGHER,
  42     TASK_PRIORITY_HIGH            =  __TASK_PRIORITY_HIGH,
  43     TASK_PRIORITY_ABOVE_NORMAL    =  __TASK_PRIORITY_ABOVE_NORMAL,
  44     TASK_PRIORITY_NORMAL          =  __TASK_PRIORITY_NORMAL,
  45     TASK_PRIORITY_BELOW_NORMAL    =  __TASK_PRIORITY_BELOW_NORMAL,
  46     TASK_PRIORITY_LOWEST          =  __TASK_PRIORITY_LOWEST,
  47     TASK_PRIORITY_IDLE            =  __TASK_PRIORITY_IDLE,
  48 }VOS_task_pri_t;
  49
  50 typedef VOS_msg_code_handler_ptr VOS_user_task_entry;
  51
  52
  53 /** 用户任务结构体 */
  54 typedef struct VOS_user_task_s
  55 {
  56     CHAR                     userTaskName[VOS_NAME_MAX_LENGTH];     ///< 用户任务名
  57     VOS_user_task_entry      userTaskEntry;                         ///< 用户任务入口
  58     ULONG                    moduleID;                              ///< 用于 VOS_Malloc 的第二个参数
  59 }VOS_user_task_t;
  60
  61
  62 /** 任务入口函数类型. */
  63 typedef VOID (*VOS_TASK_ENTRY)( ULONG pArg1, ULONG pArg2, ULONG pArg3,
  64            ULONG pArg4, ULONG pArg5, ULONG pArg6,
  65            ULONG pArg7, ULONG pArg8, ULONG pArg9,
  66            ULONG pArg10 );
  67
  68 /**
  69  * 任务创建 宏,
  70  * 该宏 会创建一个线程，栈大小为 VOS_DEFAULT_STACKSIZE 。
  71  * @param[in]   taskName       任务名，长度为 VOS_NAME_MAX_LENGTH
  72  * @param[in]   lPriority      优先级，使用 VOS_task_pri_t 枚举值
  73  * @param[in]   pfEntry        任务入口函数， 原型为VOS_TASK_ENTRY，10个ULONG 参数，无返回值
  74                                定义时使用宏DECLARE_VOS_TASK定义，eg：DECLARE_VOS_TASK(task1){ .... }
  75  * @param[in]   lTaskArg       传给任务入口函数的参数，类型为ULONG pArgs[10]
  76  * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
  77  */
  78 #define VOS_TaskCreate( taskName, lPriority, pfEntry, lTaskArg )\
  79     VOS_TaskCreate_Ex_X( taskName, pfEntry, #pfEntry, (ULONG)(lPriority), VOS_DEFAULT_STACKSIZE, (ULONG *)(lTaskArg) )
  80
  81 /**
  82  * 任务创建 宏,
  83  * 该宏 会创建一个线程。
  84  * @param[in]   taskName       任务名，长度为 VOS_NAME_MAX_LENGTH
  85  * @param[in]   pfEntry        任务入口函数， 原型为VOS_TASK_ENTRY，10个ULONG 参数，无返回值
  86                                定义时使用宏DECLARE_VOS_TASK定义，eg：DECLARE_VOS_TASK(task1){ .... }
  87  * @param[in]   lPriority      优先级，使用 VOS_task_pri_t 枚举值
  88  * @param[in]   ulStackSize    栈大小
  89  * @param[in]   lTaskArg       传给任务入口函数的参数，类型为ULONG pArgs[10]
  90  * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
  91  */
  92 #define VOS_TaskCreateEx( taskName, pfEntry, lPriority, ulStackSize, lTaskArg )\
  93     VOS_TaskCreate_Ex_X( taskName, pfEntry, #pfEntry, lPriority, ulStackSize, lTaskArg )
  94
  95
  96 /**
  97  * 任务延时 宏,
  98  * 当前任务睡眠一定的时间.
  99  * @param[in]   lMsec    延时时间，毫秒
 100  * @return      VOS_OK - 成功，其他 - 失败
 101  */
 102 #define VOS_TaskDelay( lMsec )\
 103     (LONG)VOS_TaskDelay_Ex_X( (lMsec), __FILE__, __LINE__ )
 104
 105
 106 /**
 107  * 任务删除 API,
 108  * 将指定任务删除 。
 109  * @param[in]   hTaskHandle    任务创建时返回的任务句柄
 110  * @param[in]   ulExitCode     任务退出码，仅在windows系统中有效，其他传 0 即可
 111  * @return      VOS_OK - 成功，其他 - 失败
 112  */
 113 LONG VOS_TaskTerminate( VOS_HANDLE hTaskHandle, ULONG ulExitCode );
 114
 115 /**
 116  * 将任务信息注册到vos task，在任务入口的最开始调用。main函数则在调用VOS_init()后调用
 117  * @return      VOS_OK - 成功，其他 - 失败
 118  */
 119 LONG VOS_TaskInfoAttach(void);
 120
 121 /**
 122 * 得到当前VOS任务句柄
 123 * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
 124 */
 125 VOS_HANDLE VOS_GetCurrentTask( VOID );
 126
 127
 128 /**
 129  * 获得任务优先级
 130  *
 131  * @param[in]    hTaskHandle    任务创建时返回的任务句柄
 132  * @param[out]   pPrio          任务优先级
 133  * @return       VOS_OK - 成功，其他 - 失败
 134  */
 135 LONG VOS_TaskGetPriority( VOS_HANDLE hTaskHandle, ULONG *pPrio );
 136
 137
 138 /**
 139  * 设置任务优先级
 140  *
 141  * @param[in]    hTaskHandle    任务创建时返回的任务句柄
 142  * @param[in]    ulnewPrio      任务优先级
 143  * @return       VOS_OK - 成功，其他 - 失败
 144  */
 145 LONG VOS_TaskSetPriority( VOS_HANDLE hTaskHandle, ULONG ulnewPrio );
 146
 147
 148 /**
 149  * 获取当前任务的名字.
 150  *
 151  * @param[out]    szTaskName     任务名，长度 VOS_NAME_MAX_LENGTH
 152  * @return       VOS_OK - 成功，其他 - 失败
 153  */
 154 LONG VOS_GetCurrentTaskName( CHAR szTaskName[VOS_NAME_MAX_LENGTH] );
 155
 156
 157 /**
 158  * 判断任务句柄是否有效.
 159  *
 160  * @param[in]    hTaskHandle     任务句柄
 161  * @return       有效返回真，否则返回假
 162  */
 163 BOOL VOS_TaskHandleVerify( VOS_HANDLE hTaskHandle );
 164
 165
 166 /**
 167  * 创建宿主任务，宿主任务可以绑定多个用户任务(回调函数),栈大小为 VOS_DEFAULT_STACKSIZE。
 168  * @param[in]   taskName         任务名，长度为 VOS_NAME_MAX_LENGTH
 169  * @param[in]   lPriority        优先级，使用 VOS_task_pri_t 枚举值
 170  * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
 171  */
 172 #define VOS_TaskHostCreate( taskName, lPriority )\
 173     VOS_TaskHostCreate_Ex_X( taskName, lPriority, VOS_DEFAULT_STACKSIZE)
 174
 175 /**
 176  * 创建宿主任务，宿主任务可以绑定多个用户任务(回调函数)。
 177  * @param[in]   taskName         任务名，长度为 VOS_NAME_MAX_LENGTH
 178  * @param[in]   lPriority        优先级，使用 VOS_task_pri_t 枚举值
 179  * @param[in]   ulStackSize      栈大小
 180  * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
 181  */
 182 #define VOS_TaskHostCreateEx( taskName, lPriority, ulStackSize )\
 183     VOS_TaskHostCreate_Ex_X( taskName, lPriority, ulStackSize )
 184
 185
 186
 187 /**
 188  * 删除宿主任务，同时该宿主任务下的用户任务将被全部删除
 189  *
 190  * @param[in ]    szTaskName    宿主任务名
 191  * @param[in ]    ulExitCode    退出码(暂未使用，填0即可)
 192  * @return       VOS_OK - 成功，其他 - 失败
 193  */
 194 LONG VOS_TaskHostTerminate(CHAR szTaskName[VOS_NAME_MAX_LENGTH], ULONG ulExitCode);
 195
 196
 197 /**
 198  * 向宿主任务中添加用户任务(回调函数)。
 199  *
 200  * @param[in ]    hostTaskName    宿主任务名
 201  * @param[in ]    userTask        用户任务
 202  * @return       VOS_OK - 成功，其他 - 失败
 203  */
 204 LONG VOS_UserTaskAttach(CHAR hostTaskName[VOS_NAME_MAX_LENGTH],VOS_user_task_t *userTask);
 205
 206
 207 /**
 208  * 从宿主任务中删除用户任务(回调函数)。
 209  *
 210  * @param[in ]    hostTaskName    宿主任务名
 211  * @param[in ]    userTaskName    用户任务
 212  * @return       VOS_OK - 成功，其他 - 失败
 213  */
 214 LONG VOS_UserTaskDetach(CHAR hostTaskName[VOS_NAME_MAX_LENGTH],CHAR userTaskName[VOS_NAME_MAX_LENGTH]);
 215
 216
 217
 218 /**
 219  * 设置任务的CPU亲和性
 220  *
 221  * @param[in ]    taskName    任务名(包含宿主任务，不包含用户任务)
 222  * @param[in ]    size        CPU个数
 223  * @param[in ]    cpus        CPU ID 数组
 224  * @return       VOS_OK - 成功，其他 - 失败
 225  */
 226 LONG VOS_TaskAffinitySet(CHAR taskName[VOS_NAME_MAX_LENGTH],LONG size,LONG cpus[]);
 227
 228
 229 /**
 230  * 获取任务的CPU亲和性,如果实际CPU个数超过cpus数组大小，则只返回size个cpu ID,返回值为 VOS_ERROR_BAD_ARGUMENTS
 231  *
 232  * @param[in ]    taskName    任务名(包含宿主任务，不包含用户任务)
 233  * @param[in ]    size        cpus数组大小
 234  * @param[out]    size        cpus数组有效值个数
 235  * @param[in ]    cpus        CPU ID 数组
 236  * @return       VOS_OK - 成功，其他 - 失败
 237  */
 238 LONG VOS_TaskAffinityGet(CHAR taskName[VOS_NAME_MAX_LENGTH],LONG *size,LONG cpus[]);
 239
 240
 241
 242 /*=========================================================================================================================*/
 243 /* ###### 下面的函数不要直接调用，使用上面提供的宏 ###### */
 244
 245 /**
 246 * 任务创建 API，不要直接使用，通过 VOS_TaskCreate 宏使用
 247 * 该API会创建一个线程，栈大小为 VOS_DEFAULT_STACKSIZE 。
 248 * @param[in]   szTaskName       任务名，长度为 VOS_NAME_MAX_LENGTH
 249 * @param[in]   pfnFunc          任务入口函数， 原型为VOS_TASK_ENTRY，10个ULONG 参数，无返回值
 250 * @param[in]   szFuncName       任务入口函数名
 251 * @param[in]   ulStartPriority  优先级，使用 VOS_task_pri_t 枚举值
 252 * @param[in]   ulStackSize      栈大小
 253 * @param[in]   pArgs            传给任务入口函数的参数，类型为ULONG pArgs[10]
 254 * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
 255 */
 256 VOS_HANDLE VOS_TaskCreate_Ex_X( CHAR szTaskName[VOS_NAME_MAX_LENGTH],
 257                            VOS_TASK_ENTRY pfnFunc,
 258                            CHAR *szFuncName,
 259                            ULONG ulStartPriority,
 260                            ULONG ulStackSize,
 261                            ULONG pArgs[VOS_MAX_TASK_ARGS]);
 262
 263 /**
 264 * 任务延时 API，不要直接使用，通过 VOS_TaskDelay 宏使用
 265 * 当前任务睡眠一定的时间.
 266 * @param[in]   lMsec       延时时间，毫秒
 267 * @param[in]   szFileName  调用者的文件
 268 * @param[in]   iLine       调用者的行号
 269 * @return      VOS_OK - 成功，其他 - 失败
 270 */
 271 LONG VOS_TaskDelay_Ex_X( ULONG lMsec, CHAR *szFileName, INT iLine );
 272
 273
 274 /**
 275  * 创建宿主任务，不要直接使用，通过 VOS_TaskHostCreate 宏使用,宿主任务可以绑定多个用户任务(回调函数)。
 276  *
 277  * @param[in]   szTaskName       任务名，长度为 VOS_NAME_MAX_LENGTH
 278  * @param[in]   ulStartPriority  优先级，使用 VOS_task_pri_t 枚举值
 279  * @param[in]   ulStackSize      栈大小
 280  * @return      成功返回VOS_HANDLE 类型的任务句柄，失败返回NULL
 281  */
 282 VOS_HANDLE VOS_TaskHostCreate_Ex_X( CHAR szTaskName[VOS_NAME_MAX_LENGTH],
 283                            ULONG ulStartPriority,
 284                            ULONG ulStackSize);
 285
 286
 287 /**
 288  * 获得当前任务的进程ID(PID)
 289  *
 290  * @return      返回进程ID(PID)
 291  */
 292 ULONG VOS_TaskSelfGetPID(void);
 293
 294
 295 /**
 296  * 获得当前任务的线程ID(SPID)
 297  *
 298  * @return      返回线程ID(SPID)
 299  */
 300 ULONG VOS_TaskSelfGetSPID(void);
 301
 302
 303 /**
 304  * 获得当前任务的线程ID(thread ID)
 305  *
 306  * @return      返回线程ID(thread ID)
 307  */
 308 ULONG VOS_TaskSelfThreadID(void);
 309
 310
 311 #ifdef __cplusplus
 312 }
 313 #endif /* __cplusplus */
 314
 315 #endif /* __VOS_TASK_H__ */