kernel: event api extensions to clear events and avoid phantom events

This is variation of the PR to handle phantom events and hopefully
this get merged into the PR to land.

See-also: #89624
Signed-off-by: Charles Hardin <ckhardin@gmail.com>

Author: ckhardin

doc/kernel/services/synchronization/events.rst

@@ -108,8 +108,8 @@ the event object.
         ...
     }
 
-Waiting for Events
-==================
+Waiting for Events (without removal)
+====================================
 
 Threads wait for events by calling :c:func:`k_event_wait`.
 
@@ -152,6 +152,58 @@ before continuing.
         ...
     }
 
+Waiting for Events (with removal)
+=================================
+
+Threads wait for events (with atomic removal upon receipt) by calling
+:c:func:`k_event_wait_safe`.
+
+The following code builds on the example above, and waits up to 50 milliseconds
+for any of the specified events to be posted.  A warning is issued if none
+of the events are posted in time.
+
+If events are received on time, then they will not be present in the event
+object until the next time that the events are set or posted.
+
+.. code-block:: c
+
+    void consumer_thread(void)
+    {
+        uint32_t  events;
+
+        events = k_event_wait_safe(&my_event, 0xFFF, false, K_MSEC(50));
+        if (events == 0) {
+            printk("No input devices are available!");
+        } else {
+            /* Access the desired input device(s) */
+            ...
+        }
+        ...
+    }
+
+Alternatively, the consumer thread may desire to wait for all the events
+(with atomic removal upon receipt) before continuing using
+:c:func:`k_event_wait_all_safe`.
+
+If all events are received on time, then they will not be present in the event
+object until the next time that the events are set or posted.
+
+.. code-block:: c
+
+    void consumer_thread(void)
+    {
+        uint32_t  events;
+
+        events = k_event_wait_all_safe(&my_event, 0x121, false, K_MSEC(50));
+        if (events == 0) {
+            printk("At least one input device is not available!");
+        } else {
+            /* Access the desired input devices */
+            ...
+        }
+        ...
+    }
+
 Suggested Uses
 **************
 

include/zephyr/kernel.h

@@ -2507,6 +2507,52 @@ __syscall uint32_t k_event_wait(struct k_event *event, uint32_t events,
 __syscall uint32_t k_event_wait_all(struct k_event *event, uint32_t events,
 				    bool reset, k_timeout_t timeout);
 
+/**
+ * @brief Wait for any of the specified events (safe version)
+ *
+ * This call is nearly identical to @ref k_event_wait with the main difference
+ * being that the safe version atomically clears received events from the
+ * event object. This mitigates the need for calling @ref k_event_clear, or
+ * passing a "reset" argument, since doing so may result in lost event
+ * information.
+ *
+ * @param event Address of the event object
+ * @param events Set of desired events on which to wait
+ * @param reset If true, clear the set of events tracked by the event object
+ *              before waiting. If false, do not clear the events.
+ * @param timeout Waiting period for the desired set of events or one of the
+ *                special values K_NO_WAIT and K_FOREVER.
+ *
+ * @retval set of matching events upon success
+ * @retval 0 if no matching event was received within the specified time
+ */
+__syscall uint32_t k_event_wait_safe(struct k_event *event, uint32_t events,
+				     bool reset, k_timeout_t timeout);
+
+/**
+ * @brief Wait for all of the specified events (safe version)
+ *
+ * This call is nearly identical to @ref k_event_wait_all with the main
+ * difference being that the safe version atomically clears received events
+ * from the event object. This mitigates the need for calling
+ * @ref k_event_clear, or passing a "reset" argument, since doing so may
+ * result in lost event information.
+ *
+ * @param event Address of the event object
+ * @param events Set of desired events on which to wait
+ * @param reset If true, clear the set of events tracked by the event object
+ *              before waiting. If false, do not clear the events.
+ * @param timeout Waiting period for the desired set of events or one of the
+ *                special values K_NO_WAIT and K_FOREVER.
+ *
+ * @retval set of matching events upon success
+ * @retval 0 if all matching events were not received within the specified time
+ */
+__syscall uint32_t k_event_wait_all_safe(struct k_event *event, uint32_t events,
+					 bool reset, k_timeout_t timeout);
+
+
+
 /**
  * @brief Test the events currently tracked in the event object
  *

include/zephyr/kernel/thread.h

@@ -279,7 +279,7 @@ struct k_thread {
 #if defined(CONFIG_EVENTS)
 	struct k_thread *next_event_link;
 
-	uint32_t   events;
+	uint32_t   events; /* dual purpose - wait on and then received */
 	uint32_t   event_options;
 
 	/** true if timeout should not wake the thread */

kernel/events.c

@@ -38,11 +38,13 @@
 #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 */
+#define K_EVENT_OPTION_RESET  0x02   /* Reset events prior to waiting */
+#define K_EVENT_OPTION_CLEAR  0x04   /* Clear events that are received */
 
 struct event_walk_data {
 	struct k_thread  *head;
 	uint32_t events;
+	uint32_t clear_events;
 };
 
 #ifdef CONFIG_OBJ_CORE_EVENT
@@ -77,54 +79,64 @@ void z_vrfy_k_event_init(struct k_event *event)
 #endif /* CONFIG_USERSPACE */
 
 /**
- * @brief determine if desired set of events been satisfied
+ * @brief determine the set of events that have been satisfied
  *
  * This routine determines if the current set of events satisfies the desired
  * set of events. If @a wait_condition is K_EVENT_WAIT_ALL, then at least
  * all the desired events must be present to satisfy the request. If @a
  * wait_condition is not K_EVENT_WAIT_ALL, it is assumed to be K_EVENT_WAIT_ANY.
  * In the K_EVENT_WAIT_ANY case, the request is satisfied when any of the
  * current set of events are present in the desired set of events.
+ *
+ * @return event bits that satisfy the wait condition or zero
  */
-static bool are_wait_conditions_met(uint32_t desired, uint32_t current,
-				    unsigned int wait_condition)
+static uint32_t are_wait_conditions_met(uint32_t desired, uint32_t current,
+					unsigned int wait_condition)
 {
-	uint32_t  match = current & desired;
+	uint32_t match = current & desired;
 
-	if (wait_condition == K_EVENT_WAIT_ALL) {
-		return match == desired;
+	if ((wait_condition == K_EVENT_WAIT_ALL) && (match != desired)) {
+		/* special case for K_EVENT_WAIT_ALL */
+		return 0;
 	}
 
-	/* wait_condition assumed to be K_EVENT_WAIT_ANY */
-
-	return match != 0;
+	/* return the matched events for any wait condition */
+	return match;
 }
 
 static int event_walk_op(struct k_thread *thread, void *data)
 {
-	unsigned int      wait_condition;
+	uint32_t match;
+	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)) {
-
+	match = are_wait_conditions_met(thread->events, event_data->events,
+					wait_condition);
+	if (match != 0) {
 		/*
 		 * 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;
+		z_abort_timeout(&thread->base.timeout);
 
 		/*
-		 * The wait conditions have been satisfied. Add this
-		 * thread to the list of threads to unpend.
+		 * The wait conditions have been satisfied. So, set the
+		 * received events and then add this thread to the list
+		 * of threads to unpend.
+		 *
+		 * NOTE: thread event options can consume an event
 		 */
+		thread->events = match;
+		if (thread->event_options & K_EVENT_OPTION_CLEAR) {
+			event_data->clear_events |= match;
+		}
 		thread->next_event_link = event_data->head;
 		event_data->head = thread;
-		z_abort_timeout(&thread->base.timeout);
 	}
 
 	return 0;
@@ -147,8 +159,7 @@ static uint32_t k_event_post_internal(struct k_event *event, uint32_t events,
 	previous_events = event->events & events_mask;
 	events = (event->events & ~events_mask) |
 		 (events & events_mask);
-	event->events = events;
-	data.events = events;
+
 	/*
 	 * Posting an event has the potential to wake multiple pended threads.
 	 * It is desirable to unpend all affected threads simultaneously. This
@@ -159,20 +170,24 @@ static uint32_t k_event_post_internal(struct k_event *event, uint32_t events,
 	 * 3. Ready each of the threads in the linked list
 	 */
 
+	data.events = events;
+	data.clear_events = 0;
 	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);
 	}
 
+	/* stash any events not consumed */
+	event->events = data.events & ~data.clear_events;
+
 	z_reschedule(&event->lock, key);
 
 	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, post, event, events,
@@ -262,21 +277,22 @@ static uint32_t k_event_wait_internal(struct k_event *event, uint32_t events,
 
 	k_spinlock_key_t  key = k_spin_lock(&event->lock);
 
-	if (options & K_EVENT_WAIT_RESET) {
+	if (options & K_EVENT_OPTION_RESET) {
 		event->events = 0;
 	}
 
 	/* Test if the wait conditions have already been met. */
-
-	if (are_wait_conditions_met(events, event->events, wait_condition)) {
-		rv = event->events;
+	rv = are_wait_conditions_met(events, event->events, wait_condition);
+	if (rv != 0) {
+		/* clear the events that are matched */
+		if (options & K_EVENT_OPTION_CLEAR) {
+			event->events &= ~rv;
+		}
 
 		k_spin_unlock(&event->lock, key);
 		goto out;
 	}
 
-	/* Match conditions have not been met. */
-
 	if (K_TIMEOUT_EQ(timeout, K_NO_WAIT)) {
 		k_spin_unlock(&event->lock, key);
 		goto out;
@@ -299,10 +315,9 @@ static uint32_t k_event_wait_internal(struct k_event *event, uint32_t events,
 	}
 
 out:
-	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, wait, event,
-				       events, rv & events);
+	SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_event, wait, event, events, rv);
 
-	return rv & events;
+	return rv;
 }
 
 /**
@@ -311,7 +326,7 @@ static uint32_t k_event_wait_internal(struct k_event *event, uint32_t events,
 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;
+	uint32_t options = reset ? K_EVENT_OPTION_RESET : 0;
 
 	return k_event_wait_internal(event, events, options, timeout);
 }
@@ -331,7 +346,7 @@ uint32_t z_vrfy_k_event_wait(struct k_event *event, uint32_t events,
 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)
+	uint32_t options = reset ? (K_EVENT_OPTION_RESET | K_EVENT_WAIT_ALL)
 				 : K_EVENT_WAIT_ALL;
 
 	return k_event_wait_internal(event, events, options, timeout);
@@ -347,6 +362,45 @@ uint32_t z_vrfy_k_event_wait_all(struct k_event *event, uint32_t events,
 #include <zephyr/syscalls/k_event_wait_all_mrsh.c>
 #endif /* CONFIG_USERSPACE */
 
+uint32_t z_impl_k_event_wait_safe(struct k_event *event, uint32_t events,
+				  bool reset, k_timeout_t timeout)
+{
+	uint32_t options = reset ? (K_EVENT_OPTION_CLEAR | K_EVENT_OPTION_RESET)
+				 : K_EVENT_OPTION_CLEAR;
+
+	return k_event_wait_internal(event, events, options, timeout);
+}
+
+#ifdef CONFIG_USERSPACE
+uint32_t z_vrfy_k_event_wait_safe(struct k_event *event, uint32_t events,
+				  bool reset, k_timeout_t timeout)
+{
+	K_OOPS(K_SYSCALL_OBJ(event, K_OBJ_EVENT));
+	return z_impl_k_event_wait_safe(event, events, reset, timeout);
+}
+#include <zephyr/syscalls/k_event_wait_safe_mrsh.c>
+#endif /* CONFIG_USERSPACE */
+
+uint32_t z_impl_k_event_wait_all_safe(struct k_event *event, uint32_t events,
+				      bool reset, k_timeout_t timeout)
+{
+	uint32_t options = reset ? (K_EVENT_OPTION_CLEAR |
+				    K_EVENT_OPTION_RESET | K_EVENT_WAIT_ALL)
+				 : (K_EVENT_OPTION_CLEAR | K_EVENT_WAIT_ALL);
+
+	return k_event_wait_internal(event, events, options, timeout);
+}
+
+#ifdef CONFIG_USERSPACE
+uint32_t z_vrfy_k_event_wait_all_safe(struct k_event *event, uint32_t events,
+				      bool reset, k_timeout_t timeout)
+{
+	K_OOPS(K_SYSCALL_OBJ(event, K_OBJ_EVENT));
+	return z_impl_k_event_wait_all_safe(event, events, reset, timeout);
+}
+#include <zephyr/syscalls/k_event_wait_all_safe_mrsh.c>
+#endif /* CONFIG_USERSPACE */
+
 #ifdef CONFIG_OBJ_CORE_EVENT
 static int init_event_obj_core_list(void)
 {