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
34typedef 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
57typedef 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*/
104hi_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*/
128hi_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.
139CNcomment:挂起任务的时候若为当前任务且已锁任务，则不能被挂起。CNend
140*          @li The idle task and Swt_Task cannot be suspended.
141CNcomment:idle任务及Swt_Task任务不能被挂起。CNend
142*          @li The task cannot be blocked or suspended in the lock task status.
143CNcomment:在锁任务调度状态下，禁止任务阻塞。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*/
153hi_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*/
171hi_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*/
191hi_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.
202CNcomment:仅可配置用户自己创建的任务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.
206CNcomment:设置用户优先级有可能影响任务调度，用户需要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*/
217hi_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*/
236hi_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.
249CNcomment:任务ID，失败返回#HI_INVALID_TASK_ID。CNend
250* @par 依赖:
251*           @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend
252* @see  None
253*/
254hi_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*/
271hi_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.
282CNcomment:与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*/
290hi_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.
301CNcomment:在中断处理函数中或者在锁任务的情况下，执行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.
304CNcomment:入参小于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.
307CNcomment:本函数不能用于精确计时，将在Tick个系统调度后唤醒，实际睡眠时间与函数被调用时该Tick已消耗的时间相关。CNend
308* @param  ms      [IN] type #hi_u32，sleep time (unit: ms). The precision is 10 ms.
309CNcomment:睡眠时间（单位：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*/
317hi_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.
325CNcomment:注册idle任务回调函数，如果回调函数为空，表示取消注册。CNend
326*
327* @attention
328*           @li lowper sleep process handle after callback, callback should not contain complicated
329operations that affect lowpower process .
330CNcomment:低功耗睡眠处理在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*/
339hi_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.
350CNcomment:被等待结束的任务ID。CNend
351* @param  wait_interval  [IN] type #hi_u32, interval time of query task status when waiting. at least one tick.
352CNcomment:等待时查询任务状态的间隔时间，至少间隔1个Tick。CNend
353*
354* @retval #None
355* @par 依赖:
356*           @li hi_task.h：Describes the task APIs.CNcomment:文件用于描述任务相关接口。CNend
357* @see  None
358*/
359hi_void hi_task_join(hi_u32 taskid, hi_u32 wait_interval);
360
361#endif
362