1/**
2 * @file hi_timer.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_systimer System Timer
20 * @ingroup osa
21 */
22#ifndef __INTERFACE_ROM_HI_TIMER_H__
23#define __INTERFACE_ROM_HI_TIMER_H__
24#include <hi_types_base.h>
25
26
27/**
28 * @ingroup iot_systimer
29 *
30 * Specifies the type of the timer to be created.CNcomment:用于设置所创建的定时器类型。CNend
31 */
32typedef enum {
33    HI_TIMER_TYPE_ONCE,     /**< Single-period timer.CNcomment:表示单次定时器 CNend */
34    HI_TIMER_TYPE_PERIOD,   /**< Periodic timer.CNcomment:表示周期定时器 CNend */
35    HI_TIMER_TYPE_MAX       /**< Maximum value, which cannot be used.CNcomment:最大值，不可使用 CNend */
36} hi_timer_type;
37
38/**
39* @ingroup  iot_systimer
40* @brief  Defines the type of the timer callback function.CNcomment:定义定时器回调函数的类型。CNend
41*
42* @par 描述：
43*           Defines the type of the timer callback function.CNcomment:定义定时器回调函数的类型。CNend
44*
45* @attention None
46* @param  data [IN] type #hi_u32，callback input parameter.CNcomment:回调入参。CNend
47*
48* @retval None
49* @par 依赖:
50*            @li hi_timer.h：Describes the timer APIs.CNcomment:文件用于描述定时器相关接口。CNend
51* @see hi_timer_start | hi_timer_stop
52*/
53typedef hi_void (*hi_timer_callback_f)(hi_u32 data);
54
55/**
56* @ingroup  iot_systimer
57* @brief  Creates the system timer.CNcomment:获取定时器句柄。CNend
58*
59* @par 描述:
60*           Creates the system timer.CNcomment:获取高精定时器句柄。CNend
61*
62* @attention None
63* @param  timer_handle [OUT] type #hi_u32*，handle.CNcomment:获取到的句柄。CNend
64*
65* @retval #0           Success.
66* @retval #Other       Failure. For details, see hi_errno.h.
67*
68* @par 依赖:
69*          @li hi_timer.h：Describes the timer APIs.CNcomment:文件用于描述定时器相关接口。CNend
70* @see  hi_timer_delete。
71*/
72hi_u32 hi_timer_create(hi_u32 *timer_handle);
73
74/**
75* @ingroup  iot_systimer
76* @brief  Starts the system timer.CNcomment:启动系统定时器。CNend
77*
78* @par 描述:
79*            This API is used in the following scenarios:CNcomment:本API接口使用分为以下几个场景：CNend
80*            @li If no timer is created, create and start a timer.
81CNcomment:如果未启动定时器，则直接启动。CNend
82*            @li If the timer expires and is called again, start the timer directly.
83CNcomment:如果该定时器到期后调用，则直接启动定时器。CNend
84*            @li If the timer does not expire, stop and restart the timer.
85CNcomment:如果定时器没有到期，则停止该定时器，重新启动定时器。CNend
86*
87* @attention This timer callback function is executed in the interrupt context. Therefore, the callback function should
88*            be as simple as possible and the functions such as sleep and wait semaphores that trigger scheduling
89*            cannot be used.CNcomment:本定时器回调函数执行于中断上下文，回调函数尽量简单，不能使用睡眠、
90等待信号量等引起调度的函数。CNend
91*
92* @param  timer_handle  [IN]  type #hi_u32，handle.CNcomment:句柄。CNend
93* @param  type          [IN]   type #hi_timer_type，timer type.CNcomment:定时器类型。CNend
94* @param  expire        [IN]   type #hi_u32，timeout period of the timer (unit: ms). If this parameter is set to 0,
95*                       the default value is 10 ms.CNcomment:定时器超时时间（单位：ms）。配置为0时，默认为10ms。CNend
96* @param  timer_func    [IN]   type #timer_proc_func，timer callback function.CNcomment:定时器回调函数。CNend
97* @param  data          [IN]   type #hi_u32，callback input parameter.CNcomment:回调函数传参。CNend
98*
99* @retval #0           Success.
100* @retval #Other       Failure. For details, see hi_errno.h.
101*
102* @par 依赖:
103*          @li hi_timer.h：Describes the timer APIs.CNcomment:文件用于描述定时器相关接口。CNend
104* @see hi_timer_stop
105*/
106hi_u32 hi_timer_start(hi_u32 timer_handle, hi_timer_type type, hi_u32 expire,
107                      hi_timer_callback_f timer_func, hi_u32 data);
108
109/**
110* @ingroup  iot_systimer
111* @brief  Stops the system timer.CNcomment:停止系统定时器。CNend
112*
113* @par 描述:
114*          Stops the system timer.CNcomment:停止系统定时器。CNend
115*
116* @attention This API only stops the timer and does not delete the timer.CNcomment:本接口仅停止定时器，
117并不删除该定时器。CNend
118* @param  timer_handle [IN] type #hi_u32，handle.CNcomment:句柄。CNend
119*
120* @retval #0           Success.
121* @retval #Other       Failure. For details, see hi_errno.h.
122*
123* @par 依赖:
124*          @li hi_timer.h：Describes the timer APIs.CNcomment:文件用于描述定时器相关接口。CNend
125* @see hi_timer_start | hi_timer_delete
126*/
127hi_u32 hi_timer_stop(hi_u32 timer_handle);
128
129/**
130* @ingroup  iot_systimer
131* @brief  Deletes the timer.CNcomment:删除定时器。CNend
132*
133* @par 描述:
134*           Deletes the timer.CNcomment:删除定时器。CNend
135*
136* @attention
137*            @li If the timer does not expire, stop the timer before deleting it.
138CNcomment:如果定时器未到期，则先停止该定时器再删除。CNend
139*
140* @param  timer_handle [IN] type #hi_u32，handle.CNcomment:句柄。CNend
141*
142* @retval #0           Success.
143* @retval #Other       Failure. For details, see hi_errno.h.
144*
145* @par 依赖:
146*          @li hi_timer.h：Describes the timer APIs.CNcomment:文件用于描述定时器相关接口。CNend
147* @see hi_timer_start | hi_timer_stop
148*/
149hi_u32 hi_timer_delete(hi_u32 timer_handle);
150
151#endif
152