新版软件定时器接口（对象化、单链表、new/delete 生命周期）更多...

结构体
struct	xt_timer2
	定时器对象更多...

宏定义
#define	XT_TIMER2_TIMEOUT_MAX INT32_MAX
	最大超时 tick 数（INT32_MAX，约 24.8 天 @ 1ms/tick）
#define	XT_TIMER2_DEBUG 1
	调试模式开关，默认开启。关闭后移除 magic 字段和校验
#define	XT_TIMER2_MAGIC (0x159DU)
	Magic 值，用于检测内存踩踏
#define	XT_TIMER2_FREE_MAGIC ((void *)0xA1B2C3D4)
	内存池空闲槽位魔数标记

类型定义
typedef uint32_t	xt_tick2_t
	tick 类型，32 位无符号
typedef struct xt_timer2	xt_timer2_t
	定时器句柄（前向声明）
typedef void(*	xt_timer2_cb_t) (xt_timer2_t t, void user_data)
	定时器回调函数类型

函数
xt_timer2_t *	xt_timer2_new (xt_timer2_cb_t timer_cb, void *user_data)
	动态分配并初始化一个定时器
xt_err_t	xt_timer2_delete (xt_timer2_t *t)
	删除定时器并释放内存
xt_err_t	xt_timer2_setup (xt_timer2_t t, xt_timer2_cb_t timer_cb, void user_data)
	配置定时器回调函数和用户数据（不启动）
xt_err_t	xt_timer2_start (xt_timer2_t *t, xt_tick2_t tick_timeout)
	启动/重启定时器，挂入工作链表
xt_err_t	xt_timer2_stop (xt_timer2_t *t)
	停止定时器，从工作链表摘下
bool	xt_timer2_is_running (xt_timer2_t *t)
	查询定时器是否在工作链表上
xt_err_t	xt_timer2_set_cb (xt_timer2_t *t, xt_timer2_cb_t cb)
	设置回调函数
xt_err_t	xt_timer2_set_user_data (xt_timer2_t t, void user_data)
	设置用户数据
xt_tick2_t	xt_timer2_remain (xt_tick2_t timeout_tick)
	计算剩余超时 tick 数（有符号差值，天然回绕安全）
xt_tick2_t	xt_timer2_handler (void)
	定时器主循环处理函数，需在主循环中周期性调用
void	xt_timer2_sys_setup (xt_timer2_t *pool_buf, size_t pool_count)
	初始化定时器子系统内存池
void	xt_timer2_sys_reset (void)
	重置定时器子系统运行时状态（仅测试/调试用）
void	xt_timer2_enable_custom_tick (bool enable)
	启停自定义 tick 模式（测试用）
void	xt_tick2_inc (xt_tick2_t inc)
	手动推进自定义 tick
void	xt_tick2_set (xt_tick2_t val)
	手动设置自定义 tick 值
xt_tick2_t	xt_tick2_get (void)
	获取当前系统 tick 值

详细描述

新版软件定时器接口（对象化、单链表、new/delete 生命周期）

宏定义说明

◆ XT_TIMER2_DEBUG

#define XT_TIMER2_DEBUG 1

调试模式开关，默认开启。关闭后移除 magic 字段和校验

在文件 xt_timer2.h 第 41 行定义.

◆ XT_TIMER2_FREE_MAGIC

#define XT_TIMER2_FREE_MAGIC ((void *)0xA1B2C3D4)

内存池空闲槽位魔数标记

在文件 xt_timer2.h 第 50 行定义.

◆ XT_TIMER2_MAGIC

#define XT_TIMER2_MAGIC (0x159DU)

Magic 值，用于检测内存踩踏

在文件 xt_timer2.h 第 46 行定义.

◆ XT_TIMER2_TIMEOUT_MAX

#define XT_TIMER2_TIMEOUT_MAX INT32_MAX

最大超时 tick 数（INT32_MAX，约 24.8 天 @ 1ms/tick）

在文件 xt_timer2.h 第 37 行定义.

类型定义说明

◆ xt_tick2_t

typedef uint32_t xt_tick2_t

tick 类型，32 位无符号

在文件 xt_timer2.h 第 55 行定义.

◆ xt_timer2_cb_t

typedef void(* xt_timer2_cb_t) (xt_timer2_t *t, void *user_data)

定时器回调函数类型

参数

t	定时器句柄
user_data	用户透传数据

在文件 xt_timer2.h 第 66 行定义.

◆ xt_timer2_t

typedef struct xt_timer2 xt_timer2_t

定时器句柄（前向声明）

在文件 xt_timer2.h 第 58 行定义.

函数说明

◆ xt_tick2_get()

xt_tick2_t xt_tick2_get ( void )

获取当前系统 tick 值

自定义 tick 模式下返回 xt_tick2_inc/set 控制的计数器（带 ISR 安全读取），硬件模式下返回 xt_tick_get()。

返回: 当前 tick 值（32-bit 无符号，自然回绕）

◆ xt_tick2_inc()

void xt_tick2_inc ( xt_tick2_t inc )

手动推进自定义 tick

参数

inc	推进的 tick 数

◆ xt_tick2_set()

void xt_tick2_set ( xt_tick2_t val )

手动设置自定义 tick 值

参数

val 新的 tick 值

◆ xt_timer2_delete()

xt_err_t xt_timer2_delete ( xt_timer2_t * t )

删除定时器并释放内存

若定时器在工作链表上则自动摘下，再调用 XT_TIMER2_FREE 释放。

参数

t	定时器句柄，不可为 NULL

返回: XT_EOK 成功; XT_EINVAL 参数无效（t==NULL）

注解: 不区分静态/动态分配，由用户保证只对 new 出来的定时器调用。 TODO: 从 node 拿出 bit 判断是否为 new 分配，防止误删静态对象。

◆ xt_timer2_enable_custom_tick()

void xt_timer2_enable_custom_tick ( bool enable )

启停自定义 tick 模式（测试用）

启用后 xt_timer2_handler / xt_timer2_remain 等使用 xt_tick2_inc/set 控制的计数器。

参数

enable true 启用自定义 tick，false 恢复硬件 tick

◆ xt_timer2_handler()

xt_tick2_t xt_timer2_handler ( void )

定时器主循环处理函数，需在主循环中周期性调用

三阶段处理：

阶段1（临界区内）：遍历工作链表，到期定时器摘下挂入 fire_snap 快照。
阶段2（临界区外）：逐个从 fire_snap 取出执行回调。回调后无处理，用户自行维护定时器。
阶段3（临界区内）：遍历工作链表，计算最小剩余时间。

返回: 下次超时前需等待的最小 tick 数

返回值

UINT32_MAX	无活跃定时器
0	有到期定时器已处理，调用者应重调 handler

注解: 典型用法：
xt_tick2_t remain = xt_timer2_handler();

if (remain == UINT32_MAX) { osDelay(1000); }

else if (remain == 0) { continue; }

else { osDelay(remain); }

xt_timer2_handler
xt_tick2_t xt_timer2_handler(void)
定时器主循环处理函数，需在主循环中周期性调用

xt_tick2_t
uint32_t xt_tick2_t
tick 类型，32 位无符号
定义 xt_timer2.h:55; 回调中新增/重启的定时器在当前轮不会触发（延迟最多 1 个 handler 周期）。

◆ xt_timer2_is_running()

bool xt_timer2_is_running ( xt_timer2_t * t )

查询定时器是否在工作链表上

临界区内遍历工作链表确认（而非只看 node.next，防止用户将 node 挂自己链表中）。

参数

t	定时器句柄，可为 NULL

返回: true 在工作链表上; false 不在或 t==NULL

◆ xt_timer2_new()

xt_timer2_t * xt_timer2_new	(	xt_timer2_cb_t	timer_cb,
		void *	user_data )

动态分配并初始化一个定时器

通过 XT_TIMER2_MALLOC 分配内存，可编译期重定义为内存池分配。返回的定时器可直接 start 无需先 setup。

参数

timer_cb	超时回调函数，不可为 NULL
user_data	回调透传数据

返回: 定时器指针

返回值

NULL 参数无效或分配失败

注解: 分配失败触发 assert。

◆ xt_timer2_remain()

xt_tick2_t xt_timer2_remain ( xt_tick2_t timeout_tick )

计算剩余超时 tick 数（有符号差值，天然回绕安全）

使用 (int32_t)(timeout_tick - now) <= 0 判定到期。在 XT_TIMER2_TIMEOUT_MAX 范围内有符号差值无歧义。

参数

timeout_tick 绝对到期 tick

返回: 剩余 tick 数，0 表示已到期

◆ xt_timer2_set_cb()

xt_err_t xt_timer2_set_cb	(	xt_timer2_t *	t,
		xt_timer2_cb_t	cb )

设置回调函数

参数

t	定时器句柄，不可为 NULL
cb	回调函数，不可为 NULL

返回: XT_EOK 成功; XT_EINVAL t==NULL 或 cb==NULL

◆ xt_timer2_set_user_data()

xt_err_t xt_timer2_set_user_data	(	xt_timer2_t *	t,
		void *	user_data )

设置用户数据

参数

t	定时器句柄，不可为 NULL
user_data	用户数据，可为 NULL

返回: XT_EOK 成功; XT_EINVAL t==NULL

◆ xt_timer2_setup()

xt_err_t xt_timer2_setup	(	xt_timer2_t *	t,
		xt_timer2_cb_t	timer_cb,
		void *	user_data )

配置定时器回调函数和用户数据（不启动）

仅设置 cb_func 和 user_data，不改动链表也不设超时。若 node 未初始化则内部纠正。

参数

t	定时器句柄，不可为 NULL
timer_cb	回调函数，不可为 NULL
user_data	回调透传数据

返回: XT_EOK 成功; XT_EINVAL t==NULL 或 timer_cb==NULL

注解: setup 不应在定时器运行时调用（不确定行为）。

◆ xt_timer2_start()

xt_err_t xt_timer2_start	(	xt_timer2_t *	t,
		xt_tick2_t	tick_timeout )

启动/重启定时器，挂入工作链表

内部计算绝对超时 tick = xt_tick2_get() + tick_timeout。若已在工作链表上则先摘下再重新挂入（等价 restart 语义）。

参数

t	定时器句柄，不可为 NULL
tick_timeout	超时 tick 数（相对）。0 表示下一轮 handler 触发，最大 XT_TIMER2_TIMEOUT_MAX

返回: XT_EOK 成功; XT_EINVAL t==NULL 或 cb_func==NULL 或 timeout 超限

注解: 回调中调 start(self) 合法——先摘后挂，handler 阶段2 结束后阶段3 重新计算。; start 前需确保 cb_func 非空（通过 setup 或 new 设置）。

◆ xt_timer2_stop()

xt_err_t xt_timer2_stop ( xt_timer2_t * t )

停止定时器，从工作链表摘下

cb_func 和 user_data 保持不变，可重新 start 激活。已摘下的定时器再次 stop 幂等返回 XT_EOK。

参数

t	定时器句柄，不可为 NULL

返回: XT_EOK 成功（含幂等情形）; XT_EINVAL node 未初始化

◆ xt_timer2_sys_reset()

void xt_timer2_sys_reset ( void )

重置定时器子系统运行时状态（仅测试/调试用）

清空工作链表和自定义 tick。不触碰内存池。

注解: 调用者应确保未被 handler 并发调用。

◆ xt_timer2_sys_setup()

void xt_timer2_sys_setup	(	xt_timer2_t *	pool_buf,
		size_t	pool_count )

初始化定时器子系统内存池

必须在 xt_timer2_new 之前调用。再次调用则覆盖旧配置： pool_buf==NULL 或 pool_count==0 表示不使用内存池；否则初始化所有槽位为空闲。

参数

pool_buf	预分配数组，每个元素 sizeof(xt_timer2_t)
pool_count	池容量，0 表示不使用内存池

结构体

宏定义

类型定义

函数

详细描述

宏定义说明

◆ XT_TIMER2_DEBUG

◆ XT_TIMER2_FREE_MAGIC

◆ XT_TIMER2_MAGIC

◆ XT_TIMER2_TIMEOUT_MAX

类型定义说明

◆ xt_tick2_t

◆ xt_timer2_cb_t

◆ xt_timer2_t

函数说明

◆ xt_tick2_get()

◆ xt_tick2_inc()

◆ xt_tick2_set()

◆ xt_timer2_delete()

◆ xt_timer2_enable_custom_tick()

◆ xt_timer2_handler()

◆ xt_timer2_is_running()

◆ xt_timer2_new()

◆ xt_timer2_remain()

◆ xt_timer2_set_cb()

◆ xt_timer2_set_user_data()

◆ xt_timer2_setup()

◆ xt_timer2_start()

◆ xt_timer2_stop()

◆ xt_timer2_sys_reset()

◆ xt_timer2_sys_setup()