Time

OS 定时器与时间管理。支持创建/启动/停止/修改/销毁软件定时器，回调在任务上下文中执行（非 ISR）。同时提供高精度定时器（hrtimer）和时间转换工具（ms↔jiffies 互转、sched_clock 纳秒级计时）。

定时器是一次性或周期性的，超时后自动触发回调。与硬件 Timer（ISR 上下文）不同，OS 定时器适合较长周期（≥ 1 个 tick）的定时任务。

头文件清单

#include "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 获取系统Tick/jiffies数

osal_msecs_to_jiffies 毫秒转换为Tick/jiffies

osal_jiffies_to_msecs Tick/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 "kernel/osal/include/time/osal_timer.h"

功能说明

初始化定时器，创建内核定时器资源
调用前须对 timer->handler 和 timer->data 赋值，初始化后不可再修改
timer->interval 指定定时器超时时间，单位为毫秒

前置条件

timer 指针不为 NULL，且 timer->handler 不为 NULL
timer->timer 须为 NULL（未初始化状态）
timer->interval 对应的 Tick 数须大于 0

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待初始化的定时器结构体指针非NULL，timer->handler非NULL，timer->timer为NULL

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 初始化成功定时器创建成功

OSAL_FAILURE(-1) 初始化失败参数无效或内核定时器创建失败

参考案例

src/middleware/utils/dfx/log_file/log_file.c#logfile_timer_init
src/drivers/chips/ws63/porting/xo_trim/xo_trim_porting.c

Kconfig配置

配置项宏类型说明默认值

LOSCFG_COMPAT_LINUX_TIMER 功能宏支持 OSAL Timer 接口功能 n

osal_timer_start

int osal_timer_start(osal_timer *timer)

头文件清单

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

功能说明

启动已初始化的定时器
定时器超时后，内核将执行回调函数
若定时器已在运行，调用此接口将重新启动定时器

前置条件

timer 指针不为 NULL
定时器已通过 osal_timer_init() 初始化成功

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待启动的定时器结构体指针非NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 启动成功定时器启动成功

OSAL_FAILURE(-1) 启动失败参数无效或内核定时器启动失败

参考案例

src/middleware/utils/dfx/log_file/log_file.c#logfile_timer_init
src/drivers/chips/ws63/porting/xo_trim/xo_trim_porting.c

osal_timer_mod

int osal_timer_mod(osal_timer *timer, unsigned int interval)

头文件清单

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

功能说明

修改定时器超时时间，若定时器未激活则激活
修改后定时器将按新的超时时间重新启动
效率高于先停止再重新创建

前置条件

timer 指针不为 NULL，且 timer->handler 不为 NULL
interval 对应的 Tick 数须大于 0

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待修改的定时器结构体指针非NULL，timer->handler非NULL

interval unsigned int 新的超时时间单位：ms，对应Tick数须大于0

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 修改成功定时器超时时间修改并重启成功

OSAL_FAILURE(-1) 修改失败参数无效或内核操作失败

osal_timer_start_on

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

头文件清单

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

功能说明

在指定CPU上启动定时器
支持 SMP 场景下的定时器绑定

前置条件

timer 指针不为 NULL
定时器已通过 osal_timer_init() 初始化成功
仅支持 Linux 系统

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待启动的定时器结构体指针非NULL，已初始化

delay unsigned long 延迟时间 -

cpu int 目标CPU编号 -

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 启动成功定时器在指定CPU上启动成功

OSAL_FAILURE(-1) 启动失败启动失败

osal_timer_stop

int osal_timer_stop(osal_timer *timer)

头文件清单

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

功能说明

停止定时器，对活动和非活动定时器均有效
停止处于活动状态的定时器返回 1，停止已停止的定时器返回 0

前置条件

timer 指针不为 NULL
定时器已通过 osal_timer_init() 初始化成功

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待停止的定时器结构体指针非NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

1(1) 停止成功，定时器处于活动状态定时器正在运行时被停止（仅 Linux 和 LiteOS 支持）

OSAL_SUCCESS(0) 停止成功，定时器已停止定时器已处于停止状态

OSAL_FAILURE(-1) 停止失败内核定时器停止操作失败

osal_timer_destroy

int osal_timer_destroy(osal_timer *timer)

头文件清单

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

功能说明

销毁定时器，释放内核定时器资源
模块退出时必须调用此接口释放定时器，否则将导致内存泄漏

前置条件

timer 指针不为 NULL
定时器已通过 osal_timer_init() 初始化成功

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待销毁的定时器结构体指针非NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 销毁成功定时器销毁成功

OSAL_FAILURE(-1) 销毁失败参数无效或内核定时器删除失败

osal_timer_get_private_data

unsigned long osal_timer_get_private_data(const void *sys_data)

头文件清单

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

功能说明

在定时器回调函数中获取可用的私有数据参数
定时器回调函数的参数不能直接使用，需通过此接口转换后获取
将系统传入的回调参数转换为用户初始化时设置的 data 值

前置条件

sys_data 为定时器回调函数的入参

入参

名称参数类型详细说明约束取值范围

sys_data const void * 传递给回调函数的参数非NULL

返回值

返回类型：unsigned long

返回可直接使用的私有数据参数值。

osal_timer_destroy_sync

int osal_timer_destroy_sync(osal_timer *timer)

头文件清单

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

功能说明

同步销毁定时器，停止定时器并等待回调函数执行完成
与 osal_timer_destroy 的区别在于 SMP 场景下可确保其他 CPU 上的回调已执行完毕
仅支持 Linux 系统

前置条件

timer 指针不为 NULL
调用者须确保定时器不会被重新启动
不可在中断上下文中调用（irqsafe 定时器除外）
调用者不可持有阻止回调完成的锁
定时器回调不可调用 add_timer_on()

入参

名称参数类型详细说明约束取值范围

timer osal_timer * 待同步销毁的定时器结构体指针非NULL

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 销毁成功定时器同步销毁成功

OSAL_FAILURE(-1) 销毁失败销毁失败

osal_sched_clock

unsigned long long osal_sched_clock(void)

头文件清单

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

功能说明

获取系统时间，单位为纳秒
仅支持 Linux 和 LiteOS 系统

前置条件

无

返回值

返回类型：unsigned long long

返回当前系统时间（纳秒）。

osal_get_jiffies

unsigned long long osal_get_jiffies(void)

头文件清单

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

功能说明

获取系统 Tick 数（LiteOS）或 jiffies 数（Linux）
支持 Linux、LiteOS、FreeRTOS 系统

前置条件

无

返回值

返回类型：unsigned long long

返回系统 Tick/jiffies 数。

osal_msecs_to_jiffies

unsigned long osal_msecs_to_jiffies(const unsigned int m)

头文件清单

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

功能说明

将毫秒时间转换为 Tick/jiffies 数
支持 Linux、LiteOS、FreeRTOS 系统

前置条件

无

入参

名称参数类型详细说明约束取值范围

m const unsigned int 待转换的毫秒时间单位：ms

返回值

返回类型：unsigned long

返回转换后的 Tick/jiffies 数。

osal_jiffies_to_msecs

unsigned int osal_jiffies_to_msecs(const unsigned int n)

头文件清单

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

功能说明

将 Tick/jiffies 数转换为毫秒时间
若转换结果超过 0xFFFFFFFF，返回 0xFFFFFFFF
支持 Linux、LiteOS、FreeRTOS 系统

前置条件

无

入参

名称参数类型详细说明约束取值范围

n const unsigned int 待转换的 Tick/jiffies 数 -

返回值

返回类型：unsigned int

返回转换后的毫秒时间，若超过 0xFFFFFFFF 则返回 0xFFFFFFFF。

osal_get_cycle_per_tick

unsigned int osal_get_cycle_per_tick(void)

头文件清单

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

功能说明

获取单个 Tick 对应的时钟周期数
仅支持 LiteOS 系统

前置条件

无

返回值

返回类型：unsigned int

返回单个 Tick 对应的时钟周期数。

osal_gettimeofday

void osal_gettimeofday(osal_timeval *tv)

头文件清单

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

功能说明

获取当前系统内核时间
支持 Linux、LiteOS、FreeRTOS 系统

前置条件

tv 指针不为 NULL

入参

名称参数类型详细说明约束取值范围

tv osal_timeval * 输出时间结构体指针非NULL

出参

名称数据类型输出说明

tv osal_timeval * 当前系统内核时间，包含秒和微秒

参考案例

src/middleware/services/wifi_service/service/soc_wifi_service_api.c

osal_hrtimer_create

int osal_hrtimer_create(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

创建高精度定时器并初始化定时器参数
调用前须对 hrtimer->handler 和 hrtimer->interval 赋值，创建后不可再修改
模块退出时必须调用 osal_hrtimer_destroy 释放定时器，否则将导致内存泄漏
仅支持 LiteOS 系统

前置条件

hrtimer 指针不为 NULL，且 hrtimer->timer 须为 NULL
hrtimer->handler 已赋值
hrtimer->interval 不得超过 ULONG_MAX / 1000

入参

名称参数类型详细说明约束取值范围

hrtimer osal_hrtimer * 待创建的高精度定时器结构体指针非NULL，hrtimer->timer为NULL，hrtimer->handler非NULL

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 创建成功高精度定时器创建成功

OSAL_FAILURE(-1) 创建失败参数无效或内核定时器创建失败

Kconfig配置

配置项宏类型说明默认值

LOSCFG_COMPAT_LINUX_HRTIMER 功能宏支持 OSAL HRTimer 接口功能 n

osal_hrtimer_start

int osal_hrtimer_start(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

启动高精度定时器，将定时器节点加入全局链表并开始计时
仅支持 LiteOS 系统

前置条件

hrtimer 指针不为 NULL，且 hrtimer->timer 不为 NULL
高精度定时器已通过 osal_hrtimer_create() 创建成功
hrtimer->interval 不得超过 ULONG_MAX / 1000

入参

名称参数类型详细说明约束取值范围

hrtimer osal_hrtimer * 待启动的高精度定时器结构体指针非NULL，hrtimer->timer非NULL

返回值

返回类型：int

返回值文字含义触发场景

0(0) 启动成功高精度定时器启动成功

-1(-1) 启动失败高精度定时器启动失败

1(1) 定时器节点已在链表中高精度定时器节点已存在于链表

Kconfig配置

配置项宏类型说明默认值

LOSCFG_COMPAT_LINUX_HRTIMER 功能宏支持 OSAL HRTimer 接口功能 n

osal_hrtimer_destroy

int osal_hrtimer_destroy(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

销毁高精度定时器，取消定时器并释放内存资源
若指针为 NULL 或定时器节点不存在，则销毁失败
仅支持 LiteOS 系统

前置条件

hrtimer 指针不为 NULL，且 hrtimer->timer 不为 NULL
高精度定时器已通过 osal_hrtimer_create() 创建成功

入参

名称参数类型详细说明约束取值范围

hrtimer osal_hrtimer * 待销毁的高精度定时器结构体指针非NULL，hrtimer->timer非NULL

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 销毁成功高精度定时器销毁成功

OSAL_FAILURE(-1) 销毁失败参数无效

Kconfig配置

配置项宏类型说明默认值

LOSCFG_COMPAT_LINUX_HRTIMER 功能宏支持 OSAL HRTimer 接口功能 n

Enumerations

osal_hrtimer_restart

typedef enum {
    OSAL_HRTIMER_NORESTART,
    OSAL_HRTIMER_RESTART
} 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 * 内核定时器句柄，初始化前须置 NULL

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_rtc_time

typedef struct {
    int tm_sec;
    int tm_min;
    int tm_hour;
    int tm_mday;
    int tm_mon;
    int tm_year;
    int tm_wday;
    int tm_yday;
    int tm_isdst;
} osal_rtc_time;

成员说明：

成员名称数据类型描述

tm_sec int 秒

tm_min int 分

tm_hour int 时

tm_mday int 月内日

tm_mon int 月

tm_year int 年

tm_wday int 周内日

tm_yday int 年内日

tm_isdst int 夏令时标志

osal_hrtimer

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

成员说明：

成员名称数据类型描述

timer void * 内核高精度定时器句柄，创建前须置 NULL

handler osal_hrtimer_restart ()(void timer) 高精度定时器超时回调函数指针

interval unsigned long 定时器超时时间，单位：ms

接口名称	功能简述
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	获取系统Tick/jiffies数
osal_msecs_to_jiffies	毫秒转换为Tick/jiffies
osal_jiffies_to_msecs	Tick/jiffies转换为毫秒
osal_get_cycle_per_tick	获取单个Tick对应的时钟周期数
osal_gettimeofday	获取当前系统内核时间
osal_hrtimer_create	创建高精度定时器
osal_hrtimer_start	启动高精度定时器
osal_hrtimer_destroy	销毁高精度定时器

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	初始化成功	定时器创建成功
OSAL_FAILURE(-1)	初始化失败	参数无效或内核定时器创建失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	启动成功	定时器启动成功
OSAL_FAILURE(-1)	启动失败	参数无效或内核定时器启动失败

名称	参数类型	详细说明	约束取值范围
timer	osal_timer *	待修改的定时器结构体指针	非NULL，timer->handler非NULL
interval	unsigned int	新的超时时间	单位：ms，对应Tick数须大于0

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	修改成功	定时器超时时间修改并重启成功
OSAL_FAILURE(-1)	修改失败	参数无效或内核操作失败

名称	参数类型	详细说明	约束取值范围
timer	osal_timer *	待启动的定时器结构体指针	非NULL，已初始化
delay	unsigned long	延迟时间	-
cpu	int	目标CPU编号	-

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	启动成功	定时器在指定CPU上启动成功
OSAL_FAILURE(-1)	启动失败	启动失败

返回值	文字含义	触发场景
1(1)	停止成功，定时器处于活动状态	定时器正在运行时被停止（仅 Linux 和 LiteOS 支持）
OSAL_SUCCESS(0)	停止成功，定时器已停止	定时器已处于停止状态
OSAL_FAILURE(-1)	停止失败	内核定时器停止操作失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	销毁成功	定时器销毁成功
OSAL_FAILURE(-1)	销毁失败	参数无效或内核定时器删除失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	销毁成功	定时器同步销毁成功
OSAL_FAILURE(-1)	销毁失败	销毁失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	创建成功	高精度定时器创建成功
OSAL_FAILURE(-1)	创建失败	参数无效或内核定时器创建失败

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

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	销毁成功	高精度定时器销毁成功
OSAL_FAILURE(-1)	销毁失败	参数无效

枚举成员	取值	描述
OSAL_HRTIMER_NORESTART	0	定时器不复位
OSAL_HRTIMER_RESTART	1	定时器须复位

成员名称	数据类型	描述
timer	void *	内核定时器句柄，初始化前须置 NULL
handler	void (*)(unsigned long)	定时器超时回调函数指针
data	unsigned long	传递给回调函数的私有数据
interval	unsigned int	定时器超时时间，单位：ms

成员名称	数据类型	描述
tm_sec	int	秒
tm_min	int	分
tm_hour	int	时
tm_mday	int	月内日
tm_mon	int	月
tm_year	int	年
tm_wday	int	周内日
tm_yday	int	年内日
tm_isdst	int	夏令时标志

成员名称	数据类型	描述
timer	void *	内核高精度定时器句柄，创建前须置 NULL
handler	osal_hrtimer_restart ()(void timer)	高精度定时器超时回调函数指针
interval	unsigned long	定时器超时时间，单位：ms