1. TimedActions 库概述TimedActions 是一个轻量级、无依赖的嵌入式定时动作调度库专为资源受限的 MCU如 STM32F0/F1/L0/L1、nRF52、ESP32-C3、RP2040 等设计。其核心目标并非替代操作系统级定时器如 FreeRTOSxTimerCreate或 CMSIS-RTOSosTimerCreate而是提供一种零内存动态分配、确定性执行、可静态配置的机制用于管理周期性、延时性或一次性触发的动作Action。项目摘要中“Simple handler for working with repeated actions”精准概括了其定位它不追求通用性与复杂调度策略如优先级队列、时间轮而聚焦于“重复动作”的可靠、低开销调度。在嵌入式实时系统中“重复动作”场景极为普遍传感器数据周期性采集每 100ms 读取一次温湿度LED 状态指示灯闪烁2Hz 心跳灯串口状态轮询每 500ms 检查 UART 接收缓冲区看门狗喂狗每 8s 执行一次HAL_IWDG_RefreshPWM 占空比动态调节每 20ms 更新一次 TIMx-CCR1传统做法常采用裸机SysTick中断 全局计数器 多个if (tick_count % N 0)判断或在主循环中调用HAL_GetTick()进行时间差比较。前者导致中断服务程序ISR臃肿、可维护性差后者在主循环存在长耗时操作时动作执行时机严重漂移丧失实时性。TimedActions 正是为解决这两类问题而生——它将时间判断逻辑封装为独立、可复用的模块并通过编译期静态数组管理所有动作实例彻底规避运行时内存分配与链表遍历开销。该库不依赖任何 HAL、LL 或 RTOS 组件仅需一个单调递增的毫秒级时间源通常为HAL_GetTick()亦可替换为自定义函数如my_get_ms_counter()。其设计哲学是“显式优于隐式静态优于动态确定性优于灵活性”。所有动作对象在编译期声明生命周期与程序一致所有时间计算基于无符号整型减法天然防溢出所有 API 调用均为纯函数式无副作用便于单元测试与静态分析。2. 核心设计原理与数据结构2.1 时间模型基于无符号整型的相对时间差TimedActions 不维护绝对时间戳而是采用嵌入式领域最鲁棒的时间差模型。其核心假设是系统提供一个单调递增的uint32_t类型毫秒计数器记为now该计数器在 49.7 天后回绕至 0。库内部所有时间比较均使用如下模式if ((uint32_t)(now - action-last_exec) action-interval_ms)此表达式利用了 C 语言中无符号整型减法的模运算特性当now action-last_exec即发生回绕时(now - action-last_exec)自动计算为(0xFFFFFFFF - action-last_exec now 1)结果仍为正确的正向时间差。该技巧无需任何分支判断或特殊处理代码简洁、执行高效单条 ARM Thumb 指令subs即可完成且完全规避了 32 位有符号整型溢出导致的负值陷阱。2.2 动作对象timed_action_t结构体每个待调度的动作由一个timed_action_t结构体实例表示其定义精炼仅包含必要字段字段名类型说明callbackvoid (*)(void*)动作执行时调用的函数指针接收用户传入的user_datauser_datavoid*用户上下文指针供回调函数访问私有数据如传感器句柄、状态结构体interval_msuint32_t动作执行间隔毫秒。若为0则表示仅执行一次one-shot若为非零值则为周期性动作repeatedlast_execuint32_t上次执行时刻毫秒时间戳初始化为0首次执行后更新为now该结构体总大小为 16 字节ARM Cortex-M 架构下内存占用极小。关键设计点在于interval_ms 0的语义明确区别于某些库用UINT32_MAX表示一次性动作此处0更符合直觉且避免了与最大间隔值的混淆。last_exec初始化为0的工程意义在系统启动后首次调用timed_actions_update()时now通常远大于0因此所有interval_ms 0的动作会立即触发首次执行符合“上电即开始周期性工作”的常见需求如 LED 立即开始闪烁。2.3 调度器静态数组与线性扫描TimedActions 调度器本身无状态其行为完全由一组timed_action_t实例数组驱动。用户需在全局作用域静态声明该数组例如#define MAX_ACTIONS 8 static timed_action_t g_actions[MAX_ACTIONS];调度主函数timed_actions_update(uint32_t now)的实现逻辑极其简单遍历整个数组对每个有效动作callback ! NULL执行时间差判断与回调调用。伪代码如下for i from 0 to MAX_ACTIONS-1: if g_actions[i].callback is not NULL: if (now - g_actions[i].last_exec) g_actions[i].interval_ms: call g_actions[i].callback(g_actions[i].user_data) if g_actions[i].interval_ms ! 0: // 周期性动作 g_actions[i].last_exec now else: // 一次性动作执行后注销 g_actions[i].callback NULL此线性扫描策略虽在动作数量极大时100效率略低但对于绝大多数嵌入式应用20 个动作而言其确定性最坏情况执行时间可精确计算、可预测性无缓存未命中风险和代码尺寸优势约 100 字节 Flash远超哈希表或时间轮等复杂结构。且因数组大小MAX_ACTIONS为编译期常量编译器可对其循环进行充分优化如展开、向量化。3. API 接口详解与使用规范3.1 核心 API 函数函数签名作用调用上下文注意事项void timed_actions_init(timed_action_t* actions, uint8_t count)初始化动作数组将所有callback置为NULL系统初始化阶段main()开始处actions必须为静态/全局数组count必须等于数组长度不可为运行时变量void timed_actions_update(uint32_t now)主调度函数遍历数组检查并执行到期动作高频调用点推荐在SysTick_Handler或主循环顶部now必须为单调递增的毫秒计数器此函数应尽可能短小避免在其中执行耗时操作timed_action_t* timed_actions_add(timed_action_t* actions, uint8_t count, void (*cb)(void*), void* user_data, uint32_t interval_ms)向数组中添加一个新动作初始化阶段或运行时动态注册需确保线程安全返回指向新动作的指针若数组满则返回NULLinterval_ms0表示一次性动作void timed_actions_remove(timed_action_t* action)从调度中移除指定动作任意上下文需保证action指针有效仅将action-callback置为NULL不改变数组结构3.2 关键参数与配置说明interval_ms参数取值范围0至UINT32_MAX4294967295 ms ≈ 49.7 天0严格表示“仅执行一次”执行后自动注销。适用于初始化配置、一次性告警、启动自检等场景。1至65535推荐用于高频动作如 1ms~65s。此范围内数值可安全用于 16 位 MCU 的uint16_t临时变量减少 32 位运算开销。65535适用于低频动作如每小时上报数据。需确保now计数器精度足够若HAL_GetTick()基于 1ms SysTick则无问题。user_data参数典型用途传递指向struct的指针封装动作所需的所有私有数据。例如typedef struct { I2C_HandleTypeDef *hi2c; uint8_t sensor_addr; float temperature; } temp_sensor_ctx_t; temp_sensor_ctx_t g_temp_ctx { .hi2c hi2c1, .sensor_addr 0x40 }; timed_actions_add(g_actions, MAX_ACTIONS, read_temperature_cb, g_temp_ctx, 1000);安全边界user_data本身不被库修改但回调函数必须确保其指向的内存区域在整个动作生命周期内有效即不能是栈上局部变量地址。now时间源最佳实践直接使用HAL_GetTick()STM32 HAL 库或xTaskGetTickCount()FreeRTOS。自定义实现若需更高精度或更低功耗可基于硬件定时器如 TIM6实现微秒级计数器但需保证其单调性与毫秒级分辨率兼容。严禁使用clock()POSIX非嵌入式、gettimeofday()Linux、或任何可能被中断打断、非单调的软件计数器。3.3 典型初始化与调度流程以下为一个完整的、生产就绪的初始化模板以 STM32 HAL 为例#include timed_actions.h #define MAX_TIMED_ACTIONS 6 static timed_action_t g_timed_actions[MAX_TIMED_ACTIONS]; // 回调函数声明 static void led_blink_cb(void* user_data); static void sensor_poll_cb(void* user_data); static void watchdog_feed_cb(void* user_data); int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_I2C1_Init(); // 1. 初始化 TimedActions 数组 timed_actions_init(g_timed_actions, MAX_TIMED_ACTIONS); // 2. 注册周期性动作 timed_actions_add(g_timed_actions, MAX_TIMED_ACTIONS, led_blink_cb, NULL, 500); // LED 每 500ms 闪烁 timed_actions_add(g_timed_actions, MAX_TIMED_ACTIONS, sensor_poll_cb, g_sensor_ctx, 100); // 传感器每 100ms 采样 timed_actions_add(g_timed_actions, MAX_TIMED_ACTIONS, watchdog_feed_cb, NULL, 8000); // 看门狗每 8s 喂狗 // 3. 启动 SysTick1ms 中断 HAL_SYSTICK_Config(HAL_RCC_GetHCLKFreq() / 1000); while (1) { // 4. 主循环中调用调度器推荐方式 timed_actions_update(HAL_GetTick()); // 其他业务逻辑... do_background_tasks(); } } // SysTick 中断服务程序备选调度位置需极简 void SysTick_Handler(void) { HAL_IncTick(); // 此处仅调用 timed_actions_update(HAL_GetTick()) 是危险的 // 因为 HAL_GetTick() 内部可能有临界区且 ISR 中执行回调可能违反实时约束。 // 强烈建议在主循环中调度。 }4. 与主流嵌入式生态的集成实践4.1 与 STM32 HAL 库协同TimedActions 与 HAL 库天然契合因其不干涉任何外设初始化与中断配置。典型集成点包括UART 状态轮询避免在HAL_UART_RxCpltCallback中处理复杂逻辑改用 TimedActions 每 10ms 检查huart-RxXferCount并触发解析。ADC 连续转换控制在HAL_ADC_ConvCpltCallback中仅设置标志位由 TimedActions 每 100ms 读取hadc-Instance-DR并计算平均值。PWM 占空比平滑调节定义pwm_ctx_t结构体包含目标占空比、当前占空比、步进值回调函数每次增加current_duty step并调用__HAL_TIM_SET_COMPARE(htim3, TIM_CHANNEL_1, current_duty)。4.2 与 FreeRTOS 的共存策略TimedActions 并非 RTOS 定时器的竞争者而是互补工具。其优势在于超低延迟与确定性。推荐组合模式高频率、低延迟动作10ms交由 TimedActions 在SysTick_Handler或主循环中处理如电机 PID 控制输出、高速编码器计数。低频率、高可靠性动作100ms交由 FreeRTOS Timer 处理如网络心跳包发送、文件系统日志刷写利用其任务优先级与阻塞 API。若需在 FreeRTOS 任务中安全调用 TimedActions只需确保timed_actions_update()调用不引发阻塞即可void app_task(void const * argument) { for(;;) { timed_actions_update(xTaskGetTickCount()); // 使用 RTOS Tick osDelay(1); // 保持任务调度 } }4.3 与 LLLow-Layer库的深度结合对于追求极致性能的应用可将 TimedActions 与 LL 库结合绕过 HAL 的抽象层开销。例如直接操作TIM2-CNT获取微秒级时间戳作为now或在回调中使用LL_TIM_OC_SetCompareCH1(TIM2, compare_val)设置 PWM 比较值。此时需自行保证now的单调性与分辨率。5. 工程实践故障排查与性能优化5.1 常见问题诊断动作不执行检查timed_actions_init()是否被调用确认timed_actions_update()被高频调用HAL_GetTick()值是否持续增长使用调试器观察g_actions[i].callback是否为NULL可能被误注销验证interval_ms是否被错误赋值为0一次性动作。动作执行频率异常测量HAL_GetTick()的实际增量是否稳定排除 SysTick 配置错误检查回调函数是否耗时过长导致下次update()调用时now已远超last_exec interval_ms从而累积延迟若使用SysTick_Handler调用update()确认回调中未调用任何可能触发 PendSV 或 SVC 的 HAL 函数如HAL_Delay。内存越界风险timed_actions_add()的count参数若小于实际数组长度会导致后续动作写入非法内存。强烈建议使用宏定义数组长度并在add()调用中直接传入该宏杜绝硬编码#define ACTION_ARRAY_SIZE 5 static timed_action_t g_actions[ACTION_ARRAY_SIZE]; timed_actions_add(g_actions, ACTION_ARRAY_SIZE, cb, data, 1000);5.2 性能优化技巧编译期数组大小优化根据实际需求精确设定MAX_ACTIONS。每个未使用的数组元素消耗 16 字节 RAM对 RAM 紧张的 MCU如 STM32L0至关重要。回调函数内联对极简回调如HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5)可声明为static inline消除函数调用开销。时间源精度提升若应用要求亚毫秒级精度可基于DWT_CYCCNTCortex-M DWT Cycle Counter实现微秒级now需注意其在睡眠模式下的行为。批量更新优化若多个动作具有相同interval_ms可将其合并为一个动作在回调中依次调用各子回调减少数组遍历次数。6. 源码级实现逻辑剖析以timed_actions_update()的核心循环为例其汇编级效率是设计精髓所在。在 ARM GCC-O2优化下对单个动作的判断逻辑可编译为ldr r0, [r4, #0] load action-callback cbz r0, skip if callback NULL, skip ldr r1, [r4, #4] load action-user_data ldr r2, [r4, #8] load action-interval_ms ldr r3, [r4, #12] load action-last_exec subs r5, r6, r3 r5 now - last_exec (unsigned) cmp r5, r2 compare with interval_ms blo skip if now last_exec (overflow), branch bhs exec if interval_ms, execute skip: ... exec: blx r0 call callback(user_data) cmp r2, #0 check if interval_ms 0 beq unregister if yes, unregister str r6, [r4, #12] else, update last_exec now关键洞察subs指令同时完成减法与状态标志更新blo/bhs分支直接基于减法结果无额外比较指令。所有内存访问ldr均为固定偏移利于 CPU 预取与流水线。整个循环体含分支在 Cortex-M4 上典型执行时间为 12-18 个周期远低于任何基于链表或动态内存的调度器。这种对底层硬件特性的精准把握正是 TimedActions 在资源受限场景下不可替代的价值所在——它不是功能最全的库但一定是工程师在深夜调试时最值得信赖的那个 16 字节结构体与 100 字节函数。