/* ----------------------------------------------------------------------------
 * Copyright (c) Huawei Technologies Co., Ltd. 2020-2020. All rights reserved.
 * Description: Low-power Framework.
 * Author: Huawei LiteOS Team
 * Create: 2020-09-19
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 1. Redistributions of source code must retain the above copyright notice, this list of
 * conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
 * of conditions and the following disclaimer in the documentation and/or other materials
 * provided with the distribution.
 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
 * to endorse or promote products derived from this software without specific prior written
 * permission.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * --------------------------------------------------------------------------- */

/* *
 * @defgroup los_lowpower lowpower_framework
 * @ingroup kernel
 */

#ifndef _LOS_LOWPOWER_H
#define _LOS_LOWPOWER_H

#include "los_base.h"
#include "los_sys.h"
#include "los_err.h"

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif /* __cplusplus */
#endif /* __cplusplus */

/**
 * @ingroup  los_lowpower
 *
 * Intermit modes
 */
typedef enum LOS_INTERMIT_MODE {
    LOS_INTERMIT_NONE = 0,
    LOS_INTERMIT_LIGHT_SLEEP, /**< Light sleep mode */
    LOS_INTERMIT_DEEP_SLEEP,  /**< Deep sleep mode */
    LOS_INTERMIT_STANDBY,     /**< Standby mode */
    LOS_INTERMIT_SHUTDOWN,    /**< Shutdown mode */
    LOS_INTERMIT_MAX,
} LosIntermitMode;
/*这是一个枚举类型 LOS_INTERMIT_MODE 的定义，包含了几个枚举常量：

LOS_INTERMIT_NONE：表示没有中断模式
LOS_INTERMIT_LIGHT_SLEEP：表示轻度睡眠模式
LOS_INTERMIT_DEEP_SLEEP：表示深度睡眠模式
LOS_INTERMIT_STANDBY：表示待机模式
LOS_INTERMIT_SHUTDOWN：表示关机模式
LOS_INTERMIT_MAX：该枚举类型的最大值，用于辅助枚举类型的范围检查*/
/**
 * @ingroup  los_lowpower
 *
 * System main frequency modes
 */
typedef enum LOS_FREQ_MODE {
    LOS_SYS_FREQ_SUPER = 0, /**< Super high freq */
    LOS_SYS_FREQ_HIGH,      /**< High freq */
    LOS_SYS_FREQ_NORMAL,    /**< Normal freq */
    LOS_SYS_FREQ_LOW,       /**< Low freq */
    LOS_SYS_FREQ_MAX,
} LosFreqMode;
/*这是另一个枚举类型 LOS_FREQ_MODE 的定义，包含了几个枚举常量：

LOS_SYS_FREQ_SUPER：表示超高频模式
LOS_SYS_FREQ_HIGH：表示高频模式
LOS_SYS_FREQ_NORMAL：表示正常频率模式
LOS_SYS_FREQ_LOW：表示低频模式
LOS_SYS_FREQ_MAX：该枚举类型的最大值，用于辅助枚举类型的范围检查*/
typedef UINT32 (*LowpowerExternalVoterHandle)(VOID);

STATIC INLINE BOOL FreqHigher(LosFreqMode freq1, LosFreqMode freq2)
{
    return freq1 < freq2;
}

/**
 * @ingroup los_lowpower
 *
 * Define the structure of the power manager operations.
 */
typedef struct {
    VOID (*process)(VOID);                   /**< Power manager framework entry interface */
    VOID (*wakeupFromReset)(VOID);           /**< Recovery interface used to wakeup from image */
    VOID (*resumeFromInterrupt)(UINT32);     /**< Recovery interface used to wakeup from interrupt */
    VOID (*changeFreq)(LosFreqMode);         /**< System frequency tuning interface, the param is LosFreqMode */
    VOID (*deepSleepVoteBegin)(VOID);        /**< Deep sleep vote mark interface */
    VOID (*deepSleepVoteEnd)(VOID);          /**< Deep sleep vote erase interface */
    VOID (*deepSleepVoteDelay)(UINT32 tick); /**< Deep sleep vote delay interface, the param is the delayed ticks */
    VOID (*registerExternalVoter)(UINT32 (*handler)(VOID));  /**< External voter registration interface */
    UINT32 (*getDeepSleepVoteCount)(VOID);   /**< Get deep sleep vote count interface */
    UINT32 (*getSleepMode)(VOID);            /**< Get sleep mode interface, the retval type is LosIntermitMode */
    VOID (*setSleepMode)(UINT32 mode);       /**< Set sleep mode interface, the param type is LosIntermitMode */
} PowerMgrOps;
/*这是一个结构体类型 PowerMgrOps 的定义，包含了多个函数指针成员：

process：电源管理框架的入口接口
wakeupFromReset：从镜像中唤醒的恢复接口
resumeFromInterrupt：从中断中唤醒的恢复接口
changeFreq：系统频率调节接口，参数为 LosFreqMode
deepSleepVoteBegin：深度睡眠投票标记接口
deepSleepVoteEnd：深度睡眠投票取消接口
deepSleepVoteDelay：深度睡眠投票延迟接口，参数为延迟的时钟周期数
registerExternalVoter：注册外部投票者接口，参数为一个函数指针，返回值为 UINT32
getDeepSleepVoteCount：获取深度睡眠投票计数接口，返回 UINT32
getSleepMode：获取睡眠模式接口，返回值类型为 LosIntermitMode
setSleepMode：设置睡眠模式接口，参数类型为 UINT32，表示 LosIntermitMode*/
/**
 * @ingroup  los_lowpower
 * @brief System main frequency tuning.
 *
 * @par Description:
 * This API is used to tune the system main frequency.
 *
 * @attention None.
 *
 * @param  freq [IN] The system frequency, corresponding to LosFreqMode.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_PowerMgrChangeFreq(LosFreqMode freq);
/*这是一个外部声明（extern）的函数 LOS_PowerMgrChangeFreq，
它接受一个 LosFreqMode 类型的参数 freq，用于改变系统的工作频率。
根据函数名和参数类型来看，这个函数很可能是用于在系统中切换不同的工作频率模式。*/
/**
 * @ingroup  los_lowpower
 * @brief Vote to enter deep sleep.
 *
 * @par Description:
 * This API is used to mark the deep sleep vote. Called when the current state is idle.
 *
 * @attention None.
 *
 * @param  None.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_PowerMgrDeepSleepVoteBegin(VOID);

/**
 * @ingroup  los_lowpower
 * @brief Erase the deep sleep vote.
 *
 * @par Description:
 * This API is used to erase the deep sleep vote. Called when the current state is busy.
 *
 * @attention None.
 *
 * @param  None.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_PowerMgrDeepSleepVoteEnd(VOID);
/*这是一个外部声明（extern）的函数 LOS_PowerMgrDeepSleepVoteEnd，它没有任何参数，返回类型为 VOID。根据函数名来看，
这个函数很可能用于结束深度睡眠投票，即取消之前进行的深度睡眠投票。*/
/**
 * @ingroup  los_lowpower
 * @brief Sleep delay vote.
 *
 * @par Description:
 * This API is used to delay sleep vote. Called when the current state busy, but can enter sleep later.
 *
 * @attention None.
 *
 * @param  tick [IN] The sleeptime.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_PowerMgrSleepDelay(UINT32 tick);
/*这是一个外部声明（extern）的函数 LOS_PowerMgrSleepDelay，它接受一个 UINT32 类型的参数 tick，
用于在系统中设置睡眠延迟，即指定一定的时钟周期数作为睡眠延迟。*/
/**
 * @ingroup  los_lowpower
 * @brief Register the external voter.
 *
 * @par Description:
 * This API is used to register the external voter, provided for developers with special needs.
 *
 * @attention None.
 *
 * @param  UINT32 (*)(VOID) [IN] The external voter.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_PowerMgrRegisterExtVoter(UINT32 (*)(VOID));
/*这是一个外部声明（extern）的函数 LOS_PowerMgrRegisterExtVoter，
它接受一个函数指针作为参数，该函数指针指向一个不接受任何参数并返回 UINT32 类型的函数。根据函数名来看，这个函数很可能用于注册外部投票者
，即将提供的函数指针注册为外部投票者的处理函数。*/
/**
 * @ingroup  los_lowpower
 * @brief Get the sleep mode.
 *
 * @par Description:
 * This API is used to get sleep mode. Developers can set different corresponding modes.
 * according to the actual scene, then perform follow-up operations.
 *
 * @attention None.
 *
 * @param  None.
 *
 * @retval #UINT32 Sleep mode, corresponding to LosIntermitMode.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern UINT32 LOS_PowerMgrGetSleepMode(VOID);

/**
 * @ingroup  los_lowpower
 * @brief Get the deep sleep vote count.
 *
 * @par Description:
 * This API is used to get the deep sleep vote count.
 *
 * @attention None.
 *
 * @param  None.
 *
 * @retval #UINT32 Deep sleep vote count.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern UINT32 LOS_PowerMgrGetDeepSleepVoteCount(VOID);

/**
 * @ingroup  los_lowpower
 * @brief Register power manager operations.
 *
 *
 * @par Description:
 * This API is used to register power manager operations or customized power manager by developers.
 *
 * @attention None.
 *
 * @param  pmOps [IN] The power manager operations.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_LowpowerInit(const PowerMgrOps *pmOps);
/*这是一个外部声明（extern）的函数 LOS_LowpowerInit，
它接受一个 const PowerMgrOps * 类型的指针参数 pmOps，用于初始化低功耗模式下的系统。根据函数名来看，这个函数很可能是用于在系统启动时初始化与低功耗相关的操作和参数，
以便后续能够进入低功耗状态并正确恢复系统。*/
/**
 * @ingroup los_lowpower
 * @brief Define the lowpower framework process function type.
 *
 * @par Description:
 * This API is used to define the lowpower framework entry function type.
 *
 * @attention None.
 *
 * @param None.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
typedef VOID (*LowPowerHookFn)(VOID);
/*这是一个类型定义语句，定义了一个名为 LowPowerHookFn 的函数指针类型。
该函数指针类型指向一个不接受任何参数并返回 VOID 的函数。
这种类型的函数指针通常用于注册低功耗模式下的钩子函数，
以便在进入或退出低功耗模式时执行特定的操作*/
/**
 * @ingroup  los_lowpower
 * @brief Register a hook to enter lowpower framework process.
 *
 * @par Description:
 * This API is used to register lowpower framework entry function.
 *
 * @attention None.
 *
 * @param  hook [IN] The lowpower framework hook.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_LowpowerHookReg(LowPowerHookFn hook);
/*这是一个外部声明（extern）的函数 LOS_LowpowerHookReg，
它接受一个 LowPowerHookFn 类型的参数 hook，用于注册低功耗模式下的钩子函数。
根据函数名来看，这个函数很可能用于在系统中注册低功耗模式下的钩子函数，
以便在进入或退出低功耗模式时执行特定的操作。*/
/**
 * @ingroup los_lowpower
 * @brief Define the lowpower framework wakup function type.
 *
 * @par Description:
 * This API is used to define the lowpower framework wakup function type.
 *
 * @attention None.
 *
 * @param  hwiNum [IN] The interrupt number.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
typedef VOID (*IntWakeupHookFn)(HWI_HANDLE_T hwiNum);
/*这是一个类型定义语句，定义了一个名为 IntWakeupHookFn 的函数指针类型。
该函数指针类型指向一个接受 HWI_HANDLE_T 类型参数并返回 VOID 的函数。
这种类型的函数指针通常用于注册中断唤醒的钩子函数，以便在特定中断唤醒事件发生时执行特定的操作。
*/
/**
 * @ingroup  los_lowpower
 * @brief Register a hook to wakeup from interrupt.
 *
 * @par Description:
 * This API is used to register a recovery function after wakeup from interrupt
 *
 * @attention None.
 *
 * @param  hook [IN] The lowpower wakeup hook.
 *
 * @retval None.
 * @par Dependency:
 * <ul><li>los_lowpower.h: the header file that contains the API declaration.</li></ul>
 * @see None.
 * @since Huawei LiteOS V200R005C10
 */
extern VOID LOS_IntWakeupHookReg(IntWakeupHookFn hook);
/*这是一个外部声明（extern）的函数 LOS_IntWakeupHookReg，
它接受一个 IntWakeupHookFn 类型的参数 hook，用于注册中断唤醒的钩子函数。
根据函数名来看，这个函数很可能用于在系统中注册中断唤醒的钩子函数，
以便在特定中断唤醒事件发生时执行特定的操作。
*/
#ifdef __cplusplus
#if __cplusplus
}
#endif /* __cplusplus */
#endif /* __cplusplus */
#endif /* _LOS_LOWPOWER_H */