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);
闹钟比较和唤醒定时器的用法请参见上面的工作模式部分。