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 / Inpulse typestates: Timer0-3 are Basic, Timer4-7 are PWM-capable, Timer8 is Inpulse

  • Configurable prescaler and auto-reload period via TimBuilder::prescaler / TimBuilder::period, and the prescaler is hardware-ignored on Basic timers and forced to 0

  • Counter start/stop, live counter readback, and software reset available on every mode via Tim::start / stop / get_count / reset

  • Raw ISR callback registration via Tim::register_irq / TimIrqHandler, shared across all 9 instances with a 9-slot state table

  • PWM channels (Timer4-7) expose 4 compare channels each via Channel::Ch0 through Ch3, with duty cycle, polarity, preload, and phase-sync control, and implement embedded_hal::pwm::SetDutyCycle through PwmChannel

  • Inpulse 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/:

  • tim

    Timer0 in Basic mode, clocked from the fixed 32768 Hz SDM32K source with a 1-second period set via period = 32767. Each overflow raises TIMER0_IRQ, and a raw ISR callback registered via register_irq increments 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.