Timer#
Timer 提供通用硬件定时器功能,支持创建与管理软件定时器、设置单次或周期性定时超时回调、获取硬件定时器最大可设置的延时时间,并可选支持高精度专用定时与低功耗挂起/恢复特性。
模块公共头文件
#include "include/driver/timer.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化定时器模块 |
|
适配指定硬件定时器索引并注册中断 |
|
去初始化定时器模块 |
|
在指定硬件索引下创建软件定时器并返回句柄 |
|
删除指定的软件定时器 |
|
获取硬件定时器最大可设置延时时间,单位 us |
|
启动指定定时器并注册超时回调 |
|
停止指定定时器 |
|
获取底层硬件定时器当前时间,单位 us |
|
启动高精度专用定时器 |
|
重启高精度专用定时器 |
|
停止高精度专用定时器 |
|
挂起定时器模块 |
|
恢复定时器模块 |
Functions#
uapi_timer_init #
errcode_t uapi_timer_init(void)
声明头文件
#include "include/driver/timer.h"
功能说明
初始化定时器模块的全局管理资源。
为各硬件定时器索引准备软件定时器链表。
重复调用时若模块已初始化则直接返回成功。
前置条件
调用时序约束:当前接口为模块入口,须在使用其他定时器接口之前调用。
依赖关系:当前接口依赖底层 HAL 定时器与定时器 porting 层资源可访问。
上下文限制:可在任务上下文调用。
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功初始化或模块已初始化 |
|
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_MAX_NUM |
timer_index_t 全体成员 |
|
int_id |
uint32_t |
硬件定时器中断 ID |
有效中断号 |
int_priority |
uint16_t |
硬件定时器中断优先级 |
有效中断优先级 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
适配成功或该索引已适配 |
|
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
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功去初始化或模块未初始化 |
参考案例
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_MAX_NUM |
timer_index_t 全体成员 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
timer |
成功创建的软件定时器句柄;无空闲表项时输出 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功分配软件定时器表项 |
|
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 |
待删除的软件定时器句柄 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功删除软件定时器 |
|
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 |
待启动的软件定时器句柄 |
不为 NULL |
|
time_us |
uint32_t |
定时器超时时间,单位 us |
大于 0 且不超过 uapi_timer_get_max_us 返回值 |
callback |
定时器超时回调函数指针;超时触发时在硬件定时器中断上下文中被调用,data 为透传参数 |
不为 NULL |
|
data |
uintptr_t |
定时器回调函数的透传参数 |
任意值 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功启动软件定时器 |
|
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 |
待停止的软件定时器句柄 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功停止软件定时器,或该定时器本未运行 |
|
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_MAX_NUM |
timer_index_t 全体成员 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
current_time_us |
uint32_t * |
底层硬件定时器当前时间,单位 us,由函数填充 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功获取当前时间 |
|
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_MAX_NUM |
timer_index_t 全体成员 |
|
mode |
定时器触发模式 |
timer_trigger_mode_t 全体成员 |
|
time_us |
uint32_t |
定时器超时时间,单位 us |
大于 0 且不超过 uapi_timer_get_max_us 返回值 |
irq_info |
中断信息结构体指针,包含中断号与优先级 |
不为 NULL |
|
callback |
高精度定时器超时回调函数指针;超时触发时在硬件定时器中断上下文中调用,index 为触发的硬件定时器索引 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功启动高精度定时器 |
|
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_MAX_NUM |
timer_index_t 全体成员 |
|
mode |
定时器触发模式 |
timer_trigger_mode_t 全体成员 |
|
time_us |
uint32_t |
定时器超时时间,单位 us |
大于 0 且不超过 uapi_timer_get_max_us 返回值 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功重启高精度定时器 |
|
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_MAX_NUM |
timer_index_t 全体成员 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功停止高精度定时器 |
|
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
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功挂起定时器模块 |
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
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
成功恢复定时器模块 |
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