跳转至
项目
版本
全文检索

Timer

Timer 提供通用硬件定时器功能，支持创建与管理软件定时器、设置单次或周期性定时超时回调、获取硬件定时器最大可设置的延时时间，并可选支持高精度专用定时与低功耗挂起/恢复特性。

模块公共头文件

#include "include/driver/timer.h"

接口清单

接口名称 功能简述
uapi_timer_init 初始化定时器模块
uapi_timer_adapter 适配指定硬件定时器索引并注册中断
uapi_timer_deinit 去初始化定时器模块
uapi_timer_create 在指定硬件索引下创建软件定时器并返回句柄
uapi_timer_delete 删除指定的软件定时器
uapi_timer_get_max_us 获取硬件定时器最大可设置延时时间，单位 us
uapi_timer_start 启动指定定时器并注册超时回调
uapi_timer_stop 停止指定定时器
uapi_timer_get_current_time_us 获取底层硬件定时器当前时间，单位 us
uapi_timer_start_high_precision 启动高精度专用定时器
uapi_timer_reset_high_precision 重启高精度专用定时器
uapi_timer_stop_high_precision 停止高精度专用定时器
uapi_timer_suspend 挂起定时器模块
uapi_timer_resume 恢复定时器模块

Functions

uapi_timer_init 

errcode_t uapi_timer_init(void)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 初始化定时器模块的全局管理资源。
  • 为各硬件定时器索引准备软件定时器链表。
  • 重复调用时若模块已初始化则直接返回成功。

前置条件

  • 调用时序约束：当前接口为模块入口，须在使用其他定时器接口之前调用。
  • 依赖关系：当前接口依赖底层 HAL 定时器与定时器 porting 层资源可访问。
  • 上下文限制：可在任务上下文调用。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功初始化或模块已初始化
ERRCODE_MEMSET：0x80000003 内存设置失败 软件定时器链表清零失败
Other 其他错误码，参考errcode_t 软件定时器链表初始化失败

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_LPC 特性宏 支持低功耗时钟控制特性（分支级） n

uapi_timer_adapter 

errcode_t uapi_timer_adapter(timer_index_t index, uint32_t int_id, uint16_t int_priority)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 适配指定硬件定时器索引，初始化底层 HAL 定时器。
  • 注册该索引对应的中断号与中断优先级。
  • 同一索引重复适配时直接返回成功。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_init 成功返回后调用。
  • 依赖关系：当前接口依赖 HAL 定时器初始化接口与中断注册接口可用。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员
int_id uint32_t 硬件定时器中断 ID 有效中断号
int_priority uint16_t 硬件定时器中断优先级 有效中断优先级

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 适配成功或该索引已适配
ERRCODE_TIMER_NOT_INIT：0x80001324 定时器模块未初始化 模块尚未调用 uapi_timer_init
ERRCODE_INVALID_PARAM：0x80000001 参数无效 index >= TIMER_MAX_NUM
ERRCODE_TIMER_USING：0x80001325 定时器被占用 该索引已被高精度定时器占用
Other 其他错误码，参考errcode_t HAL 定时器初始化失败

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_HIGH_PRECISION 特性宏 支持高精度定时占用检查特性（分支级） n

uapi_timer_deinit 

errcode_t uapi_timer_deinit(void)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 去初始化定时器模块，停止所有已适配的硬件定时器。
  • 注销各硬件定时器索引的中断注册。
  • 清空定时器管理资源并复位初始化状态。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_init 之后调用，模块未初始化时直接返回成功。
  • 依赖关系：当前接口依赖 HAL 定时器去初始化与中断注销接口可用。
  • 上下文限制：可在任务上下文调用。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功去初始化或模块未初始化

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_LPC 特性宏 支持低功耗时钟控制特性（分支级） n

uapi_timer_create 

errcode_t uapi_timer_create(timer_index_t index, timer_handle_t *timer)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 在指定硬件定时器索引下创建一个软件定时器。
  • 分配软件定时器链表中的空闲表项并置为使能。
  • 通过出参返回该软件定时器的句柄。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_init 成功返回后调用。
  • 依赖关系：当前接口依赖对应索引已完成适配（uapi_timer_adapter）。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员

出参

名称 数据类型 输出说明
timer timer_handle_t * 成功创建的软件定时器句柄；无空闲表项时输出 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功分配软件定时器表项
ERRCODE_INVALID_PARAM：0x80000001 参数无效 timer 为 NULL 或 index >= TIMER_MAX_NUM
ERRCODE_TIMER_NO_ENOUGH：0x80001320 软件定时器表项已满 该索引下软件定时器链表无空闲表项

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

uapi_timer_delete 

errcode_t uapi_timer_delete(timer_handle_t timer)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 删除指定的软件定时器，释放其占用的链表表项。
  • 将对应表项的使能标志置为无效。

前置条件

  • 调用时序约束：当前接口操作的句柄须由 uapi_timer_create 创建。
  • 依赖关系：当前接口依赖传入句柄对应的软件定时器表项有效。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
timer timer_handle_t 待删除的软件定时器句柄 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功删除软件定时器
ERRCODE_INVALID_PARAM：0x80000001 参数无效 timer 为 NULL

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

uapi_timer_get_max_us 

uint32_t uapi_timer_get_max_us(void)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 获取当前硬件定时器支持的最大可设置延时时间，单位 us。
  • 返回值作为 uapi_timer_start 与高精度定时接口 time_us 入参的上限参考。

前置条件

  • 依赖关系：底层定时器时钟配置（CONFIG_TIMER_CLOCK_VALUE）已确定，定时器 porting 层周期换算接口可用。
  • 上下文限制：无特殊上下文限制。

返回值

返回类型：uint32_t

返回值 文字含义 触发场景
uint32_t 最大可设置的延时时间，单位 us 调用成功，恒返回换算结果

uapi_timer_start 

errcode_t uapi_timer_start(timer_handle_t timer, uint32_t time_us, timer_callback_t callback, uintptr_t data)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 启动指定的软件定时器，设置超时时间与超时回调。
  • 设置用户数据，在超时触发时透传给回调函数。
  • 根据剩余周期决定是否立即重载硬件定时器。

前置条件

  • 调用时序约束：当前接口操作的句柄须由 uapi_timer_create 创建。
  • 依赖关系：当前接口依赖对应索引已完成适配（uapi_timer_adapter）且硬件定时器可用。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
timer timer_handle_t 待启动的软件定时器句柄 不为 NULL
time_us uint32_t 定时器超时时间，单位 us 大于 0 且不超过 uapi_timer_get_max_us 返回值
callback timer_callback_t 定时器超时回调函数指针；超时触发时在硬件定时器中断上下文中被调用，data 为透传参数 不为 NULL
data uintptr_t 定时器回调函数的透传参数 任意值

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功启动软件定时器
ERRCODE_INVALID_PARAM：0x80000001 参数无效 timer 或 callback 为 NULL、time_us 为 0 或超过最大值
ERRCODE_TIEMR_NOT_CREATED：0x80001321 定时器未创建 该句柄对应表项未使能

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_USING_OLD_VERSION 特性宏 支持旧版本 load count 对齐特性（分支级） n

uapi_timer_stop 

errcode_t uapi_timer_stop(timer_handle_t timer)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 停止指定的软件定时器，停止后用户注册的回调不会被调用。
  • 清空该表项的超时周期、回调与数据。
  • 若该索引下无运行中的定时器，停止底层硬件定时器。

前置条件

  • 调用时序约束：当前接口操作的句柄须由 uapi_timer_create 创建。
  • 依赖关系：当前接口依赖传入句柄对应的软件定时器表项有效。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
timer timer_handle_t 待停止的软件定时器句柄 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功停止软件定时器，或该定时器本未运行
ERRCODE_INVALID_PARAM：0x80000001 参数无效 timer 为 NULL
ERRCODE_TIEMR_NOT_CREATED：0x80001321 定时器未创建 该句柄对应表项未使能

参考案例

  • src/application/samples/peripheral/timer/timer_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_HIGH_PRECISION 特性宏 支持高精度定时占用标志复位特性（分支级） n

uapi_timer_get_current_time_us 

errcode_t uapi_timer_get_current_time_us(timer_index_t index, uint32_t *current_time_us)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 获取指定底层硬件定时器索引的当前计数值，换算为 us 输出。

前置条件

  • 调用时序约束：当前接口依赖对应索引的底层硬件定时器已初始化。
  • 依赖关系：当前接口依赖 HAL 定时器取值接口与 porting 层周期换算接口可用。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员

出参

名称 数据类型 输出说明
current_time_us uint32_t * 底层硬件定时器当前时间，单位 us，由函数填充

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功获取当前时间
ERRCODE_INVALID_PARAM：0x80000001 参数无效 index >= TIMER_MAX_NUM 或 current_time_us 为 NULL

uapi_timer_start_high_precision 

errcode_t uapi_timer_start_high_precision(timer_index_t index, timer_trigger_mode_t mode, uint32_t time_us,
                                          timer_irq_info_t* irq_info, high_precision_timer_callback_t callback)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 启动一个高精度专用定时器，按指定触发模式与超时时间直接驱动硬件定时器。
  • 注册该索引对应的中断号与中断优先级。
  • 超时触发时在硬件定时器中断上下文中调用用户回调。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_init 成功返回后调用。
  • 依赖关系：当前接口依赖该索引未被标准定时器占用（g_timer_useing_flag 非 STANDARD_TIMER_MODE）。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员
mode timer_trigger_mode_t 定时器触发模式 timer_trigger_mode_t 全体成员
time_us uint32_t 定时器超时时间，单位 us 大于 0 且不超过 uapi_timer_get_max_us 返回值
irq_info timer_irq_info_t * 中断信息结构体指针，包含中断号与优先级 不为 NULL
callback high_precision_timer_callback_t 高精度定时器超时回调函数指针；超时触发时在硬件定时器中断上下文中调用，index 为触发的硬件定时器索引 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功启动高精度定时器
ERRCODE_INVALID_PARAM：0x80000001 参数无效 index 越界、irq_info 或 callback 为 NULL、mode 越界、time_us 为 0 或超过最大值
ERRCODE_TIMER_USING：0x80001325 定时器被占用 该索引已被标准定时器占用
Other 其他错误码，参考errcode_t HAL 定时器初始化失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_HIGH_PRECISION 特性宏 支持高精度专用定时器接口功能（接口级） n
CONFIG_TIMER_SUPPORT_LPC 特性宏 支持低功耗时钟控制特性（分支级） n

uapi_timer_reset_high_precision 

errcode_t uapi_timer_reset_high_precision(timer_index_t index, timer_trigger_mode_t mode, uint32_t time_us)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 重启指定索引的高精度专用定时器。
  • 按新的触发模式与超时时间重载硬件定时器。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_start_high_precision 已将目标索引置为高精度模式后调用。
  • 依赖关系：当前接口依赖该索引当前处于高精度定时模式。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员
mode timer_trigger_mode_t 定时器触发模式 timer_trigger_mode_t 全体成员
time_us uint32_t 定时器超时时间，单位 us 大于 0 且不超过 uapi_timer_get_max_us 返回值

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功重启高精度定时器
ERRCODE_INVALID_PARAM：0x80000001 参数无效 index 越界、mode 越界、time_us 为 0 或超过最大值
ERRCODE_TIMER_USING：0x80001325 定时器被占用 该索引不处于高精度定时模式

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_HIGH_PRECISION 特性宏 支持高精度专用定时器接口功能（接口级） n

uapi_timer_stop_high_precision 

errcode_t uapi_timer_stop_high_precision(timer_index_t index)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 停止指定索引的高精度专用定时器。
  • 清除该索引的高精度占用标志。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_start_high_precision 已将目标索引置为高精度模式后调用。
  • 依赖关系：当前接口依赖该索引当前处于高精度定时模式。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
index timer_index_t 硬件定时器索引，须小于 TIMER_MAX_NUM timer_index_t 全体成员

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功停止高精度定时器
ERRCODE_INVALID_PARAM：0x80000001 参数无效 index >= TIMER_MAX_NUM
ERRCODE_TIMER_USING：0x80001325 定时器被占用 该索引不处于高精度定时模式

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_HIGH_PRECISION 特性宏 支持高精度专用定时器接口功能（接口级） n
CONFIG_TIMER_SUPPORT_LPC 特性宏 支持低功耗时钟控制特性（分支级） n

uapi_timer_suspend 

errcode_t uapi_timer_suspend(uintptr_t val)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 挂起定时器模块，刷新各已适配索引的软件定时器剩余周期。
  • 为各索引重新设置下一次硬件中断。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_init 成功返回后调用。
  • 依赖关系：当前接口依赖各索引已完成适配（uapi_timer_adapter）且底层 HAL 定时器可用。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
val uintptr_t 挂起参数；当前实现未使用该参数 任意值

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功挂起定时器模块

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_LPM 特性宏 支持低功耗挂起/恢复接口功能（接口级） n

uapi_timer_resume 

errcode_t uapi_timer_resume(uintptr_t val)

声明头文件

#include "include/driver/timer.h"

功能说明

  • 恢复定时器模块，依据传入的补偿计数值重载各已适配索引的硬件定时器。

前置条件

  • 调用时序约束：当前接口必须在 uapi_timer_suspend 之后调用。
  • 依赖关系：当前接口依赖各索引已完成适配（uapi_timer_adapter）且底层 HAL 定时器可用。
  • 上下文限制：可在任务上下文调用。

入参

名称 参数类型 说明 约束取值范围
val uintptr_t 恢复参数，指向 uint64_t 类型的补偿计数值 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 成功恢复定时器模块

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_TIMER_SUPPORT_LPM 特性宏 支持低功耗挂起/恢复接口功能（接口级） n

Type definitions

timer_handle_t 

typedef void *timer_handle_t;

使用说明

作为 uapi_timer_create 的出参、uapi_timer_delete/uapi_timer_start/uapi_timer_stop 的入参类型，用于标识一个软件定时器。不透明类型，实现细节不公开，仅通过对外接口操作。

timer_callback_t 

typedef void (*timer_callback_t)(uintptr_t data);

使用说明

作为 uapi_timer_start 的入参类型，用于注册软件定时器超时回调。

  • 调用时机：软件定时器超时触发硬件定时器中断时，由中断处理流程在硬件定时器中断上下文中调用（实现中 timer_int_callback 经 timer_process_timers 判空后调用）。
  • 参数 data：调用方在 uapi_timer_start 中传入的 uintptr_t 透传参数，直接传入回调。
  • 返回值处理：回调返回类型为 void，无返回值。

high_precision_timer_callback_t 

typedef void (*high_precision_timer_callback_t)(timer_index_t index);

使用说明

作为 uapi_timer_start_high_precision 的入参类型，用于注册高精度定时器超时回调。

  • 调用时机：高精度定时器超时触发硬件定时器中断时，由该索引注册的中断处理函数调用。
  • 参数 index：触发超时的硬件定时器索引。
  • 返回值处理：回调返回类型为 void，无返回值。

errcode_t 

typedef uint32_t errcode_t;

使用说明

作为本模块多个对外接口的返回类型，表示接口执行结果。

Enumerations

timer_index_t 

typedef enum timer_index {
    TIMER_INDEX_0,                      /*!< Timer0 index. */
    TIMER_INDEX_1,                      /*!< Timer1 index. */
#if defined(CONFIG_TIMER_MAX_NUM) && (CONFIG_TIMER_MAX_NUM > 2)
    TIMER_INDEX_2,                      /*!< Timer2 index. */
#endif
    TIMER_MAX_NUM
} timer_index_t;
枚举成员 取值 描述
TIMER_INDEX_0 0 Timer0 索引
TIMER_INDEX_1 1 Timer1 索引
TIMER_INDEX_2 2 Timer2 索引（CONFIG_TIMER_MAX_NUM > 2 时存在）
TIMER_MAX_NUM 2 或 3 硬件定时器索引总数上限，取值由 CONFIG_TIMER_MAX_NUM 决定（CONFIG_TIMER_MAX_NUM <= 2 时为 2，> 2 时为 3）

timer_trigger_mode_t 

typedef enum timer_trigger_mode {
    /** Timer mode: one shot mode. 定时器控制模式：单触发模式。 */
    TIMER_MODE_ONE_SHOT,
    /** Timer mode: periodic mode. 定时器控制模式：周期触发模式。 */
    TIMER_MODE_PERIODIC,
} timer_trigger_mode_t;
枚举成员 取值 描述
TIMER_MODE_ONE_SHOT 0 单次触发模式
TIMER_MODE_PERIODIC 1 周期触发模式

Structures

timer_irq_info_t 

#if defined(CONFIG_TIMER_SUPPORT_HIGH_PRECISION)
typedef struct timer_irq_info {
    /** @if Eng  irq num.
     *  @else    中断号。
     *  @endif */
    uint32_t irq;
    /** @if Eng  irq priority.
     *  @else    中断优先级。
     *  @endif */
    uint16_t priority;
} timer_irq_info_t;
#endif /* CONFIG_TIMER_SUPPORT_HIGH_PRECISION */

成员说明

成员名称 数据类型 描述
irq uint32_t 中断号
priority uint16_t 中断优先级

Macros

ERRCODE_SUCC 

#define ERRCODE_SUCC                                        0UL

ERRCODE_INVALID_PARAM 

#define ERRCODE_INVALID_PARAM                               0x80000001

ERRCODE_MEMSET 

#define ERRCODE_MEMSET                                      0x80000003

ERRCODE_TIMER_NO_ENOUGH 

#define ERRCODE_TIMER_NO_ENOUGH                             0x80001320

ERRCODE_TIEMR_NOT_CREATED 

#define ERRCODE_TIEMR_NOT_CREATED                           0x80001321

ERRCODE_TIMER_NOT_INIT 

#define ERRCODE_TIMER_NOT_INIT                              0x80001324

ERRCODE_TIMER_USING 

#define ERRCODE_TIMER_USING                                 0x80001325