Real-Time Clock (RTC)

Overview

RTL8721F provides an RTC in the AON domain, keeping calendar time and alarm/wakeup state across chip sleep and reset. The Rust driver ameba_hal::rtc wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • Calendar time in binary or BCD format via TimeFormat::Bin / TimeFormat::Bcd, covering year, day-of-year, hours, minutes, seconds, and 12/24-hour format via HourFormat

  • Clock source selection between the SDM 32 kHz oscillator and OSC131K/4 via ClockSource::Sdm32k / ClockSource::Osc131kDiv4, and asynchronous/synchronous prescaler configuration via RtcConfig

  • Alarm comparison on seconds, minutes, hours, and day, with per-field masking via AlarmMask / AlarmDayMask

  • Wakeup timer with a configurable auto-reload value, independent of the alarm comparator

  • Day-counter rollover threshold and its own interrupt, configured via set_day_threshold / set_day_int

  • Daylight-saving hour adjustment via DaylightSaving::Add1h / DaylightSaving::Sub1h, with the adjustment direction recorded in a backup bit

  • RTC_OUT pin signal routing via OutputSel::Alarm / ClkSpre / ClkApre

  • Smooth calibration of the time-update frequency via set_calib, with configurable sign, magnitude, and period

  • AON detection-interrupt helpers via get_det_intr / clear_det_intr, independent of the RTC peripheral’s own interrupt flags

Note

The driver exposes no embedded_hal trait implementation — embedded-hal has no standard calendar/RTC trait, so all access goes through the methods on Rtc directly.

Operating Modes

RTC exposes three usage patterns built on the same peripheral instance: calendar time keeping, alarm comparison, and the wakeup timer.

Calendar Time

The base mode, always active once init succeeds: the peripheral free-runs a calendar clock that set_time writes and get_time reads back. The clock source must be selected after enable(true), since it defaults to the uncalibrated OSC131K/4 tap on AON power-on.

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);

Full example: examples/rtc/src/main.rs.

Alarm

A comparator against the running calendar clock, configured with set_alarm and armed with alarm_cmd. Fields set in AlarmMask / AlarmDayMask always match (they are excluded from the comparison). Fields left clear must equal the configured value. So a mask of just HOURS | MINUTES leaves seconds as the only compared field, firing once a minute when the seconds counter reaches the alarm’s configured seconds value.

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);

// Once RTC_IRQ fires, call rtc.clear_alarm() from the handler.

There is no standalone alarm example under examples/rtc/. The calls above are illustrative, built directly from the set_alarm / alarm_cmd / AlarmConfig signatures and doc comments in ameba-hal/src/rtc/mod.rs, not excerpted from a runnable program.

Wakeup Timer

An independent auto-reload countdown, unrelated to the calendar clock or alarm comparator, configured with set_wakeup and armed with wakeup_cmd. Enabling blocks for several seconds while the write-protected auto-reload register synchronizes.

use ameba_hal::rtc::Rtc;

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

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

// Once RTC_IRQ fires, call rtc.clear_wakeup() from the handler.

There is no standalone wakeup-timer example under examples/rtc/. The calls above are illustrative, built directly from the set_wakeup / wakeup_cmd signatures and doc comments in ameba-hal/src/rtc/mod.rs, not excerpted from a runnable program.

Application Examples

The Rust SDK provides one example project at rtc:

Sets the calendar time to 2025-01-01 12:00:00, waits 3 seconds, reads the time back, and checks that the elapsed seconds fall within a 2-4 second window to confirm the RTC is actually ticking.

Wiring: none — no external wiring required.

[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

The read-back can be 1 second lower than the 3 s wait (12:00:02 with diff: 2s); the check passes for any difference of 2 to 4 seconds.

Note

Build the example with cargo xtask build example --name rtc.

API Reference

Quick Usage

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);

For alarm comparison and the wakeup timer, please see the Operating Modes section above.