Include/vos_task.h

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