Zephyr stack

文章目录

• 简介
• 数据结构
• 栈初始化
• 入栈
• 出栈
• 清理栈
• 示例

简介

在 Zephyr 中 k_stack 是一个固定大小的栈对象，它提供了以下功能：

• k_stack_init：初始化栈对象。
• k_stack_alloc_init：分配并初始化栈对象。
• k_stack_cleanup：清理栈对象。
• k_stack_push：将数据压入栈中。
• k_stack_pop：从栈中弹出数据。

数据结构

typedef uintptr_t stack_data_t;

struct k_stack {
	_wait_q_t wait_q;
	struct k_spinlock lock;
	stack_data_t *base, *next, *top;

	uint8_t flags;

	SYS_PORT_TRACING_TRACKING_FIELD(k_stack)
};

• struct k_stack 是一个固定大小的栈对象，它包含以下成员：

  • wait_q：等待队列，用于存储等待数据的线程。
  • lock：自旋锁，用于保护栈对象。
  • next：指向下一个可用的元素的指针。
  • base：指向栈底的指针。
  • top：指向栈顶的指针。
  • flags：标志位，用于表示栈对象的属性。

• 其中，wait_q 和 lock 的作用比较明显，这里不再赘述，下面我们来看一下其他成员的用途：

  • next、base 和 top 三个成员用于维护栈中元素的位置。next 指向下一个可用的元素，base 指向栈底，top 指向栈顶，当 next 等于 top 时，表示栈已满。
  • flags 标志位用于表示栈对象的属性。目前只定义了一个标志位 K_STACK_FLAG_ALLOC，表示该栈对象是通过动态内存分配得到的。

• stack_data_t 是一个指针类型，用于存储数据的地址。

栈初始化

• 栈是一种容器类型的数据结构，按照其内部的存储方式可以分为顺序栈和链栈，两者之间的差别在于相邻节点之间在内存上是否连续。
• Zephyr 中的栈是顺序栈，它需要一块内存用于存放数据所在地址，并使用这块内存初始化 k_stack 对象。

void k_stack_init(struct k_stack *stack, stack_data_t *buffer, uint32_t num_entries)

void k_stack_init(struct k_stack *stack, stack_data_t *buffer,
		  uint32_t num_entries)
{
	z_waitq_init(&stack->wait_q);
	stack->lock = (struct k_spinlock) {};
	stack->next = stack->base = buffer;
	stack->top = stack->base + num_entries;

	SYS_PORT_TRACING_OBJ_INIT(k_stack, stack);
	z_object_init(stack);
}

• k_stack_init 需要使用者提供栈所需要的内存，并告知其容量，用于初始化 k_stack_init。

int32_t k_stack_alloc_init(struct k_stack *stack, uint32_t num_entries)

• 该函数的另一个形式是通过堆申请所需要的内存，并通过 flags 标记内存来源，以便在不需要使用时，进行内存回收。

int32_t z_impl_k_stack_alloc_init(struct k_stack *stack, uint32_t num_entries)
{
	void *buffer;
	int32_t ret;

	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_stack, alloc_init, stack);

	buffer = z_thread_malloc(num_entries * sizeof(stack_data_t));
	if (buffer != NULL) {
		k_stack_init(stack, buffer, num_entries);
		stack->flags = K_STACK_FLAG_ALLOC;
		ret = (int32_t)0;
	} else {
		ret = -ENOMEM;
	}

	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, alloc_init, stack, ret);

	return ret;
}

入栈

int k_stack_push(struct k_stack *stack, stack_data_t data)

• k_stack_push 用于将数据放入栈中，此处只会将数据的首地址放入栈中，栈不关心数据的具体类型，只负责将其地址放入到栈中保存起来。

int z_impl_k_stack_push(struct k_stack *stack, stack_data_t data)
{
	struct k_thread *first_pending_thread;
	int ret = 0;
	k_spinlock_key_t key = k_spin_lock(&stack->lock);

	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_stack, push, stack);

	/* 栈满时返回错误码 */
	CHECKIF(stack->next == stack->top) {
		ret = -ENOMEM;
		goto out;
	}

	/* 取出等待队列中优先级最高的线程 */
	first_pending_thread = z_unpend_first_thread(&stack->wait_q);
	
	/* 挂起线程非空则直接将 data 中的地址放入该线程中的 swap_data 中，
	 * 然后将其恢复为就绪状态，待其恢复运行后将 swap_data 作为 k_stack_pop 的出栈值。
	 */
	if (first_pending_thread != NULL) {
		z_thread_return_value_set_with_data(first_pending_thread,
						   0, (void *)data);

		z_ready_thread(first_pending_thread);
		z_reschedule(&stack->lock, key);
		goto end;
	} else {
	/* 当前没有被挂起线程，则需要将数据放入到栈中保存 */
		*(stack->next) = data;
		stack->next++;
		goto out;
	}

out:
	k_spin_unlock(&stack->lock, key);

end:
	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, push, stack, ret);

	return ret;
}

出栈

int k_stack_pop(struct k_stack *stack, stack_data_t *data, k_timeout_t timeout)

• 使用 k_stack_pop 时应该注意， data 用于获取数据所在的地址，其应当是一个二级指针强制转换为 stack_data_t * 类型，否则会产生错误。

int z_impl_k_stack_pop(struct k_stack *stack, stack_data_t *data,
		       k_timeout_t timeout)
{
	k_spinlock_key_t key;
	int result;

	key = k_spin_lock(&stack->lock);

	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_stack, pop, stack, timeout);
	
	/* 当栈中非空时从中读取结果并返回 */
	if (likely(stack->next > stack->base)) {
		stack->next--;
		*data = *(stack->next);
		k_spin_unlock(&stack->lock, key);

		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, pop, stack, timeout, 0);

		return 0;
	}

	SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_stack, pop, stack, timeout);
	
	/*  栈空且不需要进行等待时，返回-EBUSY */
	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
		k_spin_unlock(&stack->lock, key);

		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, pop, stack, timeout, -EBUSY);

		return -EBUSY;
	}
	
	/*  栈空且需要进行等待时，挂起当前线程并等待结果 */
	result = z_pend_curr(&stack->lock, key, &stack->wait_q, timeout);
	/* 等待超时，返回 -EAGAIN */
	if (result == -EAGAIN) {
		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, pop, stack, timeout, -EAGAIN);

		return -EAGAIN;
	}
	/* 等待过程中被其他任务唤醒，从 swap_data 中读取结果 */
	*data = (stack_data_t)_current->base.swap_data;

	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, pop, stack, timeout, 0);

	return 0;
}

清理栈

int k_stack_cleanup(struct k_stack *stack)

• 当栈不需要使用之后，从堆中申请的内存需要被释放，同时为了避免将非堆空间的地址传入造成错误，便在创建时通过 K_STACK_FLAG_ALLOC 对其进行了标记，只有该标志位不为0的对象，才会释放其内存。

int k_stack_cleanup(struct k_stack *stack)
{
	SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_stack, cleanup, stack);

	CHECKIF(z_waitq_head(&stack->wait_q) != NULL) {
		SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, cleanup, stack, -EAGAIN);

		return -EAGAIN;
	}

	if ((stack->flags & K_STACK_FLAG_ALLOC) != (uint8_t)0) {
		k_free(stack->base);
		stack->base = NULL;
		stack->flags &= ~K_STACK_FLAG_ALLOC;
	}

	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_stack, cleanup, stack, 0);

	return 0;
}

示例

#include <zephyr.h>
#include <stdio.h>

#define CONFIG_NUM_MBOX_ASYNC_MSGS 10

struct k_mbox_async {
	struct _thread_base thread;		/* dummy thread object */
	struct k_mbox_msg tx_msg;	/* transmit message descriptor */
};

/* stack of unused asynchronous message descriptors */
K_STACK_DEFINE(async_msg_free, CONFIG_NUM_MBOX_ASYNC_MSGS);

static inline void mbox_async_free(struct k_mbox_async *async)
{
	k_stack_push(&async_msg_free, (stack_data_t)async);
}

static inline void mbox_async_alloc(struct k_mbox_async **async)
{
	(void)k_stack_pop(&async_msg_free, (stack_data_t *)async, K_FOREVER);
}

int main(void)
{
	struct k_mbox_async *async;
	
	for(;;)
	{
		mbox_async_alloc(&async);
		mbox_async_free(async);
		k_msleep(1000);
	}
}