跳转至
项目
版本
全文检索

time

time 提供操作系统抽象层定时器功能，支持普通定时器与高精度定时器的创建、启停与销毁，以及系统时间获取与毫秒/Tick转换等时间操作。

头文件清单

#include "include/osal/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包含的cycle数
osal_gettimeofday 获取当前系统内核时间
osal_hrtimer_create 创建高精度定时器
osal_hrtimer_start 启动高精度定时器
osal_hrtimer_destroy 销毁高精度定时器

Functions

osal_timer_init 

int osal_timer_init(osal_timer *timer)

头文件清单

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

功能说明

  • 初始化定时器，分配内核定时器资源并注册回调函数
  • 支持linux、liteos、freertos系统

前置条件

  • 调用时序约束：调用前需对timer->handler和timer->data赋值，初始化后不可再修改
  • 依赖关系：模块退出时必须调用osal_timer_destroy释放定时器，否则将导致内存泄漏

入参

名称 参数类型 详细说明 约束取值范围
timer osal_timer * 待初始化的定时器结构体指针 非NULL，timer->handler非NULL，timer->timer为NULL

出参

名称 数据类型 输出说明
timer osal_timer * 函数分配内核定时器资源并写入timer->timer字段

返回值

  • 返回类型：int
返回值 文字含义 触发场景
OSAL_SUCCESS(0) 初始化成功 定时器资源分配成功
OSAL_FAILURE(-1) 初始化失败 参数无效或interval为0或内核定时器创建失败

osal_timer_start 

int osal_timer_start(osal_timer *timer)

头文件清单

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

功能说明

  • 启动已初始化的定时器，内核将在定时器中断中执行回调
  • 定时器已过期时将在下一个Tick执行回调
  • 支持linux、liteos、freertos系统

前置条件

  • 调用时序约束：定时器已通过osal_timer_init初始化成功
  • 依赖关系：timer->handler和timer->data字段必须在启动前已赋值

入参

名称 参数类型 详细说明 约束取值范围
timer osal_timer * 待启动的定时器结构体指针 非NULL，已初始化

返回值

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

osal_timer_mod 

int osal_timer_mod(osal_timer *timer, unsigned int interval)

头文件清单

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

功能说明

  • 修改定时器超时时间，若定时器未激活则将其激活
  • 此接口是更新活跃定时器超时字段的方式
  • 支持linux、liteos、freertos系统

前置条件

  • 调用时序约束：定时器已通过osal_timer_init初始化
  • 依赖关系：timer->handler非空且interval转换为Tick后大于0

入参

名称 参数类型 详细说明 约束取值范围
timer osal_timer * 待修改的定时器结构体指针 非NULL，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 "include/osal/time/osal_timer.h"

功能说明

  • 在指定CPU上启动定时器
  • 用于将定时器绑定到特定CPU核执行
  • 仅支持linux系统

前置条件

  • 调用时序约束：定时器已通过osal_timer_init初始化
  • 上下文限制：cpu参数为有效的CPU编号

入参

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

返回值

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

osal_timer_stop 

int osal_timer_stop(osal_timer *timer)

头文件清单

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

功能说明

  • 停止定时器，对活跃和非活跃定时器均有效
  • 返回值区分定时器是否处于pending状态
  • 支持linux、liteos、freertos系统

前置条件

  • 调用时序约束：定时器已通过osal_timer_init初始化
  • 依赖关系：定时器处于活跃或非活跃状态均可调用

入参

名称 参数类型 详细说明 约束取值范围
timer osal_timer * 待停止的定时器结构体指针 非NULL

返回值

  • 返回类型：int
返回值 文字含义 触发场景
1 停止成功，定时器处于pending状态 定时器活跃并被成功停止（仅Linux和LiteOS）
OSAL_SUCCESS(0) 停止成功，定时器已处于停止状态 定时器未在运行
OSAL_FAILURE(-1) 停止失败 内核定时器停止操作失败

osal_timer_destroy 

int osal_timer_destroy(osal_timer *timer)

头文件清单

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

功能说明

  • 销毁定时器，释放内核定时器资源
  • 模块退出时必须调用此接口释放定时器，否则将导致内存泄漏
  • 支持linux、liteos、freertos系统

前置条件

  • 调用时序约束：定时器已通过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 "include/osal/time/osal_timer.h"

功能说明

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

前置条件

  • 调用时序约束：当前接口需在定时器回调函数中调用
  • 依赖关系：sys_data参数必须为定时器回调函数接收到的原始参数

入参

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

返回值

  • 返回类型：unsigned long
返回值 文字含义 触发场景
unsigned long 可直接使用的参数值 回调函数中调用

osal_timer_destroy_sync 

int osal_timer_destroy_sync(osal_timer *timer)

头文件清单

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

功能说明

  • 同步销毁定时器，停止定时器并等待回调函数在其他CPU上执行完成
  • 在SMP系统中，与osal_timer_stop的区别在于确保回调函数在所有CPU上执行完毕
  • 仅支持linux系统

前置条件

  • 调用时序约束：调用者必须阻止定时器被重新启动，否则此接口无意义
  • 调用上下文约束：禁止在中断上下文中调用（除非定时器为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 "include/osal/time/osal_timer.h"

功能说明

  • 获取系统纳秒时间
  • 用于高精度时间测量场景
  • 支持linux、liteos系统

返回值

  • 返回类型：unsigned long long
返回值 文字含义 触发场景
unsigned long long 当前系统纳秒时间 调用成功

osal_get_jiffies 

unsigned long long osal_get_jiffies(void)

头文件清单

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

功能说明

  • 获取系统Tick数（LiteOS）或jiffies数（Linux）
  • 用于基于Tick的时间计算和定时器相关操作
  • 支持linux、liteos、freertos系统

返回值

  • 返回类型：unsigned long long
返回值 文字含义 触发场景
unsigned long long 当前Tick/jiffies数 调用成功

osal_msecs_to_jiffies 

unsigned long osal_msecs_to_jiffies(const unsigned int m)

头文件清单

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

功能说明

  • 将毫秒转换为Tick/jiffies
  • 用于定时器相关的毫秒到Tick转换
  • 支持linux、liteos、freertos系统

入参

名称 参数类型 详细说明 约束取值范围
m const unsigned int 待转换的毫秒时间 0 ~ 4294967294（UINT_MAX-1），UINT_MAX时返回UINT_MAX

返回值

  • 返回类型：unsigned long
返回值 文字含义 触发场景
unsigned long 转换后的Tick/jiffies数 正常转换
UINT_MAX 输入为UINT_MAX时的特殊返回值 m == UINT_MAX

osal_jiffies_to_msecs 

unsigned int osal_jiffies_to_msecs(const unsigned int n)

头文件清单

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

功能说明

  • 将Tick/jiffies转换为毫秒
  • 转换结果超过0xFFFFFFFF时返回0xFFFFFFFF
  • 支持linux、liteos、freertos系统

入参

名称 参数类型 详细说明 约束取值范围
n const unsigned int 待转换的Tick/jiffies数 0 ~ 4294967295

返回值

  • 返回类型：unsigned int
返回值 文字含义 触发场景
unsigned int 转换后的毫秒数 正常转换，若值超过0xFFFFFFFF则返回0xFFFFFFFF

osal_get_cycle_per_tick 

unsigned int osal_get_cycle_per_tick(void)

头文件清单

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

功能说明

  • 获取单个Tick包含的cycle数
  • 用于需要精确到CPU cycle的时间计算
  • 仅支持liteos系统

返回值

  • 返回类型：unsigned int
返回值 文字含义 触发场景
unsigned int 单个Tick包含的cycle数 调用成功

osal_gettimeofday 

void osal_gettimeofday(osal_timeval *tv)

头文件清单

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

功能说明

  • 获取当前系统内核时间
  • 输出时间包含秒和微秒两部分
  • 支持linux、liteos、freertos系统

出参

名称 数据类型 输出说明
tv osal_timeval * 当前系统内核时间，tv_sec为秒，tv_usec为微秒

osal_hrtimer_create 

int osal_hrtimer_create(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

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

前置条件

  • 调用时序约束：调用前需对hrtimer->handler和hrtimer->interval赋值，初始化后不可再修改
  • 依赖关系：模块退出时必须调用osal_hrtimer_destroy释放定时器，否则将导致内存泄漏

入参

名称 参数类型 详细说明 约束取值范围
hrtimer osal_hrtimer * 待初始化的高精度定时器结构体指针 非NULL，timer为NULL，handler非NULL

出参

名称 数据类型 输出说明
hrtimer osal_hrtimer * 函数分配内核高精度定时器资源并写入hrtimer->timer字段

返回值

  • 返回类型：int
返回值 文字含义 触发场景
OSAL_SUCCESS(0) 创建成功 高精度定时器创建成功
OSAL_FAILURE(-1) 创建失败 参数无效或interval过大或内存分配失败或内核创建失败

osal_hrtimer_start 

int osal_hrtimer_start(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

  • 将高精度定时器节点添加到全局链表并启动计时
  • 启动前需确保hrtimer已通过osal_hrtimer_create创建成功
  • 仅支持liteos系统

前置条件

  • 调用时序约束：定时器已通过osal_hrtimer_create创建成功
  • 依赖关系：hrtimer->interval不超过ULONG_MAX/1000

入参

名称 参数类型 详细说明 约束取值范围
hrtimer osal_hrtimer * 待启动的高精度定时器结构体指针 非NULL，timer非NULL

返回值

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

osal_hrtimer_destroy 

int osal_hrtimer_destroy(osal_hrtimer *hrtimer)

头文件清单

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

功能说明

  • 删除已存在的高精度定时器
  • 若指针为空或定时器节点不存在，则删除失败
  • 仅支持liteos系统

前置条件

  • 调用时序约束：定时器已通过osal_hrtimer_create创建成功
  • 依赖关系：hrtimer->timer非空

入参

名称 参数类型 详细说明 约束取值范围
hrtimer osal_hrtimer * 待销毁的高精度定时器结构体指针 非NULL，timer非NULL

返回值

  • 返回类型：int
返回值 文字含义 触发场景
OSAL_SUCCESS(0) 销毁成功 高精度定时器删除成功
OSAL_FAILURE(-1) 销毁失败 参数无效或定时器节点不存在

Enumerations

timer_mode_enum 

enum timer_mode_enum {
    OSAL_TIMER_MODE_ONESHOT,
    OSAL_TIMER_MODE_PERIOD
};
枚举成员 取值 描述
OSAL_TIMER_MODE_ONESHOT 0 单次触发定时器模式
OSAL_TIMER_MODE_PERIOD 1 周期触发定时器模式

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.
#ifdef OSAL_SUPPORT_PERIOD_TIMER
    unsigned short runmode; // runmode, 0: oneshot timer, 1 or other: period timer
    unsigned short isAlign; // isAlign, 0: no align, 1 or other: align
#endif
} osal_timer;

成员说明

成员名称 数据类型 描述
timer void * 内核定时器句柄，初始化前为NULL
handler void (*)(unsigned long) 定时器回调函数指针，定时器超时中断时由内核调用，参数为data字段值
data unsigned long 传递给回调函数的参数
interval unsigned int 定时器超时时间，单位：ms
runmode unsigned short 运行模式，0：单次定时器，1或其他：周期定时器（OSAL_SUPPORT_PERIOD_TIMER宏启用时有效）
isAlign unsigned short 对齐标志，0：不对齐，1或其他：对齐（OSAL_SUPPORT_PERIOD_TIMER宏启用时有效）

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 timer) 高精度定时器回调函数指针，定时器超时时由内核调用，返回OSAL_HRTIMER_RESTART时重启定时器
interval unsigned long 定时器间隔，单位：ms

Macros

OSAL_SUCCESS 

#define OSAL_SUCCESS 0

OSAL_FAILURE 

#define OSAL_FAILURE (-1)