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