跳转至
项目
版本
全文检索

Time

Time 模块提供定时器管理功能，包括普通定时器与高精度定时器的生命周期管理，以及系统时间获取与毫秒/Ticks 单位转换能力。

模块公共头文件

#include "src/kernel/osal/include/time/osal_timer.h"

接口清单

接口名称 功能简述
osal_timer_init 初始化定时器
osal_timer_start 启动定时器
osal_timer_mod 修改定时器超时时间
osal_timer_start_on 在指定 CPU 上启动定时器
osal_timer_stop 停止定时器
osal_timer_destroy 销毁定时器
osal_timer_get_private_data 获取定时器回调函数的私有数据
osal_timer_destroy_sync 同步销毁定时器并等待回调完成
osal_sched_clock 获取系统时间（纳秒）
osal_get_jiffies 获取 Ticks 或 jiffies 数
osal_msecs_to_jiffies 将毫秒转换为 Ticks/jiffies
osal_jiffies_to_msecs 将 Ticks/jiffies 转换为毫秒
osal_get_cycle_per_tick 获取一个 tick 中的周期数
osal_gettimeofday 获取当前系统内核时间
osal_hrtimer_create 创建高精度定时器
osal_hrtimer_start 启动高精度定时器
osal_hrtimer_destroy 删除高精度定时器

Functions

osal_timer_init 

int osal_timer_init(osal_timer *timer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 初始化定时器并设置到期回调。
  • 定时器到期时通过注册的回调函数通知调用方。
  • 支持 linux、liteos、freertos 系统。

前置条件

  • 依赖关系：调用前需设置 timer 的 handler 和 data 字段，初始化完成后无法再修改这两个字段。
  • 依赖关系：不再使用定时器时应调用 osal_timer_destroy 释放，否则会导致内存泄漏。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 输入输出参数。要初始化的定时器，调用前需设置 handler 和 data 字段，函数填充内部定时器资源 不为 NULL；timer->handler 不为 NULL；timer->timer 为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器初始化成功
OSAL_FAILURE：-1 执行失败 参数无效、interval 无效或内存分配失败

参考案例

  • src/application/samples/peripheral/adc/adc_demo.c
  • src/middleware/utils/dfx/log_file/log_file.c

osal_timer_start 

int osal_timer_start(osal_timer *timer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 启动已初始化的定时器，按设定超时时间调度。
  • 定时器到期时内核将通过定时器中断回调 handler。
  • 支持 linux、liteos、freertos 系统。

前置条件

  • 调用时序约束：必须在 osal_timer_init 成功返回后调用。
  • 上下文限制：定时器到期时回调将在定时器中断上下文中执行。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要启动的定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器启动成功
OSAL_FAILURE：-1 执行失败 参数无效

参考案例

  • src/application/samples/peripheral/adc/adc_demo.c
  • src/middleware/utils/dfx/log_file/log_file.c

osal_timer_mod 

int osal_timer_mod(osal_timer *timer, unsigned int interval)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 修改定时器的超时时间。
  • 对活跃定时器更新过期时间，对非活跃定时器将其激活。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要修改的定时器 不为 NULL
interval unsigned int 新的超时时间，单位 ms > 0

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器超时时间修改成功
OSAL_FAILURE：-1 执行失败 参数无效或 interval 无效

参考案例

  • src/application/samples/peripheral/lpc/lpc_gpio_wakeup_demo.c

osal_timer_start_on 

int osal_timer_start_on(osal_timer *timer, unsigned long delay, int cpu)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 在指定 CPU 上启动定时器。
  • 支持 linux 系统。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要启动的定时器 不为 NULL
delay unsigned long 延迟时间，单位 ms -
cpu int 启动定时器的 CPU 编号 有效 CPU 编号

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器在指定 CPU 上启动成功
OSAL_FAILURE：-1 执行失败 参数无效

osal_timer_stop 

int osal_timer_stop(osal_timer *timer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 停止定时器，对活跃和非活跃定时器均生效。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要停止的定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
1 停止成功，定时器处于 pending 状态 仅 Linux 和 LiteOS 支持返回 1
OSAL_SUCCESS：0 停止成功，定时器已停止 定时器未处于活跃状态
OSAL_FAILURE：-1 执行失败 参数无效

参考案例

  • src/middleware/utils/dfx/log_file/log_file.c
  • src/protocol/wifi/source/host/frw/frw_timer.c

osal_timer_destroy 

int osal_timer_destroy(osal_timer *timer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 销毁定时器，停止定时器并释放内部资源。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要销毁的定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器销毁成功
OSAL_FAILURE：-1 执行失败 参数无效

参考案例

  • src/middleware/utils/dfx/log_file/log_file.c

osal_timer_get_private_data 

unsigned long osal_timer_get_private_data(const void *sys_data)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 在定时器回调函数中获取可直接使用的参数数据。
  • 定时器回调函数的参数不能直接使用，需通过此接口转换获取。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
sys_data const void * 传给回调函数的参数 不为 NULL

返回值

返回类型：unsigned long

返回值 文字含义 触发场景
0 获取失败 sys_data 为 NULL
非 0 值 可直接使用的参数数据 正常获取定时器私有数据

osal_timer_destroy_sync 

int osal_timer_destroy_sync(osal_timer *timer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 停止定时器并等待回调函数执行完成。
  • 在 SMP（Symmetric Multi-Processing）环境下确保其他 CPU 上的回调已执行完毕。
  • 支持 linux 系统。

前置条件

  • 调用时序约束：必须在 osal_timer_init 成功返回后调用。
  • 上下文限制：禁止在中断上下文调用（除非定时器为 irqsafe 类型）。
  • 依赖关系：调用者不能持有会阻止定时器回调函数完成的锁；调用者必须阻止定时器被重新启动。

入参

名称 参数类型 说明 约束取值范围
timer osal_timer * 要同步销毁的定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 定时器已同步销毁
OSAL_FAILURE：-1 执行失败 参数无效

osal_sched_clock 

unsigned long long osal_sched_clock(void)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 获取当前系统时间，单位为纳秒。
  • 支持 linux 和 liteos 系统。

返回值

返回类型：unsigned long long

返回值 文字含义 触发场景
unsigned long long 当前系统时间，单位纳秒 调用成功返回当前时间

osal_get_jiffies 

unsigned long long osal_get_jiffies(void)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 获取系统的 Ticks（liteos）或 jiffies（linux）数量。
  • 支持 linux、liteos、freertos 系统。

返回值

返回类型：unsigned long long

返回值 文字含义 触发场景
unsigned long long Ticks（liteos）或 jiffies（linux）数量 调用成功返回当前节拍数

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_msecs_to_jiffies 

unsigned long osal_msecs_to_jiffies(const unsigned int m)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 将毫秒转换为 Ticks/jiffies。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
m const unsigned int 要转换的时间，单位 ms -

返回值

返回类型：unsigned long

返回值 文字含义 触发场景
unsigned long 转换后的 Ticks/jiffies 数 调用成功返回转换结果

osal_jiffies_to_msecs 

unsigned int osal_jiffies_to_msecs(const unsigned int n)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 将 Ticks/jiffies 转换为毫秒。
  • 若转换结果超过 0xFFFFFFFF，则返回 0xFFFFFFFF。
  • 支持 linux、liteos、freertos 系统。

入参

名称 参数类型 说明 约束取值范围
n const unsigned int 要转换的 Ticks/jiffies 数 -

返回值

返回类型：unsigned int

返回值 文字含义 触发场景
unsigned int 转换后的毫秒数，超过 0xFFFFFFFF 时返回 0xFFFFFFFF 调用成功返回转换结果

osal_get_cycle_per_tick 

unsigned int osal_get_cycle_per_tick(void)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 获取一个 tick 中包含的周期数。
  • 支持 liteos 系统。

返回值

返回类型：unsigned int

返回值 文字含义 触发场景
unsigned int 一个 tick 中的周期数 调用成功返回周期数

osal_gettimeofday 

void osal_gettimeofday(osal_timeval *tv)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 获取当前系统内核时间。
  • 时间通过 osal_timeval 结构体返回，包含秒和微秒。
  • 支持 linux、liteos、freertos 系统。

出参

名称 数据类型 输出说明
tv osal_timeval * 获取的当前系统内核时间，由调用方分配内存、函数填充

参考案例

  • src/middleware/services/wifi_service/service/soc_wifi_service_api.c
  • src/protocol/wifi/source/host/hmac/hmac_dfx.c

osal_hrtimer_create 

int osal_hrtimer_create(osal_hrtimer *hrtimer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 创建高精度定时器节点并初始化定时器参数。
  • 支持 liteos 系统。

前置条件

  • 依赖关系：调用前需设置 hrtimer 的 handler 和 interval 字段，初始化完成后无法再修改这两个字段。
  • 上下文限制：模块退出时必须调用 osal_hrtimer_destroy 释放定时器，否则会导致内存泄漏。

入参

名称 参数类型 说明 约束取值范围
hrtimer osal_hrtimer * 输入输出参数。要创建的高精度定时器，调用前需设置 handler 和 interval 字段，函数填充内部定时器资源 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 高精度定时器创建成功
OSAL_FAILURE：-1 执行失败 高精度定时器创建失败

Kconfig配置

配置项 宏类型 说明 默认值
LOSCFG_COMPAT_LINUX_HRTIMER 特性宏 支持 high resolution timer 接口（接口级，liteos 实现体由 #ifdef 包裹，LiteOS Kconfig 声明） n

osal_hrtimer_start 

int osal_hrtimer_start(osal_hrtimer *hrtimer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 启动高精度定时器，将定时器节点添加到全局链表并开始计时。
  • 支持 liteos 系统。

入参

名称 参数类型 说明 约束取值范围
hrtimer osal_hrtimer * 要启动的高精度定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
-1 启动失败 高精度定时器启动失败
0 启动成功 高精度定时器启动成功
1 节点已存在 高精度定时器节点已在链表中

Kconfig配置

配置项 宏类型 说明 默认值
LOSCFG_COMPAT_LINUX_HRTIMER 特性宏 支持 high resolution timer 接口（接口级，liteos 实现体由 #ifdef 包裹，LiteOS Kconfig 声明） n

osal_hrtimer_destroy 

int osal_hrtimer_destroy(osal_hrtimer *hrtimer)

声明头文件

#include "src/kernel/osal/include/time/osal_timer.h"

功能说明

  • 删除已存在的高精度定时器。
  • 支持 liteos 系统。

入参

名称 参数类型 说明 约束取值范围
hrtimer osal_hrtimer * 要删除的高精度定时器 不为 NULL

返回值

返回类型：int

返回值 文字含义 触发场景
OSAL_SUCCESS：0 执行成功 高精度定时器删除成功
OSAL_FAILURE：-1 执行失败 参数为空或定时器节点不存在

Kconfig配置

配置项 宏类型 说明 默认值
LOSCFG_COMPAT_LINUX_HRTIMER 特性宏 支持 high resolution timer 接口（接口级，liteos 实现体由 #ifdef 包裹，LiteOS Kconfig 声明） n

Enumerations

osal_hrtimer_restart 

typedef enum {
    OSAL_HRTIMER_NORESTART, /* < The timer will not be restarted. */
    OSAL_HRTIMER_RESTART    /* < The timer must be restarted. */
} osal_hrtimer_restart;
枚举成员 取值 描述
OSAL_HRTIMER_NORESTART 0 定时器不再重启
OSAL_HRTIMER_RESTART 1 定时器需要重启

Structures

osal_timer 

typedef struct {
    void *timer;
    void (*handler)(unsigned long);
    unsigned long data;    // data for handler
    unsigned int interval; // timer timing duration, unit: ms.
} osal_timer;

成员说明

成员名称 数据类型 描述
timer void * 定时器内部资源指针
handler void (*)(unsigned long) 定时器超时回调函数指针
data unsigned long 回调函数的参数数据
interval unsigned int 定时器定时时长，单位 ms

osal_timeval 

typedef struct {
    long tv_sec;
    long tv_usec;
} osal_timeval;

成员说明

成员名称 数据类型 描述
tv_sec long 秒
tv_usec long 微秒

osal_hrtimer 

typedef struct osal_hrtimer {
    void *timer;
    osal_hrtimer_restart (*handler)(void *timer);
    unsigned long interval; /* Unit ms */
} osal_hrtimer;

成员说明

成员名称 数据类型 描述
timer void * 高精度定时器内部资源指针
handler osal_hrtimer_restart (*)(void *)
interval unsigned long 定时器定时间隔，单位 ms

Macros

OSAL_SUCCESS 

#define OSAL_SUCCESS 0

OSAL_FAILURE 

#define OSAL_FAILURE (-1)