版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_pm 是 XTINY HAL 电源管理模块，提供功耗模式切换、定时唤醒、开机原因查询、关机和复位等系统级电源控制能力。模块通过 wakelock 机制协调各组件对低功耗模式的约束。

设计原则 ：

请求与强制分离 ： request 受 wakelock 约束， force 绕过约束直接进入
wakelock 协调 ：各组件持有 wakelock 时可阻止系统进入更低功耗模式
查询先于执行 ：通过 xt_hal_pm_check 先查询可进入的最低功耗模式，再决定是否进入
开关机溯源 ：提供多重接口查询开机原因，区分正常开机、闹钟唤醒、充电开机等场景

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义
xt_hal_rtc.h	定时唤醒依赖 RTC 闹钟能力

二、核心概念

2.1 功耗模式

模式	枚举值	行为（取决于平台实现）
XT_HAL_PM_MODE_WORK	正常工作	所有外设和 CPU 正常运行
XT_HAL_PM_MODE_DEEPSLEEP	深度睡眠	CPU 时钟停止，外设继续运行，可被任意中断唤醒
XT_HAL_PM_MODE_SLEEP	睡眠	外设寄存器掉电（AON 引脚保持），可被任意中断唤醒
XT_HAL_PM_MODE_PSM	PSM	效果等同于关机重启，区别是支持 RTC 唤醒。唤醒后从复位向量重新执行

注意：各模式的实际行为取决于平台实现，上表以 lm620 平台为参考。不同平台的功耗、唤醒延迟、状态保留程度可能不同。

request 模式切换时，系统实际会尝试进入请求模式。若 wakelock 阻止（如网络模块仍在活动），实际可能停留在更高功耗模式。

2.2 wakelock 机制

xt_hal_pm 内部通过 wakelock 协调各组件对低功耗模式的约束。用户无需直接操作 wakelock——通过 request / check 间接使用。

2.3 定时唤醒

通过 xt_hal_pm_timer_setup 设置定时唤醒后，即使系统已进入低功耗模式，指定的时间后仍会被唤醒。唤醒后触发回调（DEEPSLEEP/SLEEP 模式）或从复位向量重新执行（PSM 模式）。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_pm（电源管理）。

3.1 功耗模式控制

函数签名	说明
xt_err_t xt_hal_pm_request(uint8_t mode)	请求进入指定功耗模式（受 wakelock 约束）
xt_err_t xt_hal_pm_force(uint8_t mode)	强制进入指定功耗模式（绕过 wakelock）
int32_t xt_hal_pm_check(uint8_t mode)	检查可进入的最低功耗模式

3.2 定时唤醒

函数签名	说明
xt_err_t xt_hal_pm_timer_setup(uint8_t timer_id, uint32_t timeout_ms, xt_hal_pm_cb_t cb)	设置定时唤醒
xt_err_t xt_hal_pm_timer_close(uint8_t timer_id)	关闭定时唤醒
bool xt_hal_pm_timer_is_running(uint8_t timer_id)	检查定时器是否运行
xt_err_t xt_hal_pm_timer_get_remaining(uint8_t timer_id, xt_hal_rtc_timestamp_t *remaining_time_ms)	获取定时器剩余时间（毫秒）

3.3 状态查询

函数签名	说明
xt_err_t xt_hal_pm_get_last_state(uint8_t last_state, uint8_t wake_reason)	获取休眠前状态和唤醒原因
int32_t xt_hal_pm_get_wake_reason(void)	获取开机原因
int32_t xt_hal_pm_get_reset_reason(void)	获取重启原因（同开机原因）

3.4 系统控制

函数签名	说明
xt_err_t xt_hal_pm_poweroff(void)	系统关机
xt_err_t xt_hal_pm_reset(void)	系统复位
xt_err_t xt_hal_pm_set_power(uint8_t power_id, uint8_t val)	控制内部电源域开关

四、编译配置

无编译配置项。

五、常见模式

5.1 进入休眠前检查

#include "xt_hal_pm.h"
 
void try_sleep(void) {
    int32_t allowed = xt_hal_pm_check(XT_HAL_PM_MODE_PSM);
    if (allowed <= XT_HAL_PM_MODE_SLEEP) {
        xt_hal_pm_request(XT_HAL_PM_MODE_SLEEP);
    }
}

5.2 定时唤醒后执行任务

#include "xt_hal_pm.h"
 
static void wakeup_cb(uint8_t id, uint32_t event_id) {
    if (event_id == XT_HAL_PM_EVENT_TIMER) {
        /* 定时时间到，执行周期任务 */
    }
}
 
void sleep_with_timer(void) {
    xt_hal_pm_timer_setup(0, 60000, wakeup_cb);
    xt_hal_pm_request(XT_HAL_PM_MODE_SLEEP);
}

5.3 开机时判断启动原因

#include "xt_hal_pm.h"
 
void check_boot_reason(void) {
    int32_t reason = xt_hal_pm_get_wake_reason();
    switch (reason) {
    case XT_HAL_PM_POWER_ON_NORMAL:
        /* 正常开机，执行完整初始化 */
        break;
    case XT_HAL_PM_POWER_ON_ALRAM:
        /* 闹钟唤醒，执行闹钟处理 */
        break;
    case XT_HAL_PM_POWER_ON_WDT:
        /* WDT 复位，记录异常日志 */
        break;
    }
}

六、已知行为与限制

行为	说明
request 受 wakelock 约束	实际进入的功耗模式可能高于请求的模式
force 立即进入	深度休眠时跳过系统调度，直接进入
定时器回调在中断上下文	不可执行耗时操作
timer_setup 定时器唯一	同一 timer_id 重复设置返回 XT_EBUSY
定时精度取决于平台	某些平台仅支持秒级精度
深度休眠模式下回调不触发	系统会唤醒但不会执行回调
poweroff 为真关机	完全断电，不同于进入低功耗模式
get_remaining 返回毫秒	若平台仅秒级精度，剩余不足 1 秒时返回 0