From f0540a90007a8b3e466fa76ca3658e8a6875146f Mon Sep 17 00:00:00 2001
From: Marian Buschsieweke <marian.buschsieweke@ml-pa.com>
Date: Mon, 8 Dec 2025 15:47:59 +0100
Subject: [PATCH] sys/event: manage event thread size via build system

This adds a mechanism for modules to declare requirements on the thread
stack size in their `Makefile.dep` and let the build system then
override the default stack size, if any requirements are declared.

The motivation is to allow multiple modules to have special requirements
without causing conflicts, as just adding the following to their
`Makefile.include` would do:

```Makefile
CFLAGS += -DEVENT_THREAD_MEDIUM_STACKSIZE=<MAGIC_NUMBER>
```

Instead, the new mechanism would work by having them both declare in
their `Makefile.dep`:

```Makefile
EVENT_THREAD_MEDIUM_STACKSIZE_MIN +=
```

The build system then picks the maximum number in
`EVENT_THREAD_MEDIUM_STACKSIZE_MIN` and exposes this as stack size, if
any module did declare a minimum requirement.

Co-authored-by: benpicco <benpicco@googlemail.com>
---
 sys/Makefile.include       |  4 ++++
 sys/event/Makefile.include | 35 +++++++++++++++++++++++++++++++++++
 sys/include/event/thread.h | 26 ++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 sys/event/Makefile.include

diff --git a/sys/Makefile.include b/sys/Makefile.include
index 280e0851db..80d51b4f12 100644
--- a/sys/Makefile.include
+++ b/sys/Makefile.include
@@ -212,3 +212,7 @@ endif
 ifneq (,$(filter unicoap,$(USEMODULE)))
   include $(RIOTBASE)/sys/net/application_layer/unicoap/Makefile.include
 endif
+
+ifneq (,$(filter event,$(USEMODULE)))
+  include $(RIOTBASE)/sys/event/Makefile.include
+endif
diff --git a/sys/event/Makefile.include b/sys/event/Makefile.include
new file mode 100644
index 0000000000..c986438e5a
--- /dev/null
+++ b/sys/event/Makefile.include
@@ -0,0 +1,35 @@
+include $(RIOTMAKE)/utils/strings.mk
+
+# This applies to all thread stacks
+ifneq (, $(EVENT_THREAD_STACKSIZE_MIN))
+  EVENT_THREAD_STACKSIZE_MIN := $(call max_number,$(EVENT_THREAD_STACKSIZE_MIN))
+endif
+
+ifeq (,$(filter event_thread_highest, $(USEMODULE)))
+  # No highest priority event thread, so the highest prio queue is handled by
+  # the same thread handling the medium priority queue. So we "trickle down"
+  # the requirements here
+  EVENT_THREAD_MEDIUM_STACKSIZE_MIN += $(EVENT_THREAD_HIGHEST_STACKSIZE_MIN)
+else
+  ifneq (, $(EVENT_THREAD_HIGHEST_STACKSIZE_MIN))
+    EVENT_THREAD_HIGHEST_STACKSIZE_MIN := $(call max_number,$(EVENT_THREAD_HIGHEST_STACKSIZE_MIN) $(EVENT_THREAD_STACKSIZE_MIN))
+    CFLAGS += -DEVENT_THREAD_HIGHEST_STACKSIZE=$(EVENT_THREAD_HIGHEST_STACKSIZE_MIN)
+  endif
+endif
+
+ifeq (,$(filter event_thread_medium, $(USEMODULE)))
+  # No medium priority event thread, so the medium prio queue is handled by
+  # the same thread handling the lowest priority queue. So we "trickle down"
+  # the requirements here
+  EVENT_THREAD_LOWEST_STACKSIZE_MIN += $(EVENT_THREAD_MEDIUM_STACKSIZE_MIN)
+else
+  ifneq (, $(EVENT_THREAD_MEDIUM_STACKSIZE_MIN))
+    EVENT_THREAD_MEDIUM_STACKSIZE_MIN := $(call max_number,$(EVENT_THREAD_MEDIUM_STACKSIZE_MIN) $(EVENT_THREAD_STACKSIZE_MIN))
+    CFLAGS += -DEVENT_THREAD_MEDIUM_STACKSIZE=$(EVENT_THREAD_MEDIUM_STACKSIZE_MIN)
+  endif
+endif
+
+ifneq (, $(EVENT_THREAD_LOWEST_STACKSIZE_MIN))
+  EVENT_THREAD_LOWEST_STACKSIZE_MIN := $(call max_number,$(EVENT_THREAD_LOWEST_STACKSIZE_MIN) $(EVENT_THREAD_STACKSIZE_MIN))
+  CFLAGS += -DEVENT_THREAD_LOWEST_STACKSIZE=$(EVENT_THREAD_LOWEST_STACKSIZE_MIN)
+endif
diff --git a/sys/include/event/thread.h b/sys/include/event/thread.h
index 1e277bee40..f76c0852aa 100644
--- a/sys/include/event/thread.h
+++ b/sys/include/event/thread.h
@@ -44,6 +44,32 @@
  * event queue gets its own thread. So higher priority events will always
  * preempt events of lower priority in this case.
  *
+ * Managing Stack Size Requirements
+ * --------------------------------
+ *
+ * A module using the medium priority event queue might require a certain
+ * minimum stack size, say 1024, to operate correctly. Instead of just adding
+ * `CFLAGS += -DDEVENT_THREAD_MEDIUM_STACKSIZE=1024`, it can instead add the
+ * following to its `Makefile.dep`:
+ *
+ * ```Makefile
+ * EVENT_THREAD_MEDIUM_STACKSIZE_MIN += 1024
+ * ```
+ *
+ * In the `Makefile.include` of `sys/event` the highest value of the minimum
+ * requirements declared by any module will be picked and added to the
+ * `CFLAGS`.
+ *
+ * @note    `EVENT_THREAD_MEDIUM_STACKSIZE_MIN` and
+ *          `EVENT_THREAD_HIGHEST_STACKSIZE_MIN` always apply to the thread
+ *          managing the medium priority queue.
+ * @details  E.g. without the module `event_thread_medium` the lowest priority
+ *          and medium priority queues are both handled by the lowest priority
+ *          even thread. In that case, `EVENT_THREAD_MEDIUM_STACKSIZE_MIN` would
+ *          ensure a minimum thread statck size on the lowest priority even
+ *          thread. With `event_thread_medium` in use, it would instead apply
+ *          to the stack of the dedicated medium event queue thread.
+ *
  * @{
  *
  * @file