【产出】 > 用 FreeRTOS 软件定时器实现延时动作和周期动作:会创建一次性和自动重载定时器、启动停止复位、修改周期,理解回调为什么跑在守护任务里、命令队列满了会怎样,并能正确设置相关配置项。
【版本】 > 依据 FreeRTOS 内核官方手册(FreeRTOS Kernel Book)第 6 章 Software Timer Management 和内核源码
timers.h编写,适用于 FreeRTOS V10 / V11,与具体芯片无关。
一、软件定时器是什么
软件定时器让一个函数在将来某个时刻执行一次,或者按固定周期反复执行。被执行的函数叫定时器的回调函数。
它由 FreeRTOS 内核实现,不占用任何硬件定时器,和芯片上的 TIM 外设没有关系。官方手册说明,定时器在回调真正执行之前不消耗处理时间。
和"写一个任务、里面 vTaskDelay()"相比:
| 软件定时器 | 专门的周期任务 | |
|---|---|---|
| 内存 | 每个定时器只有一个控制结构,所有回调共用一个任务的栈 | 每个任务一份栈和任务控制块 |
| 能否阻塞 | 回调不能阻塞 | 可以 |
| 精度 | 节拍级,受守护任务优先级影响 | 节拍级,受任务自身优先级影响 |
| 适合 | 超时、去抖、LED 闪烁、看门狗喂狗提醒这类短小动作 | 要等待数据、执行时间长的处理 |
精度方面要注意:软件定时器以系统节拍为单位计时,分辨率不会好于一个节拍周期,需要微秒级精度的场合仍然用硬件定时器。
二、开启软件定时器功能
- 把
timers.c加入工程编译(CubeMX 生成的 FreeRTOS 中间件已经包含)。 - 在
FreeRTOSConfig.h里配置:
#define configUSE_TIMERS 1
#define configTIMER_TASK_PRIORITY ( configMAX_PRIORITIES - 1 )
#define configTIMER_QUEUE_LENGTH 10
#define configTIMER_TASK_STACK_DEPTH 256
| 配置项 | 含义 |
|---|---|
configUSE_TIMERS | 设为 1 才启用软件定时器 |
configTIMER_TASK_PRIORITY | 守护任务的优先级,范围 0 到 configMAX_PRIORITIES - 1 |
configTIMER_QUEUE_LENGTH | 定时器命令队列最多能积压多少条未处理的命令 |
configTIMER_TASK_STACK_DEPTH | 守护任务的栈大小,单位是字,不是字节 |
上面的数值是示例,不是官方推荐值。优先级和栈的取法见第五节。
三、一次性与自动重载
| 类型 | 到期后 | 典型用途 |
|---|---|---|
| 一次性(one-shot) | 执行一次回调,进入休眠态,不会自己重启 | 超时判断、延时关灯、按键去抖 |
| 自动重载(auto-reload) | 执行回调后自动重新开始计时,周期性执行 | LED 闪烁、周期采样触发、心跳包 |
定时器只有两种状态:
- 休眠(Dormant):定时器存在,有句柄,但不在计时,回调不会执行。刚创建的定时器就处在这个状态。
- 运行(Running):从启动或最近一次复位开始,经过一个周期后执行回调。
"周期"指从定时器启动到回调执行之间的时间。例如周期 6 个节拍的一次性定时器在 t1 启动,回调在 t7 执行一次;周期 5 个节拍的自动重载定时器在 t1 启动,回调在 t6、t11、t16……执行。
四、创建和启动
xTimerCreate
TimerHandle_t xTimerCreate(const char * const pcTimerName,
const TickType_t xTimerPeriodInTicks,
const BaseType_t xAutoReload,
void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction);
| 参数 | 说明 |
|---|---|
pcTimerName | 名字,内核不用,只为调试时好认 |
xTimerPeriodInTicks | 周期,单位是节拍,可用 pdMS_TO_TICKS() 换算;不能为 0 |
xAutoReload | pdTRUE 自动重载,pdFALSE 一次性 |
pvTimerID | 定时器 ID 的初始值,void * 类型,应用自由使用 |
pxCallbackFunction | 回调函数 |
| 返回值 | NULL 表示堆不够创建失败;否则是定时器句柄 |
回调函数原型固定:
void vMyTimerCallback(TimerHandle_t xTimer);
定时器可以在调度器启动前创建,也可以在任务里创建。不想走动态内存时用 xTimerCreateStatic()。
xTimerStart 和其他控制函数
BaseType_t xTimerStart(TimerHandle_t xTimer, TickType_t xTicksToWait);
BaseType_t xTimerStop(TimerHandle_t xTimer, TickType_t xTicksToWait);
BaseType_t xTimerReset(TimerHandle_t xTimer, TickType_t xTicksToWait);
BaseType_t xTimerChangePeriod(TimerHandle_t xTimer, TickType_t xNewPeriod,
TickType_t xTicksToWait);
BaseType_t xTimerDelete(TimerHandle_t xTimer, TickType_t xTicksToWait);
| 函数 | 作用 |
|---|---|
xTimerStart() | 启动休眠的定时器;对运行中的定时器调用等于复位 |
xTimerStop() | 停止,进入休眠态 |
xTimerReset() | 重新开始计时,到期时间从复位时刻重新算;也能启动休眠的定时器 |
xTimerChangePeriod() | 改周期。运行中的定时器从调用时刻按新周期重算到期时间;休眠的定时器会被直接启动 |
xTimerDelete() | 删除定时器 |
这些函数的 xTicksToWait 不是定时时间,而是命令队列满时调用者最多等多久,第五节解释。返回 pdPASS 只表示命令成功放进了命令队列;返回 pdFAIL 表示等到超时队列仍然是满的。
在调度器启动前调用 xTimerStart() 是允许的,此时 xTicksToWait 被忽略,定时器在调度器启动时才真正开始计时。
【注意】 > 以上函数都不能在中断里调用。中断里用
xTimerStartFromISR()、xTimerStopFromISR()、xTimerResetFromISR()、xTimerChangePeriodFromISR(),它们最后一个参数是pxHigherPriorityTaskWoken,用法见本专区"中断与任务通知"一篇。
示例:一个周期定时器加一个一次性定时器
#include "FreeRTOS.h"
#include "task.h"
#include "timers.h"
#include "main.h"
static TimerHandle_t xBlinkTimer;
static TimerHandle_t xTimeoutTimer;
static void vBlinkCallback(TimerHandle_t xTimer)
{
(void)xTimer;
HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin); /* 动作短小,不阻塞 */
}
static void vTimeoutCallback(TimerHandle_t xTimer)
{
(void)xTimer;
/* 例如:通信超时,置错误标志或通知某个任务 */
}
void app_timers_init(void)
{
xBlinkTimer = xTimerCreate("blink", pdMS_TO_TICKS(500), pdTRUE,
NULL, vBlinkCallback);
xTimeoutTimer = xTimerCreate("timeout", pdMS_TO_TICKS(3000), pdFALSE,
NULL, vTimeoutCallback);
configASSERT(xBlinkTimer && xTimeoutTimer);
/* 调度器启动前调用,阻塞时间被忽略,填 0 */
xTimerStart(xBlinkTimer, 0);
xTimerStart(xTimeoutTimer, 0);
}
在 main() 里先调用 app_timers_init(),再 vTaskStartScheduler()。
五、守护任务和命令队列
回调在哪里执行
所有软件定时器的回调都在同一个任务里执行:RTOS 守护任务(daemon task),以前叫定时器服务任务(timer service task)。它是调度器启动时自动创建的普通任务,优先级和栈大小就是前面的 configTIMER_TASK_PRIORITY 和 configTIMER_TASK_STACK_DEPTH。
命令怎么传过去
你调用 xTimerStart() 时,函数本身并不操作定时器,而是把一条"启动某定时器"的命令写进定时器命令队列,由守护任务取出执行。命令队列也是调度器启动时自动创建的,长度是 configTIMER_QUEUE_LENGTH。
应用任务 ──xTimerStart()──> [ 定时器命令队列 ] ──> 守护任务 ──> 执行命令 / 调用到期回调
由此可以解释 xTicksToWait 的含义:命令队列满了,调用者要不要阻塞等守护任务腾出空位。
守护任务优先级的影响
守护任务和其他任务一样按优先级调度,只有它是就绪态中优先级最高的任务时,才会处理命令或执行回调。官方手册对比了两种情况:
| 守护任务优先级 | 调用 xTimerStart() 时 |
|---|---|
| 低于调用者 | 命令写进队列后调用者继续运行,直到调用者阻塞,守护任务才去处理命令 |
| 高于调用者 | 守护任务立即抢占调用者处理命令,处理完 xTimerStart() 才返回 |
这不会影响定时精度:每条命令都带有发送时刻的时间戳。周期 10 个节拍的定时器,到期时间从命令发出时算起,而不是从守护任务处理命令时算起。
但守护任务优先级会影响回调执行的及时性。定时器到期时,如果有更高优先级的任务正在运行,回调要等它让出 CPU 才能执行。需要回调准时的话,把 configTIMER_TASK_PRIORITY 设得较高。
命令队列长度怎么定
命令队列满的典型情况是:守护任务优先级低,而某个高优先级任务在一段时间内连续调用很多次定时器 API。调用时 xTicksToWait 填 0 就会直接失败。处理办法:
- 检查返回值,失败时重试或记录;
- 加大
configTIMER_QUEUE_LENGTH; - 提高守护任务优先级,让命令及时被消化。
中断里频繁调用 xTimerResetFromISR() 也会占用命令队列,同样要检查返回值。
栈大小
所有回调共用守护任务的栈,栈大小要按最耗栈的那个回调来定。回调里调用 printf、格式化浮点数,栈很快就不够了。可以用 xTimerGetTimerDaemonTaskHandle() 拿到守护任务句柄,再用 uxTaskGetStackHighWaterMark() 查看剩余栈。
六、回调里不能阻塞
回调运行在守护任务里,回调阻塞就是守护任务阻塞。守护任务阻塞期间,所有定时器的回调都无法执行,命令也无法处理。
官方手册的规则:
| 能否在回调里调用 | 说明 |
|---|---|
vTaskDelay() | 不能,它一定会阻塞 |
xQueueReceive()、xSemaphoreTake() 等 | 只能用 xTicksToWait = 0,即不等待 |
xQueueSend() 给其他任务 | 可以,xTicksToWait 填 0 |
xTimerStart() 等操作定时器 | 可以,xTicksToWait 填 0(回调本身就在守护任务里,等也等不到它腾出队列) |
| 耗时的计算、长时间外设操作 | 不建议,会推迟其他定时器 |
回调里有较重的工作时,用任务通知或队列交给一个普通任务去做,回调只负责"到点了"这件事。
七、定时器 ID:一个回调服务多个定时器
每个定时器都有一个 void * 类型的 ID,创建时给初值,之后用 vTimerSetTimerID() 修改、pvTimerGetTimerID() 读取。这两个函数直接访问定时器,不经过命令队列。
多个定时器共用一个回调时,用 ID 区分是谁到期,或者存放每个定时器自己的数据。下面让 3 路 LED 各自按不同周期闪烁,共用一个回调:
#include "FreeRTOS.h"
#include "timers.h"
#include "main.h"
typedef struct {
GPIO_TypeDef *port;
uint16_t pin;
} LedCtx_t;
static LedCtx_t xLeds[3] = {
{ LED1_GPIO_Port, LED1_Pin },
{ LED2_GPIO_Port, LED2_Pin },
{ LED3_GPIO_Port, LED3_Pin },
};
static void vLedCallback(TimerHandle_t xTimer)
{
LedCtx_t *ctx = (LedCtx_t *)pvTimerGetTimerID(xTimer);
HAL_GPIO_TogglePin(ctx->port, ctx->pin);
}
void leds_start(void)
{
static const uint32_t periods_ms[3] = { 200, 500, 1000 };
for (int i = 0; i < 3; i++) {
TimerHandle_t t = xTimerCreate("led", pdMS_TO_TICKS(periods_ms[i]),
pdTRUE, &xLeds[i], vLedCallback);
configASSERT(t != NULL);
xTimerStart(t, 0);
}
}
八、用复位实现"无操作后自动关闭"
官方手册用复位举的例子:按键时点亮背光,若干秒内没有再按键就关闭。每次按键都调用一次 xTimerReset(),到期时间从最后一次按键重新算起,一次性定时器只会在"最后一次按键之后"到期。
static TimerHandle_t xBacklightTimer;
static void vBacklightOff(TimerHandle_t xTimer)
{
(void)xTimer;
HAL_GPIO_WritePin(BL_GPIO_Port, BL_Pin, GPIO_PIN_RESET);
}
void backlight_init(void)
{
xBacklightTimer = xTimerCreate("bl", pdMS_TO_TICKS(5000), pdFALSE,
NULL, vBacklightOff);
configASSERT(xBacklightTimer != NULL);
}
/* 在按键处理任务里调用 */
void on_key_pressed(void)
{
HAL_GPIO_WritePin(BL_GPIO_Port, BL_Pin, GPIO_PIN_SET);
xTimerReset(xBacklightTimer, pdMS_TO_TICKS(10)); /* 休眠态时也会被启动 */
}
同样的结构可以用于按键去抖、通信超时、"空闲 N 秒进入低功耗"等场合。
九、常见问题
| 现象 | 原因与处理 |
|---|---|
编译报 xTimerCreate 未定义 | configUSE_TIMERS 不是 1,或 timers.c 没有参与编译 |
创建返回 NULL | 堆不够;或周期填了 0(官方规定周期不能为 0) |
| 回调从来不执行 | 定时器创建后没有启动;或守护任务优先级太低,被一直运行的高优先级任务压住 |
| 某个回调里加了延时后,其他定时器全部变慢或停止 | 回调阻塞了守护任务,改为通知普通任务处理 |
xTimerStart 返回 pdFAIL | 命令队列满;加大 configTIMER_QUEUE_LENGTH 或提高守护任务优先级 |
| 守护任务栈溢出 | 栈按最耗栈的回调定;printf 移出回调 |
| 周期显示比设置的长 | 周期换算成节拍时被截断,或回调被高优先级任务推迟;检查 configTICK_RATE_HZ |
参考资料
- FreeRTOS 内核官方手册 第 6 章 Software Timer Management:https://github.com/FreeRTOS/FreeRTOS-Kernel-Book/blob/main/ch06.md
- FreeRTOS 内核源码 timers.h:https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/include/timers.h
评价 (0)