Timer
Overview
RTL8721F provides 9 general-purpose timers, Timer0 through Timer8, grouped into three hardware modes: Basic, PWM, and Inpulse. The Rust driver ameba_hal::tim wraps the PAC register block directly — no raw bit-masking or C FFI is involved.
Features
Three hardware modes via the
Basic/Pwm/Inpulsetypestates: Timer0-3 are Basic, Timer4-7 are PWM-capable, Timer8 is InpulseConfigurable prescaler and auto-reload period via
TimBuilder::prescaler/TimBuilder::period, and the prescaler is hardware-ignored on Basic timers and forced to 0Counter start/stop, live counter readback, and software reset available on every mode via
Tim::start/stop/get_count/resetRaw ISR callback registration via
Tim::register_irq/TimIrqHandler, shared across all 9 instances with a 9-slot state tablePWM channels (Timer4-7) expose 4 compare channels each via
Channel::Ch0throughCh3, with duty cycle, polarity, preload, and phase-sync control, and implementembedded_hal::pwm::SetDutyCyclethroughPwmChannelInpulse mode (Timer8) adds one-pulse mode, edge-trigger polarity via
EdgePolarity::Rising/Falling/BothEdge, and phase counting for single-shot pulse measurement
Note
Timer4 is reserved by default as the Embassy time driver under the time-driver-tim4 feature. Switch to time-driver-tim5/tim6/tim7 to free it for application use.
Operating Modes
Timer supports three hardware modes, selected by the peripheral instance rather than a runtime switch: Basic Mode, PWM Mode, and Inpulse Mode.
Basic Mode
Timer0 through Timer3 count up from 0 to the configured auto-reload period and raise an update interrupt on overflow. This is the mode returned by TimBuilder::new(pac).period(arr).init() on a Basic-typed instance, and is typically paired with register_irq for a periodic ISR callback, since Tim itself has no async waker path.
use core::ptr::addr_of_mut;
use core::sync::atomic::{AtomicU32, Ordering};
...
use ameba_hal::bind_interrupts;
use ameba_hal::pac::Timer0Reg;
use ameba_hal::println;
use ameba_hal::tim::{self, TimFlag, TimIrqEvent, TimIrqHandler, TimIt};
...
static IRQ_COUNT: AtomicU32 = AtomicU32::new(0);
bind_interrupts!(struct Irqs {
TIMER0_IRQ => tim::InterruptHandler<Timer0Reg>;
});
struct Timer0Handler;
impl TimIrqHandler for Timer0Handler {
fn on_irq(&mut self, event: TimIrqEvent) {
if event.flags.contains(TimFlag::UIF) {
IRQ_COUNT.fetch_add(1, Ordering::Release);
}
}
}
static mut TIMER0_HANDLER: Timer0Handler = Timer0Handler;
...
const PERIOD_1S: u32 = 32767;
...
let pac = unsafe { Timer0Reg::steal() };
let tim = tim::TimBuilder::new(pac).period(PERIOD_1S).init();
tim.register_irq(unsafe { &mut *addr_of_mut!(TIMER0_HANDLER) }, Irqs);
tim.enable_interrupt(TimIt::UIE);
tim.start();
Full example: examples/tim/src/main.rs.
PWM Mode
Timer4 through Timer7 additionally expose 4 compare channels each, driven through PwmChannel, which implements embedded_hal::pwm::SetDutyCycle. The auto-reload period sets the PWM frequency, and each channel’s compare value sets its duty cycle.
use ameba_hal::pac::Timer4Reg;
use ameba_hal::tim::{Channel, TimBuilder};
use ameba_hal::tim::eh::PwmChannel;
use embedded_hal::pwm::SetDutyCycle;
let pac = unsafe { Timer4Reg::steal() };
let tim = TimBuilder::new(pac).period(999).init();
tim.enable_channel(Channel::Ch0);
tim.start();
let mut ch0 = PwmChannel::new(&tim, Channel::Ch0);
let _ = ch0.set_duty_cycle(500);
There is no standalone PWM example under examples/tim/. The calls above are illustrative, built directly from the enable_channel / PwmChannel::new / SetDutyCycle signatures and doc comments in ameba-hal/src/tim/mod.rs and ameba-hal/src/tim/eh.rs, not excerpted from a runnable program.
Inpulse Mode
Timer8 measures or generates a single edge-triggered pulse instead of running as a free-running counter, configured with set_one_pulse_mode, set_edge_trigger_polarity, and phase-count readback via get_phase_count.
use ameba_hal::pac::Timer8Reg;
use ameba_hal::tim::{EdgePolarity, TimBuilder};
let pac = unsafe { Timer8Reg::steal() };
let tim = TimBuilder::new(pac).period(0xFFFF).init();
tim.set_one_pulse_mode(true);
tim.set_edge_trigger_polarity(EdgePolarity::Rising);
tim.start();
let phase = tim.get_phase_count();
There is no standalone Inpulse-mode example under examples/tim/. The calls above are illustrative, built directly from the set_one_pulse_mode / set_edge_trigger_polarity / get_phase_count signatures and doc comments in ameba-hal/src/tim/mod.rs, not excerpted from a runnable program.
Application Examples
The Rust SDK provides one example project under examples/tim/:
-
Timer0 in Basic mode, clocked from the fixed 32768 Hz SDM32K source with a 1-second period set via
period = 32767. Each overflow raisesTIMER0_IRQ, and a raw ISR callback registered viaregister_irqincrements a counter. The main task waits 5 seconds, checking the counter once per second, and reports pass if the final count lands within ±1 of the expected 5.Wiring: none — purely internal Timer0 counting.
[TIM] hardware timer test start [TIM] timer0 started (32kHz clock, 1s period) [TIM] irq_count=1 expected=1 [TIM] irq_count=2 expected=2 [TIM] irq_count=3 expected=3 [TIM] irq_count=4 expected=4 [TIM] irq_count=5 expected=5 [PASS] timer0: irq_count=5
Note
Build any example with cargo xtask build example --name tim.
API Reference
Quick Usage
use ameba_hal::pac::Timer0Reg;
use ameba_hal::tim::{TimBuilder, TimIt};
let pac = unsafe { Timer0Reg::steal() };
let tim = TimBuilder::new(pac).period(32_767).init();
tim.enable_interrupt(TimIt::UIE);
tim.start();
let count = tim.get_count();
Tim also supports a raw ISR callback via register_irq, and PWM-capable instances expose per-channel duty cycle control through PwmChannel — see the Operating Modes section above.