1 /** 2 * @file hi_task.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "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 * http://www.apache.org/licenses/LICENSE-2.0 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 * @defgroup iot_task Task 20 * @ingroup osa 21 */ 22 #ifndef __HI_TASK_H__ 23 #define __HI_TASK_H__ 24 25 #include <hi_types_base.h> 26 27 #define HI_INVALID_TASK_ID 0xFFFFFFFF 28 #define HI_TASK_NAME_LEN 32 29 #define HI_DEFAULT_TSKNAME "default" /**< hi_task_attr default value. CNcomment:hi_task_attr的默认值CNend */ 30 #define HI_DEFAULT_TSKPRIO 20 /**< hi_task_attr default value. CNcomment:hi_task_attr的默认值CNend */ 31 #define HI_DEFAULT_STACKSIZE (4 * 1024) /**< hi_task_attr default value. CNcomment:hi_task_attr的默认值CNend */ 32 #define NOT_BIND_CPU (-1) 33 34 typedef struct { 35 hi_char name[HI_TASK_NAME_LEN]; /**< Task entrance function.CNcomment:入口函数CNend */ 36 hi_u32 id; /**< Task ID.CNcomment:任务ID CNend */ 37 hi_u16 status; /**< Task status.CNcomment:任务状态 CNend */ 38 hi_u16 priority; /**< Task priority.CNcomment:任务优先级 CNend */ 39 hi_pvoid task_sem; /**< Semaphore pointer.CNcomment:信号量指针CNend */ 40 hi_pvoid task_mutex; /**< Mutex pointer.CNcomment:互斥锁指针CNend */ 41 hi_u32 event_stru[3]; /**< Event: 3 nums.CNcomment:3个事件CNend */ 42 hi_u32 event_mask; /**< Event mask.CNcomment:事件掩码CNend */ 43 hi_u32 stack_size; /**< Task stack size.CNcomment:栈大小CNend */ 44 hi_u32 top_of_stack; /**< Task stack top.CNcomment:栈顶CNend */ 45 hi_u32 bottom_of_stack; /**< Task stack bottom.CNcomment:栈底CNend */ 46 hi_u32 mstatus; /**< Task current mstatus.CNcomment:当前mstatusCNend */ 47 hi_u32 mepc; /**< Task current mepc.CNcomment:当前mepc.CNend */ 48 hi_u32 tp; /**< Task current tp.CNcomment:当前tp.CNend */ 49 hi_u32 ra; /**< Task current ra.CNcomment:当前ra.CNend */ 50 hi_u32 sp; /**< Task SP pointer.CNcomment:当前SP.CNend */ 51 hi_u32 curr_used; /**< Current task stack usage.CNcomment:当前任务栈使用率CNend */ 52 hi_u32 peak_used; /**< Task stack usage peak.CNcomment:栈使用峰值CNend */ 53 hi_u32 overflow_flag; /**< Flag that indicates whether a task stack overflow occurs. 54 CNcomment:栈溢出标记位CNend */ 55 } hi_task_info; 56 57 typedef struct { 58 hi_u16 task_prio; 59 hi_u32 stack_size; 60 hi_u32 task_policy; 61 hi_u32 task_nice; 62 hi_u32 task_cpuid; 63 hi_char *task_name; 64 hi_void *resved; 65 } hi_task_attr; 66 67 /** 68 * @ingroup iot_task 69 * @brief Creates a task.CNcomment:创建任务。CNend 70 * 71 * @par 描述: 72 * Creates a task.CNcomment:创建任务。CNend 73 * 74 * @attention 75 * @li The space occupied by a task name string must be applied for by the caller and saved statically. 76 * The task name is not stored internally in the API.CNcomment:任务名字符串占用空间需要调用者 77 申请并静态保存，接口内部不对任务名进行存储。CNend 78 * @li If the size of the specified task stack is 0, use the default size specified by 79 * #OS_TSK_DEFAULT_STACK_SIZE. CNcomment:若指定的任务栈大小为0，则使用配置项 80 HI_DEFAULT_STACKSIZE指定默认的任务栈大小。CNend 81 * @li The size of the task stack should be 8-byte aligned. The principle for determining the task stack 82 * size is as follows: Do not use a too large or too small task stack size (to avoid waste or 83 * overflow).CNcomment:任务栈的大小按8byte大小对齐。确定任务栈大小的原则：够用即可（多则浪费， 84 少则任务栈溢出）。CNend 85 * @li The recommended user priority should be within the range of [10, 30]. Do not use the priorities of 86 * [0, 5] and [31].CNcomment:用户优先级配置建议使用[10,30]，切记不可使用[0,5]和[31]号的优先级。CNend 87 * 88 * @param taskid [OUT] type #hi_u32*，task ID.CNcomment:任务ID号。CNend 89 * @param attr [IN] type #const task_attr_t*，task attributes,when NULL was set here,the properties 90 are configured as follows: task_name:"default" task_prio:20 stack_size:(4*1024) 91 CNcomment:任务属性,当该值为空时配置如下:任务名:"default" 92 任务优先级:20 任务栈大小:(4*1024),CNend 93 * @param task_route [IN] type #task_route task entry function.CNcomment:任务入口函数。CNend 94 * @param arg [IN] type #hi_void*，parameter that needs to be input to the task entry when a task is 95 * created. If this parameter does not need to be input, set this parameter to 0. 96 CNcomment:创建任务时需要传给任务入口的参数。如果不需要传递，参数直接填0。CNend 97 * 98 * @retval #0 Success 99 * @retval #Other Failure. For details, see hi_errno.h. 100 * @par 依赖: 101 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 102 * @see hi_task_delete。 103 */ 104 hi_u32 hi_task_create(hi_u32 *taskid, const hi_task_attr *attr, 105 hi_void* (*task_route)(hi_void *), hi_void *arg); 106 107 /** 108 * @ingroup iot_task 109 * @brief Deletes a task.CNcomment:删除任务。CNend 110 * 111 * @par 描述: 112 * Deletes a task.CNcomment:删除任务。CNend 113 * 114 * @attention 115 * @li Use this API with caution. A task can be deleted only after the confirmation of the user. The idle task 116 * and Swt_Task cannot be deleted.idle.CNcomment:任务及Swt_Task任务不能被删除。CNend 117 * @li When deleting a task, ensure that the resources (such as mutex and semaphore) applied by the task have 118 * been released.在删除任务时要保证任务申请的资源（如互斥锁、信号量等）已被释放。CNend 119 * 120 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 121 * 122 * @retval #0 Success 123 * @retval #Other Failure. For details, see hi_errno.h. 124 * @par 依赖: 125 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 126 * @see hi_task_create。 127 */ 128 hi_u32 hi_task_delete(hi_u32 taskid); 129 130 /** 131 * @ingroup iot_task 132 * @brief Suspends a task.CNcomment:挂起任务。CNend 133 * 134 * @par 描述: 135 * Suspends a task.CNcomment:挂起指定任务。CNend 136 * 137 * @attention 138 * @li A task cannot be suspended if it is the current task and is locked. 139 CNcomment:挂起任务的时候若为当前任务且已锁任务，则不能被挂起。CNend 140 * @li The idle task and Swt_Task cannot be suspended. 141 CNcomment:idle任务及Swt_Task任务不能被挂起。CNend 142 * @li The task cannot be blocked or suspended in the lock task status. 143 CNcomment:在锁任务调度状态下，禁止任务阻塞。CNend 144 * 145 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 146 * 147 * @retval #0 Success 148 * @retval #Other Failure. For details, see hi_errno.h. 149 * @par 依赖: 150 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 151 * @see hi_task_resume。 152 */ 153 hi_u32 hi_task_suspend(hi_u32 taskid); 154 155 /** 156 * @ingroup iot_task 157 * @brief Resumes a task.CNcomment:恢复挂起任务。CNend 158 * 159 * @par 描述: 160 * Resumes a task.CNcomment:恢复挂起指定任务。CNend 161 * 162 * @attention None 163 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 164 * 165 * @retval #0 Success 166 * @retval #Other Failure. For details, see hi_errno.h. 167 * @par 依赖: 168 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 169 * @see hi_task_suspend。 170 */ 171 hi_u32 hi_task_resume(hi_u32 taskid); 172 173 /** 174 * @ingroup iot_task 175 * @brief Obtains the task priority.CNcomment:获取任务优先级。CNend 176 * 177 * @par 描述: 178 * Obtains the task priority.CNcomment:获取任务优先级。CNend 179 * 180 * @attention None 181 * 182 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 183 * @param priority [OUT] type #hi_u32*，task priority.CNcomment:任务优先级。CNend 184 * 185 * @retval #0 Success 186 * @retval #Other Failure. For details, see hi_errno.h. 187 * @par 依赖: 188 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 189 * @see hi_task_set_priority。 190 */ 191 hi_u32 hi_task_get_priority(hi_u32 taskid, hi_u32 *priority); 192 193 /** 194 * @ingroup iot_task 195 * @brief Sets the task priority.CNcomment:设置任务优先级。CNend 196 * 197 * @par 描述: 198 Sets the task priority.CNcomment:设置任务优先级。CNend 199 * 200 * @attention 201 * @li Only the ID of the task created by the user can be configured. 202 CNcomment:仅可配置用户自己创建的任务ID。CNend 203 * @li The recommended user priority should be within the range of [10, 30]. Do not use the priorities of 204 * [0, 5] and [31].CNcomment:用户优先级配置建议使用[10,30]，切记不可使用[0,5]和[31]号的优先级。CNend 205 * @li Setting user priorities may affect task scheduling. The user needs to plan tasks in the SDK. 206 CNcomment:设置用户优先级有可能影响任务调度，用户需要SDK中对各任务统一规划。CNend 207 * 208 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 209 * @param priority [IN] type #hi_u32，task priority.CNcomment:任务优先级。CNend 210 * 211 * @retval #0 Success 212 * @retval #Other Failure. For details, see hi_errno.h. 213 * @par 依赖: 214 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 215 * @see hi_task_get_priority。 216 */ 217 hi_u32 hi_task_set_priority(hi_u32 taskid, hi_u32 priority); 218 219 /** 220 * @ingroup iot_task 221 * @brief Obtains the task information.CNcomment:获取任务信息。CNend 222 * 223 * @par 描述: 224 * Obtains the task information.CNcomment:获取任务信息。CNend 225 * 226 * @attention None 227 * @param taskid [IN] type #hi_u32，task ID. CNcomment:任务ID号。CNend 228 * @param inf [OUT] type #hi_task_info* ，task information.CNcomment:任务信息。CNend 229 * 230 * @retval #0 Success 231 * @retval #Other Failure. For details, see hi_errno.h. 232 * @par 依赖: 233 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 234 * @see None 235 */ 236 hi_u32 hi_task_get_info(hi_u32 taskid, hi_task_info *inf); 237 238 /** 239 * @ingroup iot_task 240 * @brief Obtains the current task ID.CNcomment:获取当前任务ID。CNend 241 * 242 * @par 描述: 243 * Obtains the current task ID.CNcomment:获取当前任务ID。CNend 244 * 245 * @attention None 246 * @param None 247 * 248 * @retval #hi_u32 Task ID. If the task fails, #HI_INVALID_TASK_ID is returned. 249 CNcomment:任务ID，失败返回#HI_INVALID_TASK_ID。CNend 250 * @par 依赖: 251 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 252 * @see None 253 */ 254 hi_u32 hi_task_get_current_id(hi_void); 255 256 /** 257 * @ingroup iot_task 258 * @brief Lock task switch.CNcomment:禁止系统任务调度。CNend 259 * 260 * @par 描述: 261 * Lock task switch.CNcomment:禁止系统任务调度。CNend 262 * 263 * @attention Work pair with hi_task_unlock.CNcomment:与hi_task_unlock配对使用。CNend 264 * @param None 265 * 266 * @retval None 267 * @par 依赖: 268 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 269 * @see None 270 */ 271 hi_void hi_task_lock(hi_void); 272 273 /** 274 * @ingroup iot_task 275 * @brief Unlock task switch. CNcomment:允许系统任务调度。CNend 276 * 277 * @par 描述: 278 * Unlock task switch. CNcomment:允许系统任务调度。CNend 279 * 280 * @attention Work pair with hi_task_lock; Call hi_task_lock to disable task switch, then call hi_task_unlock 281 * reenable it. 282 CNcomment:与hi_task_lock配对使用；先调用hi_task_lock禁止任务调度，然后调用hi_task_unlock打开任务调度。CNend 283 * @param None 284 * 285 * @retval None 286 * @par 依赖: 287 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 288 * @see None 289 */ 290 hi_void hi_task_unlock(hi_void); 291 292 /** 293 * @ingroup iot_task 294 * @brief Task sleep.CNcomment:任务睡眠。CNend 295 * 296 * @par 描述: 297 * Task sleep.CNcomment:任务睡眠。CNend 298 * 299 * @attention 300 * @li In the interrupt processing function or in the case of a lock task, the hi_sleep operation fails. 301 CNcomment:在中断处理函数中或者在锁任务的情况下，执行hi_sleep操作会失败。CNend 302 * @li When less than 10 ms, the input parameter value should be replaced by 10 ms. When greater than 10 ms, 303 * the input parameter value should be exactly divided and then rounded-down to the nearest integer. 304 CNcomment:入参小于10ms时，当做10ms处理，Tick=1；大于10ms时，整除向下对齐，Tick = ms/10。CNend 305 * @li This function cannot be used for precise timing and will be woken up after Tick system scheduling. 306 * The actual sleep time is related to the time consumed by the Tick when the function is called. 307 CNcomment:本函数不能用于精确计时，将在Tick个系统调度后唤醒，实际睡眠时间与函数被调用时该Tick已消耗的时间相关。CNend 308 * @param ms [IN] type #hi_u32，sleep time (unit: ms). The precision is 10 ms. 309 CNcomment:睡眠时间（单位：ms），精度为10ms。CNend 310 * 311 * @retval #0 Success 312 * @retval #Other Failure. For details, see hi_errno.h. 313 * @par 依赖: 314 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 315 * @see None 316 */ 317 hi_u32 hi_sleep(hi_u32 ms); 318 319 /** 320 * @ingroup iot_task 321 * @brief Regiseter idle task callback.CNcomment:注册idle任务回调函数。CNend 322 * 323 * @par 描述: 324 * Regiseter idle task callback, if callback is NULL, means cancel registration. 325 CNcomment:注册idle任务回调函数，如果回调函数为空，表示取消注册。CNend 326 * 327 * @attention 328 * @li lowper sleep process handle after callback, callback should not contain complicated 329 operations that affect lowpower process . 330 CNcomment:低功耗睡眠处理在idle回调执行之后，回调函数避免处理复杂操作影响低功耗流程。CNend 331 * @li When less than 10 ms, the input parameter value should be replaced by 10 ms. When greater than 10 ms, 332 * @param cb [IN] type #hi_void_callback, callback in idle task.CNcomment:idle任务中的回调函数。CNend 333 * 334 * @retval #None 335 * @par 依赖: 336 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 337 * @see None 338 */ 339 hi_void hi_task_register_idle_callback(hi_void_callback cb); 340 341 /** 342 * @ingroup iot_task 343 * @brief Wait task excute finish.CNcomment:等待任务执行结束。CNend 344 * 345 * @par 描述: 346 * Wait task excute finish.CNcomment:等待任务执行结束。CNend 347 * 348 * @attention None 349 * @param taskid [IN] type #hi_u32, task id of the task to be waited finish. 350 CNcomment:被等待结束的任务ID。CNend 351 * @param wait_interval [IN] type #hi_u32, interval time of query task status when waiting. at least one tick. 352 CNcomment:等待时查询任务状态的间隔时间，至少间隔1个Tick。CNend 353 * 354 * @retval #None 355 * @par 依赖: 356 * @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend 357 * @see None 358 */ 359 hi_void hi_task_join(hi_u32 taskid, hi_u32 wait_interval); 360 361 #endif 362