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

一、概述

xt_hal_rtc 是 XTINY HAL 层的 RTC 驱动模块，提供实时时钟的时间设置/获取、时间戳转换、闹钟管理（绝对时间/相对延迟）和时区配置。所有平台都必须实现此模块。

1.1 设计原则

懒初始化 ：首次调用时间设置/获取/闹钟等操作时才初始化 RTC 硬件，避免资源浪费
双闹钟模式 ：支持绝对时间闹钟和相对延迟闹钟，满足不同场景需求
时间戳独立 ：提供 POSIX 风格的 tm 结构体和 UNIX 时间戳两种时间表示方式
时区可配置 ：时区以 15 分钟为单位，支持设置和查询

1.2 依赖

依赖	用途
xt_hal_internal.h	HAL 内部类型与工具宏

二、核心概念

2.1 时间表示

形式	类型	说明
xt_hal_rtc_tm 结构体	struct xt_hal_rtc_tm	年/月/日/时/分/秒/毫秒，与 POSIX tm 类似
UNIX 时间戳	xt_hal_rtc_timestamp_t	自 1970-01-01 00:00:00 起的秒数，默认 uint32_t

通过定义 XT_HAL_RTC_TIME_64BITS 可将时间戳类型切换为 uint64_t ，避免 2038 年溢出。

2.2 xt_hal_rtc_tm 字段

字段	范围	说明
tm_year	—	年份（从 1900 年开始计数）
tm_mon	0–11	月份（0=1月）
tm_mday	1–31	日期
tm_hour	0–23	小时
tm_min	0–59	分钟
tm_sec	0–60	秒（含闰秒）
tm_wday	0–6	星期（0=周日）
tm_msec	0–999	毫秒（非标准，不一定全平台支持）

2.3 闹钟

两个闹钟接口分别对应不同场景：

接口	参数	适用场景
xt_hal_rtc_setup_alarm	绝对时间 tm	定时任务（每天 8:00 触发）
xt_hal_rtc_setup_alarm_relative	相对毫秒 timeout_ms	超时/延迟任务（5 分钟后触发）

相对闹钟的毫秒参数可能受平台精度限制，实际只精确到秒级。闹钟触发后自动关闭，回调中无需手动 close_alarm 。同一闹钟 ID 不可重复注册（返回 XT_EBUSY ）。

2.4 时区

时区值以 15 分钟为单位。例如东八区 = 8 × 4 = 32（个 15 分钟）。正数表示东区（UTC+），负数表示西区（UTC-）。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_rtc（RTC 驱动）。

3.1 时间操作

函数签名	说明
xt_err_t xt_hal_rtc_set_time(struct xt_hal_rtc_tm *tm)	设置 RTC 时间（首次调用触发硬件初始化）
xt_err_t xt_hal_rtc_get_time(struct xt_hal_rtc_tm *tm)	获取 RTC 当前时间
xt_hal_rtc_timestamp_t xt_hal_rtc_get_timestamp(void)	获取 UNIX 时间戳

3.2 闹钟管理

函数签名	说明
xt_err_t xt_hal_rtc_setup_alarm(uint8_t id, struct xt_hal_rtc_tm *tm, xt_hal_rtc_cb_t cb)	设置绝对时间闹钟
xt_err_t xt_hal_rtc_setup_alarm_relative(uint8_t id, uint32_t timeout_ms, xt_hal_rtc_cb_t cb)	设置相对延迟闹钟
xt_err_t xt_hal_rtc_close_alarm(uint8_t id)	关闭闹钟
xt_err_t xt_hal_rtc_get_alarm(uint8_t id, struct xt_hal_rtc_tm *tm)	获取闹钟触发时间

3.3 时区

函数签名	说明
xt_err_t xt_hal_rtc_set_timezone(int8_t zone)	设置时区（单位：15 分钟）
xt_err_t xt_hal_rtc_get_timezone(int8_t *zone)	获取当前时区

3.4 类型

类型签名	说明
struct xt_hal_rtc_tm	时间结构体（年/月/日/时/分/秒/毫秒/星期）
xt_hal_rtc_timestamp_t	时间戳类型，默认 uint32_t
xt_hal_rtc_cb_t	回调函数类型： void (*)(uint8_t id, uint32_t event_id)
enum xt_hal_rtc_event_id	事件 ID 枚举（ XT_HAL_RTC_ALARM ）

四、常见模式

4.1 设置与读取时间

#include "xt_hal_rtc.h"
 
void rtc_set_current(void) {
    struct xt_hal_rtc_tm tm = {0};
    tm.tm_year = 2026;
    tm.tm_mon  = 6;   /* 7 月（0 起始） */
    tm.tm_mday = 3;
    tm.tm_hour = 10;
    tm.tm_min  = 30;
    tm.tm_sec  = 0;
    xt_hal_rtc_set_time(&tm);
}
 
void rtc_print_time(void) {
    struct xt_hal_rtc_tm tm;
    xt_hal_rtc_get_time(&tm);
    /* 使用 tm.tm_year, tm.tm_mon, tm.tm_mday 等 */
}

4.2 绝对时间闹钟——每天定时触发

#include "xt_hal_rtc.h"
 
static void alarm_cb(uint8_t id, uint32_t event_id) {
    if (event_id == XT_HAL_RTC_ALARM) {
        /* 闹钟触发，执行定时任务 */
    }
}
 
void rtc_set_daily_alarm(void) {
    struct xt_hal_rtc_tm tm = {0};
    xt_hal_rtc_get_time(&tm);
    tm.tm_hour = 8;
    tm.tm_min  = 0;
    tm.tm_sec  = 0;
    xt_hal_rtc_setup_alarm(0, &tm, alarm_cb);
}

4.3 相对延迟闹钟——超时通知

#include "xt_hal_rtc.h"
 
static void timeout_cb(uint8_t id, uint32_t event_id) {
    /* 30 秒超时触发 */
}
 
void rtc_start_timeout(void) {
    xt_hal_rtc_setup_alarm_relative(0, 30000, timeout_cb);
}

4.4 设置时区

#include "xt_hal_rtc.h"
 
void rtc_set_cst(void) {
    xt_hal_rtc_set_timezone(32);  /* 东八区：8*4=32 */
}

五、已知行为与限制

行为	说明
懒初始化	首次调用时间/闹钟相关函数时才初始化 RTC 硬件
闹钟触发后自动关闭	回调中无需调 close_alarm
同一 ID 不可重复注册	重复 setup_alarm 返回 XT_EBUSY
相对闹钟精度可能为秒级	timeout_ms 为毫秒参数，但实际精度由平台决定
时间戳默认 uint32_t	2038 年溢出，可定义 XT_HAL_RTC_TIME_64BITS 切换
tm_msec 非跨平台	毫秒字段不一定所有平台支持