第 5 章 · 原书 257–302 页 · 21 个函数软件定时器 API
软件定时器是一组“到点执行某个回调”的机制,由内核的定时器服务任务(Timer Service Task / daemon task)统一管理。它的本质是:定时器到期后,把回调函数排队给定时器服务任务执行,而不是在中断里直接执行。
这带来一个非常重要的推论:回调函数里绝不能阻塞。它运行在定时器服务任务的上下文里,一旦阻塞,所有定时器都会停摆。同理,回调里调用 xTimerStart() 这类会向定时器命令队列发送命令的 API,也可能因为队列满而死等。
几个必须知道的前提设置(FreeRTOSConfig.h):
| 配置项 | 作用 |
|---|---|
| configUSE_TIMERS | 置 1 才启用软件定时器(同时内核会自动创建定时器服务任务) |
| configTIMER_TASK_PRIORITY | 定时器服务任务的优先级,决定回调执行的及时性 |
| configTIMER_TASK_STACK_DEPTH | 定时器服务任务的栈深度 |
| configTIMER_QUEUE_LENGTH | 定时器命令队列长度,决定同时挂起多少条命令 |
定时器分两种:单次(One-shot,ufAutoReload = pdFALSE)到期执行一次就停止;周期(Auto-reload,pdTRUE)到期执行后自动重新装载,持续执行。
5.1xTimerChangePeriod()
BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
TickType_t xNewPeriod,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要修改周期的定时器句柄。 |
| xNewPeriod | in | 新的周期,单位为节拍,可用 pdMS_TO_TICKS() 换算。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。 |
返回值
pdPASS 表示命令成功入队;pdFAIL 表示命令队列满(或定时器服务任务尚未启动)。
说明
修改定时器的周期。如果定时器当前正在运行,它会用新周期重新计时;如果当前未运行,本函数会顺带把它启动起来(这一点与 xTimerReset() 类似)。
典型用途:通信超时、看门狗喂狗周期需要运行期调整。
注意
- configUSE_TIMERS 必须为 1。
- xTicksToWait 等的是命令入队,不是定时器到期。
- 在定时器回调里调用本函数是危险的(命令队列可能满而死等)。
5.2xTimerChangePeriodFromISR()
BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
TickType_t xNewPeriod,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要修改周期的定时器句柄。 |
| xNewPeriod | in | 新周期(节拍)。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE。若发送命令使定时器服务任务解除阻塞且其优先级更高,则置为 pdTRUE。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
中断里修改定时器周期的版本。
注意
- 中断里不阻塞,所以没有 xTicksToWait。
- 命令无法入队时只能失败,注意队列长度要留余量。
5.3xTimerCreate()
TimerHandle_t xTimerCreate( const char * const pcTimerName,
const TickType_t xTimerPeriodInTicks,
const UBaseType_t uxAutoReload,
void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pcTimerName | in | 定时器名字,纯调试用。 |
| xTimerPeriodInTicks | in | 定时周期,单位节拍。 |
| uxAutoReload | in | pdTRUE 为周期定时器(自动重装);pdFALSE 为单次定时器。 |
| pvTimerID | in | 定时器 ID(void*),可由应用自由使用,例如区分多个共用同一回调的定时器。 |
| pxCallbackFunction | in | 到期时执行的回调函数,原型为 void vCallback( TimerHandle_t xTimer )。 |
返回值
创建成功返回定时器句柄;堆内存不足返回 NULL。
说明
创建一个软件定时器。创建出来的定时器初始处于停止(休眠)状态,必须调用 xTimerStart() 才会开始计时。
回调函数在定时器服务任务的上下文中执行,因此不能阻塞,也应尽量短小。
注意
- configUSE_TIMERS 必须为 1。
- 若还要按 ID 区分回调来源,创建时给不同 ID,回调里用 pvTimerGetTimerID() 取回判断。
- 创建不代表启动;忘记 Start 是最常见的“定时器不工作”原因。
典型用法
static void vTimerCallback( TimerHandle_t xTimer )
{
/* 定时到期要做的事。不要阻塞、不要死等。 */
}
TimerHandle_t xTimer = xTimerCreate( "MyTimer",
pdMS_TO_TICKS( 100 ),
pdTRUE, /* 周期定时器 */
( void * ) 0, /* ID */
vTimerCallback );
xTimerStart( xTimer, 0 );
5.4xTimerCreateStatic()
TimerHandle_t xTimerCreateStatic( const char * const pcTimerName,
const TickType_t xTimerPeriodInTicks,
const UBaseType_t uxAutoReload,
void * const pvTimerID,
TimerCallbackFunction_t pxCallbackFunction,
StaticTimer_t *pxTimerBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pcTimerName | in | 定时器名字。 |
| xTimerPeriodInTicks | in | 定时周期(节拍)。 |
| uxAutoReload | in | pdTRUE 周期 / pdFALSE 单次。 |
| pvTimerID | in | 定时器 ID。 |
| pxCallbackFunction | in | 回调函数。 |
| pxTimerBuffer | in | 应用提供的 StaticTimer_t 结构,用作定时器控制块。 |
返回值
创建成功返回句柄;pxTimerBuffer 为 NULL 时返回 NULL。
说明
静态创建软件定时器,控制块由应用提供。
注意
- configUSE_TIMERS 与 configSUPPORT_STATIC_ALLOCATION 必须都为 1。
- 启用静态分配后,定时器服务任务的栈与 TCB 也要由应用通过 vApplicationGetTimerTaskMemory() 提供。
5.5xTimerDelete()
BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要删除的定时器句柄。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
删除定时器并释放其内存。删除命令同样是排队执行的——函数返回时定时器可能还没真正被释放。
注意
- 删除后不要继续使用该句柄。
- 不要在定时器自己的回调里删除自己(会用到已经失效的上下文,且易触发命令队列满)。
5.6xTimerGetExpiryTime()
TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
定时器下一次到期的时间,单位是节拍(绝对时间,与 xTaskGetTickCount() 同一基准)。
说明
查询定时器下次到期的绝对时刻。可用于计算“还有多久到期”,或同时管理多个定时器时判断谁先到期。
注意
- 返回值是节拍计数,不是剩余时间;剩余时间 = 返回值 - xTaskGetTickCount()。
- 定时器处于停止状态时该值无意义。
5.7pcTimerGetName()
char * pcTimerGetName( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
定时器的名字(创建时传入的 pcTimerName)。
说明
取回定时器名字,调试日志里打印它比打印句柄直观。
注意
- 返回的是内部字符串指针,不要修改或释放。
5.8xTimerGetPeriod()
TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
定时器当前配置的周期,单位节拍。
说明
查询定时器周期。可用 pdMS_TO_TICKS() 的逆运算(ticks / configTICK_RATE_HZ)换算成秒。
注意
- 返回值是配置周期,不是剩余时间;要看剩余时间用 xTimerGetExpiryTime()。
5.9uxTimerGetReloadMode()
UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
返回 0 表示单次定时器(不自动重装);返回 1 表示周期定时器(自动重装)。
说明
查询定时器的重装模式,用于区分单次与周期。
注意
- 返回值是数值 0/1,而不是 pdTRUE/pdFALSE 常量,虽然语义等价。
5.10xTimerGetTimerDaemonTaskHandle()
TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
返回值
定时器服务任务(daemon task)的句柄。
说明
取回定时器服务任务的句柄。定时器服务任务由内核在启用 configUSE_TIMERS 时自动创建,负责执行到期的回调与处理定时器命令。
常见用途:调整该任务的优先级、查询它的栈水位(排查“回调太重导致栈溢出”)。
注意
- configUSE_TIMERS 必须为 1。
- 若该任务被长期占用(例如回调里有阻塞或耗时操作),所有定时器都会延迟。
5.11pvTimerGetTimerID()
void *pvTimerGetTimerID( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
创建时指定的定时器 ID(void*)。
说明
取回定时器 ID。多个定时器共用一个回调时,靠 ID 区分是谁到期了——这是软件定时器最实用的技巧。
注意
- ID 只是一个渡让给应用使用的指针,内核不关心它指向什么(也可以直接存一个整数,强制转换即可)。
- 运行期可用 vTimerSetTimerID() 修改。
典型用法
void vSharedCallback( TimerHandle_t xTimer )
{
uint32_t ulId = ( uint32_t ) pvTimerGetTimerID( xTimer );
switch( ulId )
{
case 0: /* 定时器 0 到期 */ break;
case 1: /* 定时器 1 到期 */ break;
}
}
5.12xTimerIsTimerActive()
BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要查询的定时器句柄。 |
返回值
pdTRUE 表示定时器正在运行(已启动且未到期/未停止);pdFALSE 表示处于停止状态。
说明
查询定时器当前是否在计时。常用于“避免重复启动”或状态判断。
注意
- 返回值是瞬时状态,随后可能因到期而改变。
- 定时器在启动后的那一刻起就是 active,直到到期(单次)或被停止。
5.13xTimerPendFunctionCall()
BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
void *pvParameter1,
uint32_t ulParameter2,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xFunctionToPend | in | 要延后执行的函数,原型为 void vFunc( void *pvParameter1, uint32_t ulParameter2 )。 |
| pvParameter1 | in | 传给函数的第一个参数(指针)。 |
| ulParameter2 | in | 传给函数的第二个参数(32 位整数)。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
把一个函数“挂”到定时器服务任务上去执行,相当于借用定时器服务任务的上下文做延时处理,而不是等待某个时间点。
它的价值在于:有些事不能在中断里做(耗时或会阻塞),就可以用本函数从 ISR 里“转交”给定时器服务任务执行。
注意
- configUSE_TIMERS 与 INCLUDE_xTimerPendFunctionCall 必须都为 1。
- 被挂起的函数同样不能阻塞——它跑在定时器服务任务里。
- 中断里请用 xTimerPendFunctionCallFromISR()。
5.14xTimerPendFunctionCallFromISR()
BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
void *pvParameter1,
uint32_t ulParameter2,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xFunctionToPend | in | 要延后执行的函数。 |
| pvParameter1 | in | 第一个参数(指针)。 |
| ulParameter2 | in | 第二个参数(32 位整数)。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若命令使定时器服务任务解除阻塞且其优先级更高,则置为 pdTRUE。 |
返回值
pdPASS 表示入队成功;pdFAIL 表示队列满。
说明
中断版本:从中断里把函数转交给定时器服务任务执行。这是“中断里做不了的重活”的一条退路。
注意
- configUSE_TIMERS 与 INCLUDE_xTimerPendFunctionCall 必须都为 1。
- 与信号量/队列相比,它不需要额外创建对象,比较省 RAM。
- pxHigherPriorityTaskWoken 需由 portYIELD_FROM_ISR() 处理。
5.15xTimerReset()
BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要复位的定时器句柄。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
复位定时器:如果定时器正在运行,重新从 0 开始计时(到期时间 = 现在 + 周期);如果已经停止,则把它启动起来。
典型用途:看门狗/超时场景——每收到一次数据就 reset 一次,只有当“一段时间内没有数据”时定时器才真正到期。
注意
- configUSE_TIMERS 必须为 1。
- 单次定时器 + Reset 可以实现“无活动超时”检测,比反复 Stop/Start 更自然。
5.16xTimerResetFromISR()
BaseType_t xTimerResetFromISR( TimerHandle_t xTimer,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要复位的定时器句柄。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;必要时被置为 pdTRUE。 |
返回值
pdPASS 表示入队成功;pdFAIL 表示队列满。
说明
中断里复位定时器。串口每收到一个字节就 reset 一次帧间隔定时器,是它的经典用法。
注意
- 中断里不阻塞,无超时参数。
- 频繁在中断里 reset 会增大定时器命令队列的压力,注意队列长度。
5.17vTimerSetTimerID()
void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 定时器句柄。 |
| pvNewID | in | 新的 ID 值(void*)。 |
说明
修改定时器的 ID。多个定时器共用回调时,可用它在运行期切换“身份”,或者在回调里保存上下文指针。
注意
- 只保存指针,不管理所指对象的内存。
5.18xTimerStart()
BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要启动的定时器句柄。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
启动定时器,从当前时刻开始计时。对已在运行的定时器再调用,等价于复位(重新计时)。
注意
- configUSE_TIMERS 必须为 1。
- 命令是异步的:函数返回 pdPASS 只代表命令已入队,定时器真正启动稍后由服务任务完成。
- 若在调度器启动前创建定时器并 Start,命令会一直等到调度器启动后才被处理。
典型用法
if( xTimerStart( xTimer, 0 ) != pdPASS )
{
/* 命令队列满,定时器未启动 */
}
5.19xTimerStartFromISR()
BaseType_t xTimerStartFromISR( TimerHandle_t xTimer,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要启动的定时器句柄。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;必要时被置为 pdTRUE。 |
返回值
pdPASS 表示入队成功;pdFAIL 表示队列满。
说明
中断里启动定时器,例如按键中断启动“长按”定时器、外部事件中断启动超时定时器。
注意
- 中断里不阻塞。
- 注意命令队列的容量:多个中断源同时操作定时器时容易满。
5.20xTimerStop()
BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要停止的定时器句柄。 |
| xTicksToWait | in | 命令入队时的最长阻塞节拍数。 |
返回值
pdPASS 表示命令入队成功;pdFAIL 表示队列满。
说明
停止定时器。停止后它不再到期,直到再次 Start / Reset / ChangePeriod。
注意
- configUSE_TIMERS 必须为 1。
- 停止命令不会撤销“已经排队等待执行”的回调——如果回调已经挂在服务任务上,仍会执行一次。
5.21xTimerStopFromISR()
BaseType_t xTimerStopFromISR( TimerHandle_t xTimer,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTimer | in | 要停止的定时器句柄。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;必要时被置为 pdTRUE。 |
返回值
pdPASS 表示入队成功;pdFAIL 表示队列满。
说明
中断里停止定时器。例如按键释放中断停止“长按判定”定时器。
注意
- 中断里不阻塞。
- 同样无法撤销已经排队待执行的回调。