简介

• events 是Zephyr 提供的一种多线程同步方式，其功能和 FreeRTOS 中的 eventGroup 一样，可以用于等待多个用户事件发生。
• events 对象用于向一个或多个线程发出信号，指示发生了一组自定义事件。
• 线程等待 events 对象，直到另一个线程或 ISR 将所需的事件集发布到事件对象。
• 每次将事件发布到 events 对象时， events 对象会处理等待该事件对象的所有线程以确定是否存在匹配项。
• 等待条件与事件对象中的事件集匹配的所有线程都将被唤醒。

数据结构

k_event

struct k_event {_wait_q_t         wait_q;uint32_t          events;struct k_spinlock lock;SYS_PORT_TRACING_TRACKING_FIELD(k_event)
};

• 该结构体中包含2个主要成员：
  • wait_q 等待队列，当线程调用等待函数时，如果条件不满足，那么将会被添加到等待队列中。
  • events 事件的状态，已发生为1，未发生为0。
• spinlock 是为了多线程安全操作。

event_walk_data

struct event_walk_data {struct k_thread  *head;uint32_t events;
};

• 其中 events 为事件发布后事件对象中 events 成员变量的值，代表当前已经发生的事件。
• 当线程或者中断向事件对象发布事件时，因为等待事件被挂起的线程可能需要被唤醒，但是这些线程等待的事件并不相同，需要从等待队列 wait_q 中查找出满足唤醒条件的线程，并将这些线程作为节点添加到被唤醒链表中，head即为链表头。

static int event_walk_op(struct k_thread *thread, void *data)
{unsigned int      wait_condition;struct event_walk_data *event_data = data;wait_condition = thread->event_options & K_EVENT_WAIT_MASK;if (are_wait_conditions_met(thread->events, event_data->events,wait_condition)) {/ Events create a list of threads to wake up. We do* not want z_thread_timeout to wake these threads; they* will be woken up by k_event_post_internal once they* have been processed.*/thread->no_wake_on_timeout = true;/ The wait conditions have been satisfied. Add this* thread to the list of threads to unpend.*/thread->next_event_link = event_data->head;event_data->head = thread;z_abort_timeout(&thread->base.timeout);}return 0;
}

• 程序依次遍历wait_q 中的线程，如果发现其等待的条件已满足，调用 event_walk_op 从链表头部插入线程。
• 当遍历完成后依次取出单链表中的线程，将其唤醒。

events 初始化

Z_EVENT_INITIALIZER

• 静态初始化使用于为 k_event 全局对象设置初始值

#define Z_EVENT_INITIALIZER(obj) \\{ \\.wait_q = Z_WAIT_Q_INIT(&obj.wait_q), \\.events = 0 \\}

• 该宏会将等待队列初始化为空
• events 设置为0

void k_event_init(struct k_event *event)

• k_event_init 为运行时初始化函数，其具体的实现由z_impl_k_event_init 完成， 该函数功能与 Z_EVENT_INITIALIZER 一致。

void z_impl_k_event_init(struct k_event *event)
{event->events = 0;event->lock = (struct k_spinlock) {};SYS_PORT_TRACING_OBJ_INIT(k_event, event);z_waitq_init(&event->wait_q);z_object_init(event);
}

发布事件

void k_event_post(struct k_event *event, uint32_t events)

• k_event_post 用于向事件对象发布指定的事件集，其实现由 z_impl_k_event_post 完成。

void z_impl_k_event_post(struct k_event *event, uint32_t events)
{k_event_post_internal(event, events, events);
}static void k_event_post_internal(struct k_event *event, uint32_t events,uint32_t events_mask)
{k_spinlock_key_t  key;struct k_thread  *thread;struct event_walk_data data;data.head = NULL;key = k_spin_lock(&event->lock);SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_event, post, event, events,events_mask);events = (event->events & ~events_mask) |(events & events_mask);event->events = events;data.events = events;/* 发布一个事件可能会唤醒多个被挂起的线程，为了将被影响的线程同时解挂，* 需要完成以下步骤：*  1、遍历等待队列并创建一个单链表用于解除挂起*  2、将单链表中的线程依次解除挂起*  3、将单链表中的线程设置为就绪态*//* 将等待队列中满足条件的线程添加到单链表中 */z_sched_waitq_walk(&event->wait_q, event_walk_op, &data);/* 唤醒所有单链表中的线程 */if (data.head != NULL) {thread = data.head;struct k_thread *next;do {arch_thread_return_value_set(thread, 0);thread->events = events;next = thread->next_event_link;z_sched_wake_thread(thread, false);thread = next;} while (thread != NULL);}z_reschedule(&event->lock, key);SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, post, event, events,events_mask);
}

设置事件

void k_event_set(struct k_event *event, uint32_t events)

• k_event_set 和 k_event_post 的区别类似于C语言中 = 与 |= 之间的差别，k_event_set 会将事件对象中的事件赋值为 events，而 k_event_post 只会影响指定的位，未指定的位则保持不变。

void z_impl_k_event_set(struct k_event *event, uint32_t events)
{k_event_post_internal(event, events, ~0);
}

设置或清除事件

void k_event_set_masked(struct k_event *event, uint32_t events, uint32_t events_mask)

• k_event_set_masked 会将 events_mask 中指定的事件清除，并设置 events 中指定的事件。

void z_impl_k_event_set_masked(struct k_event *event, uint32_t events,uint32_t events_mask)
{k_event_post_internal(event, events, events_mask);
}

清除事件

k_event_clear(struct k_event *event, uint32_t events)

• k_event_clear 用于将 events 指定的事件清除

void z_impl_k_event_clear(struct k_event *event, uint32_t events)
{k_event_post_internal(event, 0, events);
}

等待事件

等待选项

• 在Zephyr中包含如下选项，用于设置等待方式

#define K_EVENT_WAIT_ANY      0x00   /* Wait for any events */
#define K_EVENT_WAIT_ALL      0x01   /* Wait for all events */
#define K_EVENT_WAIT_MASK     0x01
#define K_EVENT_WAIT_RESET    0x02   /* Reset events prior to waiting */

• 选项说明：
  • bit0 为 1，等待所有事件，bit0 为 0，等待其中任一事件
  • bit1 为 1，在调用 k_event_wait 时先清除所有事件，bit1 为 0，不清除。

uint32_t k_event_wait(struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)

• k_event_wait 中包含4个参数：
  • events 等待的事件
  • reset 是否在调用 k_event_wait 时先清除所有事件
  • timeout 超时时间
• k_event_wait 由 z_impl_k_event_wait 实现相应功能。

uint32_t z_impl_k_event_wait(struct k_event *event, uint32_t events,bool reset, k_timeout_t timeout)
{uint32_t options = reset ? K_EVENT_WAIT_RESET : 0;return k_event_wait_internal(event, events, options, timeout);
}

• 该函数中 options 的 bit0 为 0，代表任一事件发生即会返回
• options 的 bit1 由 reset 决定，当 reset 为 true 时会先将所有事件清除，再等待事件。

static uint32_t k_event_wait_internal(struct k_event *event, uint32_t events,unsigned int options, k_timeout_t timeout)
{uint32_t  rv = 0;unsigned int  wait_condition;struct k_thread  *thread;/* 在中断中调用 k_event_wait_internal 时不会进入等待 */__ASSERT(((arch_is_in_isr() == false) ||K_TIMEOUT_EQ(timeout, K_NO_WAIT)), "");SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_event, wait, event, events,options, timeout);/* 无等待事件，返回0 */if (events == 0) {SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, wait, event, events, 0);return 0;}wait_condition = options & K_EVENT_WAIT_MASK;thread = z_current_get();k_spinlock_key_t  key = k_spin_lock(&event->lock);/* K_EVENT_WAIT_RESET 选项开启后，首先会把事件对象中的events清0，* 在某些使用场景下，需要先清除之前的状态，确保不会因为之前过时状态而立即返回* 例如串口通讯中，发送一条指令并等待回应，通常会设置超时时间，* 如果在超时后接收到应答，通常会将对应的事件位设置为1，* 从而导致下一次运行时立即返回，得到错误的结果*/if (options & K_EVENT_WAIT_RESET) {event->events = 0;}/* 测试等待条件是否满足，满足返回等待结果，不满足则等待 */if (are_wait_conditions_met(events, event->events, wait_condition)) {rv = event->events;k_spin_unlock(&event->lock, key);goto out;}/* 等待事件未发生且等待时间为0，返回0 */if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {k_spin_unlock(&event->lock, key);goto out;}/* 调用线程在TCB中设置等待的事件和选项，并进入等待，* 等待线程或中断发布事件，将当前调用线程唤醒*/thread->events = events;thread->event_options = options;SYS_PORT_TRACING_OBJ_FUNC_BLOCKING(k_event, wait, event, events,options, timeout);if (z_pend_curr(&event->lock, key, &event->wait_q, timeout) == 0) {/* Retrieve the set of events that woke the thread */rv = thread->events;}out:SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, wait, event,events, rv & events);return rv & events;
}

uint32_t k_event_wait_all(struct k_event *event, uint32_t events, bool reset, k_timeout_t timeout)

• k_event_wait_all 是 k_event_wait 的另一版本，两者差别在于等待条件的不同，前者是等待所有事件，后者等待任一事件。

uint32_t z_impl_k_event_wait_all(struct k_event *event, uint32_t events,bool reset, k_timeout_t timeout)
{uint32_t options = reset ? (K_EVENT_WAIT_RESET | K_EVENT_WAIT_ALL): K_EVENT_WAIT_ALL;return k_event_wait_internal(event, events, options, timeout);
}