FreeRTOS 中文参考手册 /5 软件定时器 API

第 5 章 · 原书 257–302 页 · 21 个函数软件定时器 API

Chapter 5 · Software Timer API

软件定时器是一组“到点执行某个回调”的机制,由内核的定时器服务任务(Timer Service Task / daemon task)统一管理。它的本质是:定时器到期后,把回调函数排队给定时器服务任务执行,而不是在中断里直接执行。

这带来一个非常重要的推论:回调函数里绝不能阻塞。它运行在定时器服务任务的上下文里,一旦阻塞,所有定时器都会停摆。同理,回调里调用 xTimerStart() 这类会向定时器命令队列发送命令的 API,也可能因为队列满而死等。

几个必须知道的前提设置(FreeRTOSConfig.h):

配置项作用
configUSE_TIMERS置 1 才启用软件定时器(同时内核会自动创建定时器服务任务)
configTIMER_TASK_PRIORITY定时器服务任务的优先级,决定回调执行的及时性
configTIMER_TASK_STACK_DEPTH定时器服务任务的栈深度
configTIMER_QUEUE_LENGTH定时器命令队列长度,决定同时挂起多少条命令
定时器的所有操作函数(Start / Stop / Reset / ChangePeriod / Delete / PendFunctionCall)都是通过“往定时器命令队列发命令”来实现的,因此都带一个 xTicksToWait 参数——它等的是命令入队,不是定时器到期。这一点是初学者最容易误解的地方。

定时器分两种:单次(One-shot,ufAutoReload = pdFALSE)到期执行一次就停止;周期(Auto-reload,pdTRUE)到期执行后自动重新装载,持续执行。

5.1xTimerChangePeriod()

定时器 timers.h
BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
                                TickType_t xNewPeriod,
                                TickType_t xTicksToWait );

参数

参数方向说明
xTimerin要修改周期的定时器句柄。
xNewPeriodin新的周期,单位为节拍,可用 pdMS_TO_TICKS() 换算。
xTicksToWaitin命令入队时的最长阻塞节拍数。0 表示不等待;portMAX_DELAY 表示无限等待。

返回值

pdPASS 表示命令成功入队;pdFAIL 表示命令队列满(或定时器服务任务尚未启动)。

说明

修改定时器的周期。如果定时器当前正在运行,它会用新周期重新计时;如果当前未运行,本函数会顺带把它启动起来(这一点与 xTimerReset() 类似)。

典型用途:通信超时、看门狗喂狗周期需要运行期调整。

注意

5.2xTimerChangePeriodFromISR()

定时器 · 中断 timers.h
BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
                                       TickType_t xNewPeriod,
                                       BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTimerin要修改周期的定时器句柄。
xNewPeriodin新周期(节拍)。
pxHigherPriorityTaskWokenout初始化为 pdFALSE。若发送命令使定时器服务任务解除阻塞且其优先级更高,则置为 pdTRUE。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

中断里修改定时器周期的版本。

注意

5.3xTimerCreate()

定时器 timers.h
TimerHandle_t xTimerCreate( const char * const pcTimerName,
                              const TickType_t xTimerPeriodInTicks,
                              const UBaseType_t uxAutoReload,
                              void * const pvTimerID,
                              TimerCallbackFunction_t pxCallbackFunction );

参数

参数方向说明
pcTimerNamein定时器名字,纯调试用。
xTimerPeriodInTicksin定时周期,单位节拍。
uxAutoReloadinpdTRUE 为周期定时器(自动重装);pdFALSE 为单次定时器。
pvTimerIDin定时器 ID(void*),可由应用自由使用,例如区分多个共用同一回调的定时器。
pxCallbackFunctionin到期时执行的回调函数,原型为 void vCallback( TimerHandle_t xTimer )。

返回值

创建成功返回定时器句柄;堆内存不足返回 NULL。

说明

创建一个软件定时器。创建出来的定时器初始处于停止(休眠)状态,必须调用 xTimerStart() 才会开始计时。

回调函数在定时器服务任务的上下文中执行,因此不能阻塞,也应尽量短小。

注意

典型用法

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()

定时器 timers.h
TimerHandle_t xTimerCreateStatic( const char * const pcTimerName,
                                    const TickType_t xTimerPeriodInTicks,
                                    const UBaseType_t uxAutoReload,
                                    void * const pvTimerID,
                                    TimerCallbackFunction_t pxCallbackFunction,
                                    StaticTimer_t *pxTimerBuffer );

参数

参数方向说明
pcTimerNamein定时器名字。
xTimerPeriodInTicksin定时周期(节拍)。
uxAutoReloadinpdTRUE 周期 / pdFALSE 单次。
pvTimerIDin定时器 ID。
pxCallbackFunctionin回调函数。
pxTimerBufferin应用提供的 StaticTimer_t 结构,用作定时器控制块。

返回值

创建成功返回句柄;pxTimerBuffer 为 NULL 时返回 NULL。

说明

静态创建软件定时器,控制块由应用提供。

注意

5.5xTimerDelete()

定时器 timers.h
BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );

参数

参数方向说明
xTimerin要删除的定时器句柄。
xTicksToWaitin命令入队时的最长阻塞节拍数。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

删除定时器并释放其内存。删除命令同样是排队执行的——函数返回时定时器可能还没真正被释放。

注意

5.6xTimerGetExpiryTime()

定时器 timers.h
TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

定时器下一次到期的时间,单位是节拍(绝对时间,与 xTaskGetTickCount() 同一基准)。

说明

查询定时器下次到期的绝对时刻。可用于计算“还有多久到期”,或同时管理多个定时器时判断谁先到期。

注意

5.7pcTimerGetName()

定时器 · 调试 timers.h
char * pcTimerGetName( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

定时器的名字(创建时传入的 pcTimerName)。

说明

取回定时器名字,调试日志里打印它比打印句柄直观。

注意

5.8xTimerGetPeriod()

定时器 timers.h
TickType_t xTimerGetPeriod( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

定时器当前配置的周期,单位节拍。

说明

查询定时器周期。可用 pdMS_TO_TICKS() 的逆运算(ticks / configTICK_RATE_HZ)换算成秒。

注意

5.9uxTimerGetReloadMode()

定时器 timers.h
UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

返回 0 表示单次定时器(不自动重装);返回 1 表示周期定时器(自动重装)。

说明

查询定时器的重装模式,用于区分单次与周期。

注意

5.10xTimerGetTimerDaemonTaskHandle()

定时器 timers.h
TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );

返回值

定时器服务任务(daemon task)的句柄。

说明

取回定时器服务任务的句柄。定时器服务任务由内核在启用 configUSE_TIMERS 时自动创建,负责执行到期的回调与处理定时器命令。

常见用途:调整该任务的优先级、查询它的栈水位(排查“回调太重导致栈溢出”)。

注意

5.11pvTimerGetTimerID()

定时器 timers.h
void *pvTimerGetTimerID( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

创建时指定的定时器 ID(void*)。

说明

取回定时器 ID。多个定时器共用一个回调时,靠 ID 区分是谁到期了——这是软件定时器最实用的技巧。

注意

典型用法

void vSharedCallback( TimerHandle_t xTimer )
{
    uint32_t ulId = ( uint32_t ) pvTimerGetTimerID( xTimer );
    switch( ulId )
    {
        case 0: /* 定时器 0 到期 */ break;
        case 1: /* 定时器 1 到期 */ break;
    }
}

5.12xTimerIsTimerActive()

定时器 timers.h
BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );

参数

参数方向说明
xTimerin要查询的定时器句柄。

返回值

pdTRUE 表示定时器正在运行(已启动且未到期/未停止);pdFALSE 表示处于停止状态。

说明

查询定时器当前是否在计时。常用于“避免重复启动”或状态判断。

注意

5.13xTimerPendFunctionCall()

定时器 · 延时执行 timers.h
BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
                                    void *pvParameter1,
                                    uint32_t ulParameter2,
                                    TickType_t xTicksToWait );

参数

参数方向说明
xFunctionToPendin要延后执行的函数,原型为 void vFunc( void *pvParameter1, uint32_t ulParameter2 )。
pvParameter1in传给函数的第一个参数(指针)。
ulParameter2in传给函数的第二个参数(32 位整数)。
xTicksToWaitin命令入队时的最长阻塞节拍数。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

把一个函数“挂”到定时器服务任务上去执行,相当于借用定时器服务任务的上下文做延时处理,而不是等待某个时间点。

它的价值在于:有些事不能在中断里做(耗时或会阻塞),就可以用本函数从 ISR 里“转交”给定时器服务任务执行。

注意

5.14xTimerPendFunctionCallFromISR()

定时器 · 中断 timers.h
BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
                                           void *pvParameter1,
                                           uint32_t ulParameter2,
                                           BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xFunctionToPendin要延后执行的函数。
pvParameter1in第一个参数(指针)。
ulParameter2in第二个参数(32 位整数)。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若命令使定时器服务任务解除阻塞且其优先级更高,则置为 pdTRUE。

返回值

pdPASS 表示入队成功;pdFAIL 表示队列满。

说明

中断版本:从中断里把函数转交给定时器服务任务执行。这是“中断里做不了的重活”的一条退路。

注意

5.15xTimerReset()

定时器 timers.h
BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );

参数

参数方向说明
xTimerin要复位的定时器句柄。
xTicksToWaitin命令入队时的最长阻塞节拍数。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

复位定时器:如果定时器正在运行,重新从 0 开始计时(到期时间 = 现在 + 周期);如果已经停止,则把它启动起来。

典型用途:看门狗/超时场景——每收到一次数据就 reset 一次,只有当“一段时间内没有数据”时定时器才真正到期。

注意

5.16xTimerResetFromISR()

定时器 · 中断 timers.h
BaseType_t xTimerResetFromISR( TimerHandle_t xTimer,
                                BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTimerin要复位的定时器句柄。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;必要时被置为 pdTRUE。

返回值

pdPASS 表示入队成功;pdFAIL 表示队列满。

说明

中断里复位定时器。串口每收到一个字节就 reset 一次帧间隔定时器,是它的经典用法。

注意

5.17vTimerSetTimerID()

定时器 timers.h
void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );

参数

参数方向说明
xTimerin定时器句柄。
pvNewIDin新的 ID 值(void*)。

说明

修改定时器的 ID。多个定时器共用回调时,可用它在运行期切换“身份”,或者在回调里保存上下文指针。

注意

5.18xTimerStart()

定时器 timers.h
BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );

参数

参数方向说明
xTimerin要启动的定时器句柄。
xTicksToWaitin命令入队时的最长阻塞节拍数。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

启动定时器,从当前时刻开始计时。对已在运行的定时器再调用,等价于复位(重新计时)。

注意

典型用法

if( xTimerStart( xTimer, 0 ) != pdPASS )
{
    /* 命令队列满,定时器未启动 */
}

5.19xTimerStartFromISR()

定时器 · 中断 timers.h
BaseType_t xTimerStartFromISR( TimerHandle_t xTimer,
                                BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTimerin要启动的定时器句柄。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;必要时被置为 pdTRUE。

返回值

pdPASS 表示入队成功;pdFAIL 表示队列满。

说明

中断里启动定时器,例如按键中断启动“长按”定时器、外部事件中断启动超时定时器。

注意

5.20xTimerStop()

定时器 timers.h
BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );

参数

参数方向说明
xTimerin要停止的定时器句柄。
xTicksToWaitin命令入队时的最长阻塞节拍数。

返回值

pdPASS 表示命令入队成功;pdFAIL 表示队列满。

说明

停止定时器。停止后它不再到期,直到再次 Start / Reset / ChangePeriod。

注意

5.21xTimerStopFromISR()

定时器 · 中断 timers.h
BaseType_t xTimerStopFromISR( TimerHandle_t xTimer,
                               BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTimerin要停止的定时器句柄。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;必要时被置为 pdTRUE。

返回值

pdPASS 表示入队成功;pdFAIL 表示队列满。

说明

中断里停止定时器。例如按键释放中断停止“长按判定”定时器。

注意