版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_timer 是 XTINY HAL 硬件定时器模块，基于芯片硬件定时器外设提供单次/周期触发、启动/停止控制以及频率计数查询等功能。定时器超时后通过回调通知用户。

设计原则 ：

硬件定时器 ：直接操作芯片定时器硬件，无需操作系统定时器资源
灵活频率配置 ： tick_freq_hz 支持极端值——0 使用最大分频（最低功耗）， 0xFFFFFFFF 使用不分频（最高精度）
模式组合 ：启动行为（立即/待命）、触发模式（单次/周期）、计数方向（向上/向下）通过预定义宏组合

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义

二、核心概念

2.1 定时器时间计算

定时器超时时间由两个参数共同决定：

超时时间 = tick_num / 定时器实际频率

其中定时器实际频率 = 时钟源频率 / (预分频值 + 1) ，预分频值由 tick_freq_hz 参数推导得出：

预分频值 = 时钟源频率 / tick_freq_hz - 1

因此，用户通常只需要设置 tick_freq_hz 和 tick_num ，无需关心底层分频细节。若需精确了解实际定时器频率，可使用 xt_hal_timer_get_clk_src_freq 和 xt_hal_timer_get_prescaler 查询。

2.2 mode 参数

宏	说明
XT_HAL_TIMER_START	初始化后立即启动（默认）
XT_HAL_TIMER_STOP	初始化后不启动，需手动调用 xt_hal_timer_start
XT_HAL_TIMER_ONE_SHOT	单次触发，超时后停止
XT_HAL_TIMER_PERIODIC	周期触发（默认），超时后自动重载
XT_HAL_TIMER_DIR_UP	向上计数（默认）
XT_HAL_TIMER_DIR_DOWN	向下计数
XT_HAL_TIMER_DEFAULT_MODE	默认模式：周期 + 向上 + 立即启动

2.3 回调

定时器超时时以中断上下文调用回调函数。回调中应尽快完成处理，不应执行耗时操作或阻塞等待。如需执行复杂处理，建议在回调中设置标志位，由主循环或任务处理。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_timer（硬件定时器驱动）。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_timer_setup(uint8_t timer_id, uint32_t mode, uint32_t tick_freq_hz, uint32_t tick_num, xt_hal_timer_cb_t cb)	初始化定时器
xt_err_t xt_hal_timer_close(uint8_t timer_id)	关闭定时器

3.2 运行控制

函数签名	说明
xt_err_t xt_hal_timer_start(uint8_t timer_id)	启动定时器
xt_err_t xt_hal_timer_stop(uint8_t timer_id)	停止定时器

3.3 查询

函数签名	说明
uint32_t xt_hal_timer_get_clk_src_freq(uint8_t timer_id)	获取定时器时钟源频率（Hz）
uint32_t xt_hal_timer_get_prescaler(uint8_t timer_id)	获取定时器实际分频值（psc+1），参数错误返回 0
uint32_t xt_hal_timer_get_count(uint8_t timer_id)	获取定时器当前计数值

四、编译配置

无编译配置项。

五、常见模式

5.1 单次延时触发

#include "xt_hal_timer.h"
 
static void one_shot_cb(uint8_t timer_id, uint32_t event_id) {
    /* 延时时间到，执行一次性操作 */
}
 
void setup_delay(void) {
    uint32_t mode = XT_HAL_TIMER_ONE_SHOT | XT_HAL_TIMER_START | XT_HAL_TIMER_DIR_UP;
    /* 1kHz tick 频率，计数 1000 → 1 秒后触发 */
    xt_hal_timer_setup(0, mode, 1000, 1000, one_shot_cb);
}

5.2 周期定时触发

#include "xt_hal_timer.h"
 
static void periodic_cb(uint8_t timer_id, uint32_t event_id) {
    /* 每 100ms 执行一次 */
}
 
void setup_periodic(void) {
    /* 使用默认模式：周期 + 向上 + 立即启动 */
    /* 10kHz tick 频率，计数 1000 → 100ms 周期 */
    xt_hal_timer_setup(0, XT_HAL_TIMER_DEFAULT_MODE, 10000, 1000, periodic_cb);
}

5.3 手动控制启停

#include "xt_hal_timer.h"
 
static void timer_cb(uint8_t timer_id, uint32_t event_id) {
    /* 处理超时 */
}
 
void setup_manual_control(void) {
    uint32_t mode = XT_HAL_TIMER_PERIODIC | XT_HAL_TIMER_STOP | XT_HAL_TIMER_DIR_UP;
    xt_hal_timer_setup(0, mode, 1000, 500, timer_cb);
 
    /* 业务逻辑控制启停 */
    if (need_start) {
        xt_hal_timer_start(0);
    }
}

六、已知行为与限制

行为	说明
tick_freq_hz=0 时最大分频	内部使用最大分频值（最低 tick 频率），适合低频超长定时
tick_freq_hz=0xFFFFFFFF 时不预分频	直接使用时钟源频率，适合最高精度定时
tick_num 最小值平台依赖	不保证能设置为 1，取决于平台硬件计数器的位宽和实现
回调在中断上下文	定时器回调在中断中执行，不能阻塞或执行耗时操作
频率近似	实际分频值为整数，可能无法精确匹配 tick_freq_hz ，查询 get_prescaler 和 get_clk_src_freq 可获取实际值