RTC

概述

RTL8721F 在 AON 域提供 RTC,在芯片休眠和复位期间保持日历时间以及闹钟/唤醒状态。Rust 驱动 ameba_hal::rtc 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 日历时间支持 binary 或 BCD 格式,通过 TimeFormat::Bin / TimeFormat::Bcd 设置,涵盖年、年内天数、时、分、秒,以及通过 HourFormat 设置的 12/24 小时制

  • 时钟源可在 SDM 32 kHz 振荡器和 OSC131K/4 之间切换,通过 ClockSource::Sdm32k / ClockSource::Osc131kDiv4 设置,异步/同步分频器可通过 RtcConfig 配置

  • 闹钟可对秒、分、时、日分别比较,通过 AlarmMask / AlarmDayMask 设置各字段的比较掩码

  • 唤醒定时器提供可配置的自动重载值,独立于闹钟比较器

  • 日计数器翻转阈值及其独立中断,通过 set_day_threshold / set_day_int 配置

  • 夏令时调整支持通过 DaylightSaving::Add1h / DaylightSaving::Sub1h 加减一小时,调整方向记录在一个备份位中

  • RTC_OUT 引脚信号选择,通过 OutputSel::Alarm / ClkSpre / ClkApre 设置

  • 通过 set_calib 对时间更新频率做平滑校准,可配置符号、幅度和周期

  • AON 检测中断辅助函数 get_det_intr / clear_det_intr,独立于 RTC 外设自身的中断标志

备注

驱动未实现任何 embedded_hal trait——embedded-hal 没有标准的日历/RTC trait,因此所有访问都直接通过 Rtc 上的方法进行。

工作模式

RTC 在同一个外设实例上提供三种用法:日历计时、闹钟比较、唤醒定时器。

日历计时

基础模式,只要 init 成功就始终生效:外设自由运行一个日历时钟,set_time 写入,get_time 读回。时钟源需要在 enable(true) 之后选择,因为 AON 上电后默认使用未校准的 OSC131K/4 分支。

use ameba_hal::{
    println,
    rcc,
    rtc::{AmPm, ClockSource, Rtc, RtcConfig, TimeConfig, TimeFormat},
};
...
rcc::enable(rcc::Peripheral::RTC);

let rtc = unsafe { Rtc::steal() };
rtc.enable(true);

rcc::enable(rcc::Peripheral::RTC_FEN);

let ok = rtc.init(&RtcConfig::default());
if !ok {
    println!("[RTC] init failed");
    return;
}

// Set time to 2025-01-01 12:00:00
let start_time = TimeConfig {
    am_pm: AmPm::Am,
    year: 2025,
    days: 1,
    hours: 12,
    minutes: 0,
    seconds: 0,
};

let ok = rtc.set_time(TimeFormat::Bin, &start_time);
if !ok {
    println!("[RTC] set_time failed");
    return;
}

...
rtc.set_clock_source(ClockSource::Sdm32k);
...
let t = rtc.get_time(TimeFormat::Bin);

完整示例见 examples/rtc/src/main.rs。

闹钟

对运行中的日历时钟做比较,通过 set_alarm 配置,通过 alarm_cmd 使能。在 AlarmMask / AlarmDayMask 中被置位的字段始终视为匹配(即被排除在比较之外)。未置位的字段则必须等于配置的值才算匹配。因此仅设置 HOURS | MINUTES 时,只有秒字段参与比较,秒计数达到闹钟配置的秒值时才会每分钟触发一次。

use ameba_hal::rtc::{AlarmConfig, AlarmMask, Rtc, TimeFormat};

let rtc = unsafe { Rtc::steal() };

let alarm = AlarmConfig {
    mask: AlarmMask::HOURS | AlarmMask::MINUTES,
    ..AlarmConfig::default()
};
rtc.set_alarm(TimeFormat::Bin, &alarm);
rtc.alarm_cmd(true);

// RTC_IRQ 触发后,在中断处理函数中调用 rtc.clear_alarm()。

examples/rtc/ 下没有独立的闹钟示例。以上调用是根据 ameba-hal/src/rtc/mod.rs 中 set_alarm / alarm_cmd / AlarmConfig 的函数签名和文档注释直接写出的说明性用法,并非节选自某个可运行程序。

唤醒定时器

一个独立的自动重载倒计时,与日历时钟和闹钟比较器无关,通过 set_wakeup 配置,通过 wakeup_cmd 使能。使能时会阻塞数秒,等待带写保护的自动重载寄存器完成同步。

use ameba_hal::rtc::Rtc;

let rtc = unsafe { Rtc::steal() };

rtc.set_wakeup(0x1FFF);
rtc.wakeup_cmd(true);

// RTC_IRQ 触发后,在中断处理函数中调用 rtc.clear_wakeup()。

examples/rtc/ 下没有独立的唤醒定时器示例。以上调用是根据 ameba-hal/src/rtc/mod.rs 中 set_wakeup / wakeup_cmd 的函数签名和文档注释直接写出的说明性用法,并非节选自某个可运行程序。

应用示例

Rust SDK 提供了一个示例项目 rtc:

将日历时间设为 2025-01-01 12:00:00,等待 3 秒后读回,检查读回的秒差是否落在 2-4 秒区间内,以确认 RTC 确实在计时。

接线:无需外部接线。

[RTC] start
[RTC] time set to 2025-01-01 12:00:00, waiting 3s...
[RTC] read-back: 2025-001 12:00:02
[RTC] diff: 2s  (embassy elapsed: 3000ms)
[PASS] RTC: tick OK

回读时间可能比 3 秒等待少 1 秒(12:00:02,diff: 2s);只要差值在 2 到 4 秒之间即判定通过。

备注

编译该示例:cargo xtask build example --name rtc。

API 参考

快速使用

use ameba_hal::rcc;
use ameba_hal::rtc::{AmPm, ClockSource, Rtc, RtcConfig, TimeConfig, TimeFormat};

rcc::enable(rcc::Peripheral::RTC);

let rtc = unsafe { Rtc::steal() };
rtc.enable(true);
rtc.init(&RtcConfig::default());
rtc.set_clock_source(ClockSource::Sdm32k);

let now = TimeConfig { am_pm: AmPm::Am, year: 2025, days: 1, hours: 12, minutes: 0, seconds: 0 };
rtc.set_time(TimeFormat::Bin, &now);

let t = rtc.get_time(TimeFormat::Bin);

闹钟比较和唤醒定时器的用法请参见上面的工作模式部分。