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	获取定时器可设置的最大延时时间
uapi_timer_start	启动软件定时器
uapi_timer_stop	停止软件定时器
uapi_timer_get_current_time_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

timer_init uapi timer init uapi_timer_init

errcode_t uapi_timer_init(void)

头文件清单

#include "include/driver/timer.h"

功能说明

• 初始化定时器模块，完成定时器管理器的内存清零与软件定时器列表配置
• 重复调用时返回 ERRCODE_SUCC，不会重复初始化
• 初始化后方可调用 uapi_timer_adapter 适配硬件定时器

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功
Other	其他错误码，参考errcode_t	执行失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_LPC	特性宏	支持低功耗时钟控制特性	n

uapi_timer_adapter

timer_adapter uapi timer adapter 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"

功能说明

• 适配指定硬件定时器，注册该定时器的中断回调与中断优先级
• 同一硬件定时器索引重复适配时返回 ERRCODE_SUCC，不会重复注册
• 高精度模式下若该定时器已被占用，返回 ERRCODE_TIMER_USING

前置条件

• 调用时序约束：已通过 uapi_timer_init() 初始化完成，返回初始化成功状态
• 依赖关系：硬件定时器索引有效，对应外设时钟已使能

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 CONFIG_TIMER_MAX_NUM
int_id	uint32_t	硬件定时器中断ID	有效的中断号
int_priority	uint16_t	硬件定时器中断优先级	有效的中断优先级值

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	适配成功或已适配
ERRCODE_TIMER_NOT_INIT(0x80001324)	定时器未初始化	模块未初始化即调用
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	索引超出范围
ERRCODE_TIMER_USING(0x80001325)	定时器已被占用	高精度模式下定时器已被使用
Other	其他错误码，参考errcode_t	HAL层初始化失败

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_HIGH_PRECISION	功能宏	支持高精度定时器功能	n

uapi_timer_deinit

timer_deinit uapi timer deinit uapi_timer_deinit

errcode_t uapi_timer_deinit(void)

头文件清单

#include "include/driver/timer.h"

功能说明

• 去初始化定时器模块，停止所有已适配的硬件定时器并注销中断
• 清空定时器管理器数据，将模块标记为未初始化状态
• 未初始化时调用返回 ERRCODE_SUCC

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	去初始化成功

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_LPC	特性宏	支持低功耗时钟控制特性	n

uapi_timer_create

timer_create uapi timer create uapi_timer_create

errcode_t uapi_timer_create(timer_index_t index, timer_handle_t *timer)

头文件清单

#include "include/driver/timer.h"

功能说明

• 在指定硬件定时器索引下创建软件定时器，返回定时器句柄
• 同一硬件定时器索引下可创建多个软件定时器，数量受 CONFIG_TIMER_MAX_TIMERS_NUM 限制
• 创建后定时器处于使能但未运行状态，需调用 uapi_timer_start 启动

前置条件

• 调用时序约束：已通过 uapi_timer_init() 初始化完成
• 依赖关系：对应硬件定时器已通过 uapi_timer_adapter 适配完成

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 CONFIG_TIMER_MAX_NUM

出参

名称	数据类型	输出说明
timer	timer_handle_t *	创建成功时返回定时器句柄；创建失败时返回 NULL，不为 NULL

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	创建成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	timer 为 NULL 或 index 超出范围
ERRCODE_TIMER_NO_ENOUGH(0x80001320)	定时器资源不足	软件定时器池已满

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n

uapi_timer_delete

timer_delete uapi timer delete uapi_timer_delete

errcode_t uapi_timer_delete(timer_handle_t timer)

头文件清单

#include "include/driver/timer.h"

功能说明

• 删除指定软件定时器，将其资源释放回定时器池
• 删除后定时器句柄不再有效，禁止继续使用
• 若定时器正在运行，删除后回调不再触发

入参

名称	参数类型	详细说明	约束取值范围
timer	timer_handle_t	定时器句柄	由 uapi_timer_create 创建的有效句柄，不为 NULL

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	删除成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	timer 为 NULL

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n

uapi_timer_get_max_us

timer_get_max_us uapi timer get max us uapi_timer_get_max_us

uint32_t uapi_timer_get_max_us(void)

头文件清单

#include "include/driver/timer.h"

功能说明

• 获取定时器可设置的最大延时时间，单位为微秒
• 返回值由硬件定时器计数位宽与输入时钟频率共同决定
• 启动定时器前可调用此接口确认 time_us 参数的有效上限

返回值

• 返回类型：uint32_t

返回值	文字含义	触发场景
uint32_t	最大可设置延时时间(us)	正常返回

uapi_timer_start

timer_start uapi timer start 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_get_max_us 返回的最大值，不能为 0
• 超时后回调函数在中断上下文中执行，回调函数内禁止执行耗时操作

前置条件

• 调用时序约束：timer 句柄由 uapi_timer_create 创建，对应的硬件定时器已通过 uapi_timer_adapter 适配完成
• 参数合法性要求：callback 不为 NULL，time_us 不为 0 且不超过最大值

入参

名称	参数类型	详细说明	约束取值范围
timer	timer_handle_t	定时器句柄	由 uapi_timer_create 创建的有效句柄，不为 NULL
time_us	uint32_t	定时器超时时间	(0, uapi_timer_get_max_us()]
callback	timer_callback_t	定时器回调函数	不为 NULL
data	uintptr_t	传递给回调函数的参数	无限制

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	启动成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	timer 为 NULL、callback 为 NULL、time_us 为 0 或超最大值
ERRCODE_TIEMR_NOT_CREATED(0x80001321)	定时器未创建	timer 句柄无效或未使能

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_USING_OLD_VERSION	特性宏	支持旧版本IP对齐特性	n

uapi_timer_stop

timer_stop uapi timer stop uapi_timer_stop

errcode_t uapi_timer_stop(timer_handle_t timer)

头文件清单

#include "include/driver/timer.h"

功能说明

• 停止指定软件定时器，停止后回调不再触发
• 若定时器未运行，返回 ERRCODE_SUCC
• 若当前硬件定时器下无其他软件定时器运行，将停止硬件计数

入参

名称	参数类型	详细说明	约束取值范围
timer	timer_handle_t	定时器句柄	由 uapi_timer_create 创建的有效句柄，不为 NULL

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	停止成功或定时器未运行
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	timer 为 NULL
ERRCODE_TIEMR_NOT_CREATED(0x80001321)	定时器未创建	timer 句柄未使能

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_HIGH_PRECISION	特性宏	支持高精度定时器标志位清除特性	n

uapi_timer_get_current_time_us

timer_get_current_time_us uapi timer get current time us 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"

功能说明

• 获取指定底层硬件定时器的当前剩余计时时间，单位为微秒
• 读取硬件定时器当前计数值并转换为微秒
• 可用于获取硬件定时器的实时计时状态

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	底层硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 TIMER_MAX_NUM

出参

名称	数据类型	输出说明
current_time_us	uint32_t *	底层定时器当前时间(us)，由调用方分配内存、函数填充，不为 NULL

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	获取成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	index 超出范围或 current_time_us 为 NULL

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n

uapi_timer_start_high_precision

timer_start_high_precision uapi timer start high precision 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() 初始化完成
• 依赖关系：对应硬件定时器未被标准模式占用
• 参数合法性要求：index 有效、irq_info 不为 NULL、mode 有效、time_us 不为 0 且不超过最大值、callback 不为 NULL

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 TIMER_MAX_NUM
mode	timer_trigger_mode_t	定时器触发模式	TIMER_MODE_ONE_SHOT(0) / TIMER_MODE_PERIODIC(1)
time_us	uint32_t	定时器超时时间	(0, uapi_timer_get_max_us()]
irq_info	timer_irq_info_t *	中断信息结构体	不为 NULL
callback	high_precision_timer_callback_t	高精度定时器回调函数	不为 NULL

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	启动成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	参数不满足合法性要求
ERRCODE_TIMER_USING(0x80001325)	定时器已被占用	标准模式正在使用该定时器
Other	其他错误码，参考errcode_t	HAL层初始化失败

Kconfig配置

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

uapi_timer_reset_high_precision

timer_reset_high_precision uapi timer reset high precision 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 有效、mode 有效、time_us 不为 0 且不超过最大值

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 TIMER_MAX_NUM
mode	timer_trigger_mode_t	定时器触发模式	TIMER_MODE_ONE_SHOT(0) / TIMER_MODE_PERIODIC(1)
time_us	uint32_t	定时器超时时间	(0, uapi_timer_get_max_us()]

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	重启成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	参数不满足合法性要求
ERRCODE_TIMER_USING(0x80001325)	定时器状态不符	定时器未处于高精度模式

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_HIGH_PRECISION	功能宏	支持高精度定时器功能	n

uapi_timer_stop_high_precision

timer_stop_high_precision uapi timer stop high precision uapi_timer_stop_high_precision

errcode_t uapi_timer_stop_high_precision(timer_index_t index)

头文件清单

#include "include/driver/timer.h"

功能说明

• 停止高精度专用定时器，清除高精度模式标志
• 仅在定时器已处于高精度模式时方可调用
• 停止后定时器索引可被标准模式或再次启动高精度模式使用

前置条件

• 调用时序约束：对应硬件定时器已处于高精度模式
• 参数合法性要求：index 在有效范围内

入参

名称	参数类型	详细说明	约束取值范围
index	timer_index_t	硬件定时器索引	TIMER_INDEX_0(0) / TIMER_INDEX_1(1) / TIMER_INDEX_2(2) / TIMER_INDEX_3(3)，小于 TIMER_MAX_NUM

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	停止成功
ERRCODE_INVALID_PARAM(0x80000001)	参数无效	index 超出范围
ERRCODE_TIMER_USING(0x80001325)	定时器状态不符	定时器未处于高精度模式

Kconfig配置

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

uapi_timer_suspend

timer_suspend uapi timer suspend uapi_timer_suspend

errcode_t uapi_timer_suspend(uintptr_t val)

头文件清单

#include "include/driver/timer.h"

功能说明

• 挂起定时器，更新所有已适配硬件定时器的剩余计时时间
• 遍历所有已适配定时器，保存当前计时状态并重新设置下次中断
• 用于低功耗模式进入前的定时器状态保存

前置条件

• 调用时序约束：已通过 uapi_timer_init() 初始化完成
• 依赖关系：至少有一个硬件定时器已通过 uapi_timer_adapter 适配

入参

名称	参数类型	详细说明	约束取值范围
val	uintptr_t	挂起参数	未使用

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	挂起成功

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
CONFIG_TIMER_SUPPORT_LPM	功能宏	支持低功耗模式挂起/恢复功能	n

uapi_timer_resume

timer_resume uapi timer resume uapi_timer_resume

errcode_t uapi_timer_resume(uintptr_t val)

头文件清单

#include "include/driver/timer.h"

功能说明

• 恢复定时器，根据补偿计数值重新启动所有已适配硬件定时器
• val 参数指向 uint64_t 类型的补偿计数值，用于恢复后的时间补偿
• 用于低功耗模式退出后的定时器状态恢复

前置条件

• 调用时序约束：已通过 uapi_timer_init() 初始化完成
• 依赖关系：至少有一个硬件定时器已通过 uapi_timer_adapter 适配
• 参数合法性要求：val 指向的 uint64_t 内存空间已申请成功

入参

名称	参数类型	详细说明	约束取值范围
val	uintptr_t	恢复参数，指向 uint64_t 补偿计数值	指向有效的 uint64_t 内存地址

返回值

• 返回类型：errcode_t

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	恢复成功

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_DRIVER_SUPPORT_TIMER	功能宏	支持Timer接口功能	n
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 接口的回调参数。调用时机：软件定时器超时触发中断时，由中断处理函数调用。参数 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，无返回值处理。

Enumerations

timer_index_t

typedef enum timer_index {
    TIMER_INDEX_0,                      /*!< Timer0 index. */
    TIMER_INDEX_1,                      /*!< Timer1 index. */
    TIMER_INDEX_2,                      /*!< Timer2 index. */
    TIMER_INDEX_3,                      /*!< Timer3 index. */
    TIMER_MAX_NUM
} timer_index_t;

枚举成员	取值	描述
TIMER_INDEX_0	0	定时器0索引
TIMER_INDEX_1	1	定时器1索引
TIMER_INDEX_2	2	定时器2索引
TIMER_INDEX_3	3	定时器3索引
TIMER_MAX_NUM	4	定时器最大数量

timer_trigger_mode_t

typedef enum timer_trigger_mode {
    TIMER_MODE_ONE_SHOT,
    TIMER_MODE_PERIODIC,
} timer_trigger_mode_t;

枚举成员	取值	描述
TIMER_MODE_ONE_SHOT	0	单触发模式
TIMER_MODE_PERIODIC	1	周期触发模式

Structures

timer_irq_info_t

typedef struct timer_irq_info {
    uint32_t irq;
    uint16_t priority;
} timer_irq_info_t;

成员说明

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

Macros

ERRCODE_SUCC

errcode succ errcode_succ

#define ERRCODE_SUCC                                        0UL

ERRCODE_INVALID_PARAM

errcode invalid param errcode_invalid_param invalid_param

#define ERRCODE_INVALID_PARAM                               0x80000001

ERRCODE_TIMER_NO_ENOUGH

errcode timer no enough errcode_timer_no_enough timer_no_enough

#define ERRCODE_TIMER_NO_ENOUGH                             0x80001320

ERRCODE_TIEMR_NOT_CREATED

errcode tiemr not created errcode_tiemr_not_created tiemr_not_created

#define ERRCODE_TIEMR_NOT_CREATED                           0x80001321

ERRCODE_TIMER_NOT_INIT

errcode timer not init errcode_timer_not_init timer_not_init

#define ERRCODE_TIMER_NOT_INIT                              0x80001324

ERRCODE_TIMER_USING

errcode timer using errcode_timer_using timer_using

#define ERRCODE_TIMER_USING                                 0x80001325