1/**
2* @file hi_time.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* Description: time APIs.CNcomment:时间接口描述CNend
18* @li System time of the hi_get_tick, hi_get_tick64, hi_get_milli_seconds, and hi_get_seconds operations. The system
19*     time is calculated starting from kernel startup and cannot be modified through APIs.
20CNcomment:hi_get_tick, hi_get_tick64,hi_get_milli_seconds, hi_get_seconds操作的系统时间，
21系统时间从kernel启动开始计时，不可以通过接口进行修改。CNend
22* @li The hi_get_real_time and hi_set_real_time APIs are about real-time operations. The real time is calculated
23*     starting from kernel startup and can be modified by hi_set_real_time.CNcomment:hi_get_real_time，
24hi_set_real_time操作的是实时时间，实时时间从kernel启动开始计时，可以通过hi_set_real_time进行修改。CNend   \n
25* Author: Hisilicon   \n
26* Create: 2019-05-29
27*/
28
29/**
30 * @defgroup iot_time System Clock
31 * @ingroup osa
32 */
33#ifndef __HI_TIME_H__
34#define __HI_TIME_H__
35#include <hi_types_base.h>
36
37/**
38* @ingroup  iot_time
39* @brief  Delay, in microseconds.CNcomment:延时，微秒级。CNend
40*
41* @par 描述:
42*           Delay operation implemented by software based on the system clock, blocking the CPU.
43CNcomment:延时操作，阻塞CPU。CNend
44*
45* @attention This API cannot be used for a long time in an interrupt.CNcomment:不允许中断中使用。CNend
46*
47* @param  us                [IN] type #hi_u32，delay period (unit: microsecond).
48CNcomment:延时时间（单位：μs）。CNend
49*
50* @retval  None
51* @par 依赖:
52*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
53* @see  None
54*/
55hi_void hi_udelay(hi_u32 us);
56
57/**
58* @ingroup  iot_time
59* @brief  Obtains the tick value of the system (32-bit).CNcomment:获取系统tick值（32bit）。CNend
60*
61* @par 描述:
62*           Obtains the tick value of the system (32-bit).CNcomment:获取系统tick值（32bit）。CNend
63*
64* @attention None
65* @param None
66*
67* @retval #hi_u32 Tick value of the system.CNcomment:系统tick值。CNend
68* @par 依赖:
69*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
70*/
71hi_u32 hi_get_tick(hi_void);
72
73/**
74* @ingroup  iot_time
75* @brief  Obtains the tick value of the system (64-bit).CNcomment:获取系统tick值（64bit）。CNend
76*
77* @par 描述:
78*           Obtains the tick value of the system (64-bit).CNcomment:获取系统tick值（64bit）。CNend
79*
80* @attention The hi_mdm_time.h file must be included where the API is called. Otherwise, the API is considered not
81*            declared, and the tick value is returned as an int type, resulting in a truncation error.
82CNcomment:该接口调用处必须包含头文件hi_time.h，否则按照未声明接口处理，会将tick值当做int类型返回，产生截断错误。CNend
83* @param None
84*
85* @retval  #hi_u64 Tick value of the system.CNcomment:系统tick值。CNend
86* @par 依赖:
87*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
88*/
89hi_u64 hi_get_tick64(hi_void);
90
91/**
92* @ingroup  iot_time
93* @brief  Obtains the system time (unit: ms).CNcomment:获取系统时间（单位：ms）。CNend
94*
95* @par 描述:
96*           Obtains the system time (unit: ms).CNcomment:获取系统时间（单位：ms）。CNend
97*
98* @attention None
99* @param None
100*
101* @retval #hi_u32 System time.CNcomment:系统时间。CNend
102* @par 依赖:
103*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
104*/
105hi_u32 hi_get_milli_seconds(hi_void);
106
107/**
108* @ingroup  iot_time
109* @brief  Obtains the system time (unit: s).CNcomment:获取系统时间（单位：s）。CNend
110*
111* @par 描述:
112*           Obtains the system time (unit: s).CNcomment:获取系统时间（单位：s）。CNend
113*
114* @attention None
115* @param None
116*
117* @retval #hi_u32 System time.CNcomment:系统时间。CNend
118* @retval #HI_ERR_FAILURE failed to be obtained. CNcomment:获取时间失败。CNend
119* @par 依赖:
120*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
121*/
122hi_u32 hi_get_seconds(hi_void);
123
124/**
125* @ingroup  iot_time
126* @brief  Obtains the system time (unit: us).CNcomment:获取系统时间（单位：us）。CNend
127*
128* @par 描述:
129*           Obtains the system time (unit: us).CNcomment:获取系统时间（单位：us）。CNend
130*
131* @attention None
132* @param None
133*
134* @retval #hi_u64 System time.CNcomment:系统时间。CNend
135* @retval #HI_ERR_FAILURE failed to be obtained. CNcomment:获取时间失败。CNend
136* @par 依赖:
137*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
138*/
139hi_u64 hi_get_us(hi_void);
140
141/**
142* @ingroup  iot_time
143* @brief  Obtains the real time of the system (unit: s).CNcomment:获取系统实时时间（单位：s）。CNend
144*
145* @par 描述:
146*           Obtains the real time of the system (unit: s).CNcomment:获取系统实时时间（单位：s）。CNend
147*
148* @attention None
149* @param None
150*
151* @retval #hi_u32 Real time of the system.CNcomment: 系统实时时间。CNend
152* @retval #HI_ERR_FAILURE failed to be obtained. CNcomment:获取时间失败。CNend
153* @par 依赖:
154*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
155*/
156hi_u32 hi_get_real_time(hi_void);
157
158/**
159* @ingroup  iot_time
160* @brief  Sets the real time of the system.CNcomment:设置系统实时时间。CNend
161*
162* @par 描述:
163*           Sets the real time of the system.CNcomment:设置系统实时时间。CNend
164*
165* @attention None
166* @param  seconds            [IN] type #hi_u32，set the real time of the system to this value.
167CNcomment:将系统实时时间设置为该值。CNend
168*
169* @retval #HI_ERR_SUCCESS    Success.
170* @retval #HI_ERR_FAILURE    Failure.
171* @par 依赖:
172*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
173*/
174hi_u32 hi_set_real_time(hi_u32 seconds);
175
176extern hi_void_callback g_tick_callback;
177
178/**
179* @ingroup  iot_time
180* @brief Regiseter system tick callback.CNcomment:注册tick 中断响应回调函数。CNend
181*
182* @par 描述:
183*          Regiseter system tick callback, if callback is NULL, means cancel registration.
184CNcomment:注册tick中断回调函数，如果回调函数为空，表示取消注册。CNend
185*
186* @attention
187*           @li cb should not excute in FLASH, must excute in RAM or ROM. u can specify BSP_RAM_TEXT_SECTION before func
188to set func excute in RAM.
189CNcomment:回调函数不能在FLASH中运行，必须放置在RAM或ROM中，可以通过在
190函数名前添加BSP_RAM_TEXT_SECTION 冠头指定函数在RAM中运行。CNend
191* @param  cb      [IN] type #hi_void_callback, callback in tick interrupt.CNcomment:tick中断的回调函数。CNend
192*
193* @retval #None
194* @par 依赖:
195*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
196*/
197hi_void hi_tick_register_callback(hi_void_callback cb);
198
199/**
200* @ingroup  iot_time
201* @brief Convert milliseconds to ticks CNcomment:将毫秒转换为ticks。CNend
202*
203* @par 描述:
204*          Convert milliseconds to ticks,ms is greater than 10ms, ticks = ms / 10,
205*          otherwise see parameter include0 description.
206CNcomment: 将milliseconds换算为ticks,ms大于10ms,ticks=ms/10。CNend
207*
208* @attention None
209* @param  ms            [IN] type #hi_u32, milliseconds.
210* @param  include0      [IN] type #hi_bool, ms is 0, if include0 is HI_TRUE, return 0 tick,otherwise return 1 tick.
211CNcomment:入参ms为0时，如果include0为HI_TRUE，换算结果为0；否则换算结果为1。CNend
212*
213* @retval #hi_u32 ticks time.CNcomment:ticks时间数 CNend
214* @par 依赖:
215*            @li hi_time.h：Describes system time APIs.CNcomment:文件包含系统时间相关接口。CNend
216*/
217hi_u32 hi_ms2systick (hi_u32 ms, hi_bool include0);
218
219#endif
220