定时器

概述

RTL8721F 提供 9 个通用定时器 Timer0 至 Timer8,分为 Basic、PWM、Inpulse 三种硬件模式。Rust 驱动 ameba_hal::tim 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 三种硬件模式,通过 Basic / Pwm / Inpulse 类型状态区分:Timer0–3 为 Basic,Timer4–7 支持 PWM,Timer8 为 Inpulse

  • 可通过 TimBuilder::prescaler / TimBuilder::period 配置分频器和自动重载周期,Basic 定时器的分频器在硬件上被忽略并强制为 0

  • 每种模式都支持计数器启停、实时计数读取和软件复位,通过 Tim::start / stop / get_count / reset

  • 通过 Tim::register_irq / TimIrqHandler 注册裸 ISR 回调,9 个实例共享一张 9 槽位状态表

  • PWM 通道(Timer4–7)各提供 4 个比较通道,通过 Channel::Ch0 至 Ch3 选择,支持占空比、极性、预加载和相位同步配置,并通过 PwmChannel 实现 embedded_hal::pwm::SetDutyCycle

  • Inpulse 模式(Timer8)额外提供单脉冲模式、通过 EdgePolarity::Rising / Falling / BothEdge 设置的边沿触发极性,以及用于单次脉冲测量的相位计数

备注

Timer4 在 time-driver-tim4 特性下默认被保留作为 Embassy 时间驱动,如需释放给应用使用,可切换为 time-driver-tim5/tim6/tim7。

工作模式

Timer 支持三种硬件模式,由外设实例决定,而非运行时切换:Basic 模式、PWM 模式和 Inpulse 模式。

Basic 模式

Timer0 至 Timer3 从 0 计数到配置的自动重载周期,溢出时触发更新中断。这是在 Basic 类型实例上调用 TimBuilder::new(pac).period(arr).init() 返回的模式,通常搭配 register_irq 实现周期性 ISR 回调,因为 Tim 本身没有 async waker 路径。

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

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

PWM 模式

Timer4 至 Timer7 额外提供 4 个比较通道,通过实现了 embedded_hal::pwm::SetDutyCycle 的 PwmChannel 驱动。自动重载周期决定 PWM 频率,每个通道的比较值决定其占空比。

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

examples/tim/ 下没有独立的 PWM 示例。以上调用是根据 ameba-hal/src/tim/mod.rs 和 ameba-hal/src/tim/eh.rs 中 enable_channel / PwmChannel::new / SetDutyCycle 的签名和文档注释直接写出的示意代码,并非从可运行程序中节选。

Inpulse 模式

Timer8 用于测量或生成单次边沿触发脉冲,而不是作为自由运行计数器,通过 set_one_pulse_mode、set_edge_trigger_polarity 配置,并通过 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();

examples/tim/ 下没有独立的 Inpulse 模式示例。以上调用是根据 ameba-hal/src/tim/mod.rs 中 set_one_pulse_mode / set_edge_trigger_polarity / get_phase_count 的签名和文档注释直接写出的示意代码,并非从可运行程序中节选。

应用示例

Rust SDK 在 examples/tim/ 下提供一个示例项目:

  • tim

    Timer0 处于 Basic 模式,时钟源固定为 32768 Hz 的 SDM32K,通过 period = 32767 设置 1 秒周期。每次溢出触发 TIMER0_IRQ,通过 register_irq 注册的裸 ISR 回调对计数器加一。主任务等待 5 秒,每秒检查一次计数器,若最终计数与预期值 5 的偏差在 ±1 以内则报告通过。

    接线:无——纯粹是 Timer0 内部计数。

    [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
    

备注

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

API 参考

快速用法

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 还支持通过 register_irq 注册裸 ISR 回调,PWM 能力实例可通过 PwmChannel 对每个通道进行占空比控制,详见上文工作模式一节。