1 /** 2 * @file hi_lowpower.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_lp Power consumption management 20 * @ingroup system 21 */ 22 23 #ifndef __HI_LOWPOWER_H__ 24 #define __HI_LOWPOWER_H__ 25 26 #include <hi_types.h> 27 #include <hi_gpio.h> 28 29 /** 30 * @ingroup iot_lp 31 * UDP wakes up source enumeration. 32 */ 33 typedef enum { 34 HI_UDS_GPIO3 = 1 << 0, /**< ultra sleep wakeup source GPIO3.CNcomment:超深睡唤醒源GPIO3 CNend */ 35 HI_UDS_GPIO5 = 1 << 1, /**< ultra sleep wakeup source GPIO5.CNcomment:超深睡唤醒源GPIO5 CNend */ 36 HI_UDS_GPIO7 = 1 << 2, /**< ultra sleep wakeup source GPIO7.CNcomment:超深睡唤醒源GPIO7 CNend */ 37 HI_UDS_GPIO14 = 1 << 3, /**< ultra sleep wakeup source GPIO14.CNcomment:超深睡唤醒源GPIO14 CNend */ 38 } hi_udsleep_src; 39 40 /** 41 * @ingroup iot_lp 42 * Sleep level enumeration. 43 */ 44 typedef enum { 45 HI_NO_SLEEP, /**< no sleep type.CNcomment:不睡模式 CNend */ 46 HI_LIGHT_SLEEP, /**< light sleep type.CNcomment:浅睡模式 CNend */ 47 HI_DEEP_SLEEP, /**< deep sleep type.CNcomment:深睡模式 CNend */ 48 } hi_lpc_type; 49 50 /** 51 * @ingroup hct_lp 52 * 53 * 睡眠模块ID 枚举，每个id占用1个bit，继续扩展时要注意最大为(1 << 31)。 54 */ 55 typedef enum { 56 HI_LPC_ID_DIAG = 1 << 0, /**< diag uart Id.CNcomment:diag模块 Id */ 57 HI_LPC_ID_SHELL = 1 << 1, /**< shell Id.CNcomment:shell模块 Id CNend */ 58 HI_LPC_ID_RSV = 1 << 15, /**< 之前均为内部预留id.CNcomment:内部预留 Id CNend */ 59 HI_LPC_ID_DEMO = 1 << 16, /**< demo Id.CNcomment:低功耗管理id样例，之后为客户预留Id CNend */ 60 }hi_lpc_id; 61 62 /** 63 * @ingroup iot_lp 64 * Low power management structure. 65 */ 66 typedef struct { 67 hi_u32 wakeup_times; /**< wakeup times.CNcomment:唤醒次数统计 CNend */ 68 hi_u32 sleep_threshold_refuse_times; /**< sleep threshold refuse times.CNcomment: 69 可睡时间小于设定门限次数统计 CNend */ 70 hi_u32 sleep_check_refuse_times; /**< sleep check refuse times.CNcomment: 71 入睡投票睡眠失败次数统计 CNend */ 72 hi_u32 sleep_times; /**< sleep times.CNcomment:入睡次数统计 CNend */ 73 hi_u32 sleep_threshold; /**< sleep threshold, unit is ms, only when 74 the system' Remaining idle time is bigger than the threshold, 75 system can enter deep sleep state.CNcomment:深睡眠门限，单位 76 为ms，当系统剩余空闲时间大于该门限时，方可进入深睡 CNend */ 77 hi_u32 dsleep_fail_times; /**< the times of power off fail during deepsleep.CNcomment:深睡下电失败次数统计 CNend */ 78 hi_u8 type; /**< hi_lpc_type type, enable low power management. 79 CNcomment:hi_lp_type类型，低功耗类型 CNend */ 80 hi_u8 evt_sts; /**< wakeup event state, bit0:gpio wkup, bit1:rtc wkup, bit2:sdio wkup, bit4: 81 sta0 wkup, bit5:sta1 wkup, bit6:ap0 wkup.CNcomment:唤醒事件状态，bit0:gpio 唤醒， 82 bit1:rtc 唤醒，bit2:sdio 唤醒，bit4:sta0 唤醒, bit5:sta1 唤醒， 83 bit6:ap0 唤醒。 CNend */ 84 hi_u8 int_sts; /**< wakeup interrupt state, bit0:gpio wkup, bit1:rtc wkup, bit2:sdio wkup, bit4: 85 sta0 wkup, bit5:sta1 wkup, bit6:ap0 wkup.CNcomment:唤醒中断状态，bit0:gpio 唤醒， 86 bit1:rtc 唤醒，bit2:sdio 唤醒，bit4:sta0 唤醒, bit5:sta1 唤醒, 87 bit6:ap0 唤醒 CNend */ 88 hi_u8 last_time_vote_state; /**< last time vote state, 0:no sleep, 1: light sleep, 2: deep sleep. 89 CNcomment:最近一次睡眠状态，0:没有入睡，1:浅睡，2:深睡。 CNend */ 90 hi_u32 timer_ticks; /**< the time ticks is about to expire, unit is 10 ms, if the value is 0xffffffff, there is 91 no timer that is about to expire. 92 CNcomment:定时器即将到期的时间，单位为10ms；如果是0xffffffff，表示没有即将到期的 93 定时器 CNend */ 94 hi_u32 timer_handle; /**< the callback function address of the timer that is about to expire. if the value is 95 0xffffffff, it means that there is no timer that is about to expire. 96 CNcomment:即将到期定时器回调函数的地址，如果是0xffffffff,表示没有即将到期的定时器 CNend */ 97 hi_u32 timer_handle_arg; /**< the parameter of the timer callback function, if the value is 0xffffffff, it means 98 there is no timer to expire.CNcomment:定时器回调函数的参数，如果是0xffffffff, 99 表示没有即将到期的定时器 CNend */ 100 hi_u32 task_ticks; /**< the task ticks is about to expire, unit is 10 ms.CNcomment:任务即将到期的时间， 101 单位为10ms。CNend */ 102 hi_u32 task_id; /**< the task id that is about to expire.CNcomment:即将到期任务的ID。CNend */ 103 hi_u32 sleep_ticks; /**< last sleep time ticks, unit is 10 ms.CNcomment:最近一次睡眠的tick时间， 104 单位为10ms。CNend */ 105 hi_u32 veto_info; /**< veto_info.CNcomment:投票否决睡眠信息，详见hi_lpc_id。CNend */ 106 hi_u16 dsleep_wk_gpio; /**< wakeup gpio for deep sleep.CNcomment:唤醒的GPIO,该值(1<<x)为1表示GPIOx使能。CNend */ 107 hi_u16 reserve; /**< reserve.CNcomment:预留。CNend */ 108 hi_u32 refuse_vote_handle; /**< Address of voting funcfion refusing to vote for sleep.CNcomment: 109 拒绝投睡眠票的投票函数地址。CNend */ 110 } hi_lpc_info; 111 112 /** 113 * @ingroup iot_lp 114 * @brief Low power initialization. 115 * 116 * @par Description: 117 * Initializes power saving management. CNcomment:低功耗初始化CNend 118 * 119 * @attention This is an initialization API and does not support multi-task calling or repeated calling. 120 must call after hi_sal_init. 121 CNcomment:初始化操作是非多任务安全的，并且不支持重复调用。 122 必须在hi_sal_init之后调用。CNend 123 * @param None 124 * 125 * @retval #0 Success. 126 * @retval #Other Failure. For details, see hi_errno.h. 127 * @par Dependency: 128 * @li hi_lowpower.h: Describes power saving management APIs. 129 * @see None 130 */ 131 hi_u32 hi_lpc_init(hi_void); 132 133 /** 134 * @ingroup iot_lp 135 * @brief Set current lowpower type. 136 * 137 * @par Description: 138 * Set current lowpower sleep mode. CNcomment:设置低功耗模式CNend 139 * 140 * @param type [IN] type #hi_lpc_type type. 141 CNcomment:低功耗模式CNend 142 * 143 * @retval #HI_ERR_SUCCESS Success. 144 * @retval #Other Failure. For details, see hi_errno.h. 145 * @par Dependency: 146 * @li hi_lowpower.h: Describes power saving management APIs. 147 * @see None 148 */ 149 hi_u32 hi_lpc_set_type(hi_lpc_type type); 150 151 /** 152 * @ingroup iot_lp 153 * @brief Get current lowpower type. 154 * 155 * @par Description: 156 * Get current lowpower type.CNcomment:获取当前低功耗模式。CNend 157 * 158 * @param None 159 * 160 * @retval #hi_lpc_type current lowpower type. 161 * @par Dependency: 162 * @li hi_lowpower.h: Describes power saving management APIs. 163 * @see None 164 */ 165 hi_lpc_type hi_lpc_get_type(hi_void); 166 167 /** 168 * @ingroup iot_lp 169 * @brief Register check callback fucntion. 170 * 171 * @par Description: 172 * Register check callback function.CNComment:注册检查是否允许睡眠接口CNend 173 * 174 * @param check_allowed [IN] type #hi_u32_void_callback 175 * If the return value is 0 means to disable sleep,others means enable. 176 * CNcomment:返回值为0禁止睡眠，其他值为允许.CNend 177 * 178 * @retval #hi_pvoid Hanlder.CNcomment:句柄CNend 179 * @par Dependency: 180 * @li hi_lowpower.h: Describes power saving management APIs. 181 * @see hi_lowpower_unregister_vote 182 */ 183 hi_pvoid hi_lpc_register_check_handler(hi_u32_void_callback check_allowed); 184 185 /** 186 * @ingroup iot_lp 187 * @brief Cancel registation of check callback fucntion. 188 * 189 * @par Description: 190 * Cancel registation of check callback fucntion.CNcomment:取消检查接口注册CNend 191 * 192 * @param handle [IN] type #hi_pvoid Low power handler.CNcomment:低功耗句柄CNend 193 * 194 * @retval #0 Success. 195 * @retval #Other Failure. For details, see hi_errno.h. 196 * @par Dependency: 197 * @li hi_lowpower.h: Describes power saving management APIs. 198 * @see hi_lowpower_register_vote 199 */ 200 hi_u32 hi_lpc_unregister_check_handler(hi_pvoid handle); 201 202 /** 203 * @ingroup iot_lp 204 * @brief Add low power sleep veto. 205 * 206 * @par Description: 207 * Add low power sleep veto. CNcomment:禁止进入睡眠模式CNend 208 * 209 * @param id [IN] type #hi_lpc_id module id. 210 CNcomment:模块idCNend 211 * 212 * @retval #HI_ERR_SUCCESS Success. 213 * @retval #Other Failure. For details, see hi_errno.h. 214 * @par Dependency: 215 * @li hi_lowpower.h: Describes power saving management APIs. 216 * @see None 217 */ 218 hi_u32 hi_lpc_add_veto(hi_lpc_id id); 219 220 /** 221 * @ingroup iot_lp 222 * @brief Remove low power sleep veto. 223 * 224 * @par Description: 225 * Set low power sleep mode. CNcomment:解除对应id的禁止进入睡眠模式状态CNend 226 * 227 * @param id [IN] type #hi_lpc_id module id. 228 CNcomment:模块idCNend 229 * 230 * @retval #HI_ERR_SUCCESS Success. 231 * @retval #Other Failure. For details, see hi_errno.h. 232 * @par Dependency: 233 * @li hi_lowpower.h: Describes power saving management APIs. 234 * @see None 235 */ 236 hi_u32 hi_lpc_remove_veto(hi_lpc_id id); 237 238 /** 239 * @ingroup iot_lp 240 * @brief Statistics related to power saving. 241 * 242 * @par Description: 243 * Statistics related to power saving.CNcomment:低功耗相关维测统计CNend 244 * 245 * @param None 246 * 247 * @retval hi_lp_stat Pointer to the status sturcture. CNcomment:统计量指针CNend 248 * @par Dependency: 249 * @li hi_lowpower.h: Describes power saving management APIs. 250 * @see None 251 */ 252 hi_lpc_info* hi_lpc_get_info(hi_void); 253 254 /** 255 * @ingroup iot_lp 256 * @brief enable ultra deep sleep wakeup source. 257 * 258 * @par Description: 259 * enable ultra deep sleep wakeup source to low power module.CNcomment:使能低功耗超深睡唤醒源CNend 260 * 261 * @param src [IN] type #hi_udsleep_src Type of ultra deep sleep wakeup source enumeration. 262 CNcomment:超深睡唤醒源CNend 263 * 264 * @retval #0 Success. 265 * @retval #Other Failure. For details, see hi_errno.h. 266 * 267 * @par Dependency: 268 * @li hi_lowpower.h: Describes power saving management APIs. 269 * @see None 270 */ 271 hi_u32 hi_lpc_enable_udsleep(hi_udsleep_src src); 272 273 /** 274 * @ingroup iot_lp 275 * @brief get ultra deep sleep wakeup source. 276 * 277 * @par Description: 278 * get the wakeup source of ultra deep sleep.CNcomment:获取低功耗超深睡唤醒的触发源CNend 279 * 280 * @param src [OUT] type #hi_u16 * Type of ultra deep sleep wakeup source enumeration. 281 CNcomment:超深睡唤醒源CNend 282 * 283 * @retval #0 Success. 284 * @retval #Other Failure. For details, see hi_errno.h. 285 * 286 * @par Dependency: 287 * @li hi_lowpower.h: Describes power saving management APIs. 288 * @see None 289 */ 290 hi_u32 hi_lpc_get_udsleep_wakeup_src(hi_u16 *src); 291 292 /** 293 * @ingroup iot_lp 294 * @brief Register hardware callback func of light_sleep or deep_sleep. 295 * 296 * @par Description: 297 * Register hardware callback func of light_sleep or deep_sleep.CNcomment:设置睡眠阶段硬件相关回调函数CNend 298 * 299 * @attention The save function is called after voting success and befor sleep, and the restore function is called 300 * when waking up. 301 CNcomment:prepare函数在芯片实际休眠前执行，resume函数在睡醒时执行。CNend 302 * @param prepare [IN] type #hi_u32_void_callback Callback func of sleep.CNcomment:睡眠准备阶段回调函数CNend 303 * @param resume [IN] type #hi_u32_void_callback Callback func of wake up.CNcomment:唤醒阶段回调函数CNend 304 * 305 * @retval #0 Success. 306 * @retval #Other Failure. For details, see hi_errno.h. 307 * 308 * @par Dependency: 309 * @li hi_lowpower.h: Describes power saving management APIs. 310 * @see None 311 */ 312 hi_u32 hi_lpc_register_hw_handler(hi_u32_void_callback prepare, hi_u32_void_callback resume); 313 314 /** 315 * @ingroup iot_lp 316 * @brief Register software callback func of light_sleep or deep_sleep. 317 * 318 * @par Description: 319 * Register software callback func of light_sleep or deep_sleep.CNcomment:设置睡眠阶段软件相关回调函数CNend 320 * 321 * @attention The save function is called before voting for sleep, and the restore function is called when waking up or 322 * vote fail. 323 CNcomment:prepare函数在系统判断是否可休眠前执行，resume函数在睡醒时或投票失败后执行。CNend 324 * @param prepare [IN] type #hi_u32_void_callback Callback func of sleep.CNcomment:睡眠准备阶段回调函数CNend 325 * @param resume [IN] type #hi_u32_void_callback Callback func of wake up.CNcomment:唤醒阶段回调函数CNend 326 * 327 * @retval #0 Success. 328 * @retval #Other Failure. For details, see hi_errno.h. 329 * 330 * @par Dependency: 331 * @li hi_lowpower.h: Describes power saving management APIs. 332 * @see None 333 */ 334 hi_u32 hi_lpc_register_sw_handler(hi_u32_void_callback prepare, hi_u32_void_callback resume); 335 336 /** 337 * @ingroup iot_lp 338 * @brief Register callback func of peripheral init entry. 339 * 340 * @par Description: 341 * Register callback func of peripheral init entry.CNcomment:设置深睡唤醒时入口函数，一般用作外设初始化CNend 342 * 343 * @param handler [IN] type #hi_void_callback_f Callback func of wake up.CNcomment:唤醒回调函数CNend 344 * 345 * @retval #0 Success. 346 * @retval #Other Failure. For details, see hi_errno.h. 347 * 348 * @par Dependency: 349 * @li hi_lowpower.h: Describes power saving management APIs. 350 * @see None 351 */ 352 hi_u32 hi_lpc_register_wakeup_entry(hi_void_callback_f handler); 353 354 /** 355 * @ingroup iot_lp 356 * @brief Config deep sleep gpio wakeup IO. 357 * 358 * @par Description: 359 * Config deep sleep wakeup IO.CNcomment:深睡眠唤醒IO设置CNend 360 * 361 * @param id [IN] type #hi_gpio_idx Wake up source IO.CNcomment:唤醒IOCNend 362 * @param enable [IN] type #hi_bool whether enable the source IO.CNcomment:唤醒IOCNend 363 * 364 * @retval #0 Success. 365 * @retval #Other Failure. For details, see hi_errno.h. 366 * 367 * @par Dependency: 368 * @li hi_lowpower.h: Describes power saving management APIs. 369 * @see None 370 */ 371 hi_u32 hi_lpc_config_dsleep_wakeup_io(hi_gpio_idx id, hi_bool enable); 372 373 374 #endif /* __HI_LOWPOWER_H__ */ 375