Zephyr内核对象--k_timer简介

Creative Commons
本作品采用知识共享署名
发表于 | 分类于 | | 阅读次数：

本文分析说明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，下面两种方式的效果是一样的
使用函数

1
2
3
4
5
6
7
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);

使用宏

1
K_TIMER_DEFINE(my_timer, my_expiry_function, NULL);

功能使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//启动后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的结构体如下

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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的数据结构各字段赋值

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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是否过期，只是不会发生等待

1
2
3
4
5
6
7
8
9
10
11
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的线程恢复运行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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)

参考

https://lgl88911.github.io/2020/04/26/Zephyr%E5%86%85%E6%A0%B8Timeout%E6%A8%A1%E5%9D%97%E7%AE%80%E4%BB%8B/