Zephyr内核对象--k_timer简介
本文分析说明zephyr的k_timer机制。
前文参考 [1] Zephyr内核Timeout模块简介
k_timer使用内核系统时钟测量时间，通过向其注册callback可以在指定的时刻执行应用定义的行为，也可以用于周期性计数，并由应用读取其计数状态。
特性 链接到标题
只要内存足够，内核不限制timer的数量。 Timer有两个关键时间参数duration和period
- duration：指定timer第一次到期的时间
- period: 指定timer第一次到期后，之后的到期时间间隔
可以注册到期回调函数，duration/period到期后会在时钟中断中回调该函数.
可以注册停止回调函数，在执行stop timer的线程中回调该函数.
timer维护一个status值，用于指示上一次读取状态到现在timer到期了多少次.
下图描述了以上特性
使用 链接到标题
API 链接到标题
#define K_TIMER_DEFINE(name, expiry_fn, stop_fn)
作用:定义一个k_timer，并初始化
name: k_timer name
expiry_fn: 到期回调
stop_fn：停止回调
void k_timer_init(struct k_timer *timer, k_timer_expiry_t expiry_fn, k_timer_stop_t stop_fn)
作用:初始化k_timer
timer: k_timer
expiry_fn: 到期回调
stop_fn：停止回调
void k_timer_start(struct k_timer *timer, k_timeout_t duration, k_timeout_t period)
作用:启动k_timer
timer: k_timer
duration: 第一次到期时间，不能传入K_FOREVER，传入K_NO_WAIT时，会在最近的一个tick中断到来时立即过期。
period：后续周期的到期时间，当传入K_FOREVER或K_NO_WAIT，在duration过期后timer自动停止
void k_timer_stop(struct k_timer *timer)
作用:停止k_timer
timer: k_timer
uint32_t k_timer_status_get(struct k_timer *timer)
作用:获取从上次读取到当前k_timer到期了多少次，每次读取后status被清0
timer: k_timer
返回值：到期次数
uint32_t k_timer_status_sync(struct k_timer *timer)
作用:等待timer到期或停止
timer: k_timer
返回值：到期次数
k_ticks_t k_timer_expires_ticks(const struct k_timer *timer)
作用:获取timer即将到期的时间
timer: k_timer
返回值：tick数
k_ticks_t k_timer_remaining_ticks(const struct k_timer *timer)
作用:获取timer还有多久到期
timer: k_timer
返回值：tick数
uint32_t k_timer_remaining_get(struct k_timer *timer)
作用:获取timer还有多久到期
timer: k_timer
返回值：毫秒数
void k_timer_user_data_set(struct k_timer *timer, void *user_data)
作用:设置timer的user data，该data会被传递给回调函数
timer: k_timer
user_data： user data
void *k_timer_user_data_get(const struct k_timer *timer)
作用:获取timer的user data，该data会被传递给回调函数
timer: k_timer
返回值： user data
使用说明 链接到标题
初始化 链接到标题
先定义初始化一个timer，下面两种方式的效果是一样的 使用函数
struct k_timer my_timer;
extern void my_expiry_function(struct k_timer *timer_id)
{
//过期处理，可以使用timer_id->user_data
}
k_timer_init(&my_timer, my_expiry_function, NULL);
使用宏
K_TIMER_DEFINE(my_timer, my_expiry_function, NULL);
功能使用 链接到标题
//启动后2s会调用一次my_expiry_function，然后每200ms会调用一次my_expiry_function
k_timer_start(&my_timer, K_SECONDS(2), K_SECONDS(200));
//等待过期发生
k_timer_status_sync(&my_sync_timer);
k_sleep(K_SECONDS(5))
if (k_timer_status_get(&my_status_timer) > 0) {
//检查是否有timer过期发生
}
//停止timer
k_timer_stop(&my_timer);
使用注意事项 链接到标题
- 过期回调在中断中执行，要做耗费时间的动作
- k_timer过期可以保证至少过了多久，不能保证精确的定时
- 但其精度比k_sleep/k_usleep要高
- 测量执行时间时不建议使用k_timer，建议直接读硬件时钟
实现 链接到标题
k_timer的代码是kernel/timer.c，k_timer是由timeout模块实现，timeout的分析参考[1]
初始化timer 链接到标题
一个k_timer的结构体如下
struct k_timer {
//timeout，参考[1]
struct _timeout timeout;
//timer wait_q，用于timer sync等待
_wait_q_t wait_q;
//过期回调，在ISR中执行
void (*expiry_fn)(struct k_timer *timer);
//停止回调，在调用stop timer的线程内回调
void (*stop_fn)(struct k_timer *timer);
//timer周期时间
k_timeout_t period;
//timer到期的次数记录，读取/停止/启动timer都会清0
uint32_t status;
//timer user data
void *user_data;
};
timer的初始化就是对k_timer的数据结构各字段赋值
void k_timer_init(struct k_timer *timer,
k_timer_expiry_t expiry_fn,
k_timer_stop_t stop_fn)
{
//初始化callback及status
timer->expiry_fn = expiry_fn;
timer->stop_fn = stop_fn;
timer->status = 0U;
//初始化wait_q
if (IS_ENABLED(CONFIG_MULTITHREADING)) {
z_waitq_init(&timer->wait_q);
}
//初始化timeout
z_init_timeout(&timer->timeout);
timer->user_data = NULL;
z_object_init(timer);
}
启动Timer 链接到标题
k_timer_start->z_impl_k_timer_start
void z_impl_k_timer_start(struct k_timer *timer, k_timeout_t duration,
k_timeout_t period)
{
//duration不能为K_FOREVER
if (K_TIMEOUT_EQ(duration, K_FOREVER)) {
return;
}
//计算符合timeout模块的ticks
if (!K_TIMEOUT_EQ(period, K_FOREVER) && period.ticks != 0 &&
Z_TICK_ABS(period.ticks) < 0) {
period.ticks = MAX(period.ticks - 1, 1);
}
if (Z_TICK_ABS(duration.ticks) < 0) {
duration.ticks = MAX(duration.ticks - 1, 0);
}
//启动新的timer前，先中止正在允许的timer
(void)z_abort_timeout(&timer->timeout);
timer->period = period;
timer->status = 0U;
//向timeout添加一个超时，在duration后会调用z_timer_expiration_handler
z_add_timeout(&timer->timeout, z_timer_expiration_handler,
duration);
}
timer到期 链接到标题
duration到期后会调用z_timer_expiration_handler, 之后在z_timer_expiration_handler内再次添加period的timeout
void z_timer_expiration_handler(struct _timeout *t)
{
struct k_timer *timer = CONTAINER_OF(t, struct k_timer, timeout);
struct k_thread *thread;
//如果period不为K_NO_WAIT,K_FOREVER,重新添加timeout，在period后会调用z_impl_k_timer_status_sync
if (!K_TIMEOUT_EQ(timer->period, K_NO_WAIT) &&
!K_TIMEOUT_EQ(timer->period, K_FOREVER)) {
z_add_timeout(&timer->timeout, z_timer_expiration_handler,
timer->period);
}
//更新status，记录过期的次数
timer->status += 1U;
//调用过期函数
if (timer->expiry_fn != NULL) {
timer->expiry_fn(timer);
}
if (!IS_ENABLED(CONFIG_MULTITHREADING)) {
return;
}
//检查是否由线程在等待timer到期
thread = z_waitq_head(&timer->wait_q);
if (thread == NULL) {
return;
}
//将等待timer到期的线程从wait_q中移除
z_unpend_thread_no_timeout(thread);
//将等待timer的线程重新加入到ready_q中并选出最合适的线程，z_timer_expiration_handler是在timeout模块中clock ISR中执行，因此在退出ISR时会进行上下文切换
arch_thread_return_value_set(thread, 0);
z_ready_thread(thread);
}
等待timer到期 链接到标题
线程可以通过k_timer_status_sync等待timer到期，timer到期后会在z_timer_expiration_handler将等待的线程重新加入到ready_q k_timer_status_sync->z_impl_k_timer_status_sync
uint32_t z_impl_k_timer_status_sync(struct k_timer *timer)
{
//ISR内不能等待
__ASSERT(!arch_is_in_isr(), "");
k_spinlock_key_t key = k_spin_lock(&lock);
uint32_t result = timer->status;
//status为0说明还timer没有过期，需要等待
if (result == 0U) {
if (!z_is_inactive_timeout(&timer->timeout)) {
//等待timer过期
(void)z_pend_curr(&lock, key, &timer->wait_q, K_FOREVER);
//timer过期会先发生中断，更新status，再将等待的线程重新调度，才能执行到这里。这里要重新取一次status
key = k_spin_lock(&lock);
result = timer->status;
} else {
/* timer is already stopped */
}
} else {
//status为0，已经过期无需等待
}
//清0 status
timer->status = 0U;
k_spin_unlock(&lock, key);
//返回status
return result;
}
通过读取过期次数状态也能知道timer是否过期，只是不会发生等待
uint32_t z_impl_k_timer_status_get(struct k_timer *timer)
{
k_spinlock_key_t key = k_spin_lock(&lock);
uint32_t result = timer->status;
//清0 status
timer->status = 0U;
k_spin_unlock(&lock, key);
//返回status
return result;
}
停止timer 链接到标题
停止timer会将status清0，并将等待该timer的线程恢复运行
void z_impl_k_timer_stop(struct k_timer *timer)
{
//中止正在执行的timer
int inactive = z_abort_timeout(&timer->timeout) != 0;
if (inactive) {
return;
}
//执行停止回调
if (timer->stop_fn != NULL) {
timer->stop_fn(timer);
}
if (IS_ENABLED(CONFIG_MULTITHREADING)) {
struct k_thread *pending_thread = z_unpend1_no_timeout(&timer->wait_q);
//检查是否有线程在等待该timer，如果有恢复该线程，并进行调度
if (pending_thread != NULL) {
z_ready_thread(pending_thread);
z_reschedule_unlocked();
}
}
}
其它API 链接到标题
user data 链接到标题
user data只是简单的设置和读取k_timer结构体内的user_data字段，这里就不再列出来 k_timer_user_data_get->z_impl_k_timer_user_data_get k_timer_user_data_set->z_impl_k_timer_user_data_set
时间的获取 链接到标题
时间的获取都是封装timeout的API，可参考[1].这里列出调用关系，无需再做详细分析 k_timer_expires_ticks->z_impl_k_timer_expires_ticks->z_timeout_expires k_timer_remaining_ticks->z_impl_k_timer_remaining_ticks->z_timeout_remaining k_timer_remaining_get->k_ticks_to_ms_floor32(k_timer_remaining_ticks)