os_timer.h

学习阁2026/7/20大约 3 分钟附录源码附录

os_timer.h

路径: kernel\include\os_timer.h

功能: 定时器 API 声明头文件。提供面向用户层的定时器操作接口，包括创建、销毁、启动、停止、超时时间设置/获取、单次/周期模式切换等。

核心宏定义:

宏	说明
`OS_TIMER_FLAG_ONE_SHOT` (0x0)	单次定时器标志
`OS_TIMER_FLAG_PERIODIC` (0x1)	周期定时器标志
`OS_TIMER_FLAG_HARD_TIMER` (0x0)	硬件定时器标志（回调在 tick ISR 中执行）
`OS_TIMER_FLAG_SOFT_TIMER` (0x4)	软件定时器标志（回调在 timer task 中执行）
`OS_TIMER_DEFINE(name)`	静态定义定时器控制块（对齐栈要求）
`OS_TIMER_PERIODIC_COMPENSATE`	周期定时器补偿开关（单链表定时器模式下固定为 0）

核心 API 声明:

函数	说明
`os_timer_create`	创建定时器：指定控制块、名称、回调、参数、超时时间和标志
`os_timer_destroy`	销毁定时器
`os_timer_start`	启动定时器
`os_timer_stop`	停止定时器
`os_timer_set_timeout_ticks`	设置超时 tick 数
`os_timer_get_timeout_ticks`	获取超时 tick 数
`os_timer_get_remain_ticks`	获取剩余 tick 数
`os_timer_get_name`	获取定时器名称
`os_timer_is_active`	查询定时器是否激活
`os_timer_set_oneshot`	设置为单次模式
`os_timer_set_periodic`	设置为周期模式
`os_timer_is_periodic`	查询是否为周期模式
`os_timer_check_exist`	检查定时器是否存在
`os_timer_is_soft`	查询是否为软件定时器（仅单链表定时器模式）

关键设计点:

类型隐藏: 通过 typedef struct dummy_timer os_timer_dummy_t 和 os_timer_id 对外隐藏定时器控制块的内部布局
静态创建支持: OS_TIMER_DEFINE(name) 宏允许用户静态分配定时器控制块（对齐到栈对齐要求），避免动态内存分配
硬/软定时器: 仅单链表定时器模式下区分硬定时器（ISR 上下文执行）和软定时器（timer task 上下文执行），哈希桶定时器仅支持软定时器
周期补偿: 单链表定时器模式下 OS_TIMER_PERIODIC_COMPENSATE 固定为 0，不启用周期补偿

/**
 ***********************************************************************************************************************
 * Copyright (c) 2020, China Mobile Communications Group Co.,Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations under the License.
 *
 * @file        os_timer.h
 *
 * @brief       Header file for timer interface.
 *
 * @revision
 * Date         Author          Notes
 * 2020-11-18   OneOS Team      First version.
 ***********************************************************************************************************************
 */

#ifndef __OS_TIMER_LIST_H__
#define __OS_TIMER_LIST_H__

#include <oneos_config.h>
#include <os_types.h>
#include <os_list.h>
#include <os_dummy.h>

#ifdef __cplusplus
extern "C" {
#endif

#ifdef OS_USING_KERNEL_TIMER

#define OS_TIMER_FLAG_ONE_SHOT 0x0U /* Oneshot timer. */
#define OS_TIMER_FLAG_PERIODIC 0x1U /* Periodic timer. */

typedef struct dummy_timer os_timer_dummy_t;
typedef os_timer_dummy_t  *os_timer_id;

#define OS_TIMER_DEFINE(name)                                                                                          \
    OS_ALIGN(OS_ARCH_STACK_ALIGN_SIZE)                                                                                 \
    os_timer_dummy_t name /* Here, actually, it is an array of os_timer_t structure size.                              \
                             The purpose is to serve as a timer control block for                                      \
                             static create of timer. */

#ifdef OS_USING_SINGLE_LIST_TIMER
#if defined(OS_HARD_SINGLE_LIST_TIMER) && defined(OS_SOFT_SINGLE_LIST_TIMER)
#define OS_TIMER_FLAG_HARD_TIMER 0x0U /* Hard timer,the timer's callback function will be called in tick isr. */
#define OS_TIMER_FLAG_SOFT_TIMER 0x4U /* Soft timer,the timer's callback function will be called in timer task. */
#endif                                /* end of OS_HARD_SINGLE_LIST_TIMER & OS_SOFT_SINGLE_LIST_TIMER */
/* used to cfg periodic timer compensate(timeout cb still too long) */
#define OS_TIMER_PERIODIC_COMPENSATE 0
#endif /* end of OS_USING_SINGLE_LIST_TIMER */

extern os_timer_id os_timer_create(os_timer_dummy_t *timer_cb,
                                   const char       *name,
                                   void (*function)(void *parameter),
                                   void     *parameter,
                                   os_tick_t timeout,
                                   uint8_t   flag);

extern os_err_t os_timer_destroy(os_timer_id timer_id);

extern os_err_t os_timer_start(os_timer_id timer_id);
extern os_err_t os_timer_stop(os_timer_id timer_id);

extern os_err_t  os_timer_set_timeout_ticks(os_timer_id timer_id, os_tick_t timeout);
extern os_tick_t os_timer_get_timeout_ticks(os_timer_id timer_id);
extern os_tick_t os_timer_get_remain_ticks(os_timer_id timer_id);
extern const char *os_timer_get_name(os_timer_id timer_id);
extern os_bool_t   os_timer_is_active(os_timer_id timer_id);

extern os_err_t  os_timer_set_oneshot(os_timer_id timer_id);
extern os_err_t  os_timer_set_periodic(os_timer_id timer_id);
extern os_bool_t os_timer_is_periodic(os_timer_id timer_id);
extern os_bool_t os_timer_check_exist(os_timer_id timer_id);

/* Hash timers do not have hardware timers, only software timers */
#ifdef OS_USING_SINGLE_LIST_TIMER
extern os_bool_t os_timer_is_soft(os_timer_id timer_id);
#endif /* end of OS_USING_SINGLE_LIST_TIMER */

#endif /* End of OS_USING_KERNEL_TIMER */

#ifdef __cplusplus
}
#endif

#endif