feat!: notification-backed k_event (full 32 bits, upstream semantics)

[swoisz]

Summary

Part of #40 — the second (and per the design verdict, final planned) primitive converted to the own-the-synchronization-state architecture proven by the k_sem conversion (#41): events word + waiter list in the caller-owned struct under a portMUX, blocking on the shared reserved notification index (now Z_KERNEL_NOTIFY_INDEX in zkernel_internal.h), stack-resident waiter nodes severed under the lock before any return. A post wakes all waiters whose conditions become met — satisfied nodes are unlinked into a local chain in one lock pass and notified after unlock.

This retires the FreeRTOS event-group backend, and with it a hard ceiling plus three parity gaps:

Gap	Old (event group)	New (upstream parity)
Usable events	24 bits (EventBits_t reserves the top byte)	full 32 bits
k_event_set	merged (aliased post)	replaces the tracked set
reset=true	cleared matched bits after the wait	zeroes the entire set before waiting
wait_all timeout	could return a truthy partial match	returns 0

New upstream surface: k_event_set_masked, k_event_test, k_event_wait_safe / k_event_wait_all_safe (atomically consume matched bits), previous-value returns from all mutators, compile-time K_EVENT_DEFINE, void k_event_init.

⚠️ BREAKING: k_event_set merge→replace (use k_event_post to accumulate); reset=true semantics as above; k_event_init returns void. In-tree tests updated intentionally (the MT multi-setter now uses post; the consume-on-wake test uses wait_safe). Same config requirement as #41 (sdkconfig.boreas — no new requirements).

Review-caught bug (fixed + regression-tested)

The first implementation cleared _safe waiters' matched bits mid-walk, starving overlapping waiters that upstream wakes (upstream accumulates clear_events and applies them after its wait-queue walk). Fixed to accumulate-then-apply, with an MT regression test where a _safe waiter enqueued first and a plain waiter must both wake from one post.

Tests (190 → 197 linux / 221 S3)

Set-replaces vs post-merges, previous-value returns, set_masked, wait_safe consumption, wait_all timeout-zero, bits 24/31 round-trip (the ceiling lift), K_EVENT_DEFINE static init, blocking wait_safe from a thread, and the wake-all-with-safe-waiter regression.

Validation

Target	Result
linux (host)	197 Tests 0 Failures ×3 consecutive runs
esp32s3 (on hardware)	221 Tests 0 Failures

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR replaces the FreeRTOS EventGroup-backed k_event implementation with a notification-backed design that owns the event state (32-bit word + waiter list) in the caller’s struct k_event, aligning Boreas behavior with upstream Zephyr semantics and removing the old 24-bit ceiling.

Changes:

• Reimplements k_event on top of a caller-owned event word + waiter list guarded by a portMUX lock, using the reserved task-notification index (Z_KERNEL_NOTIFY_INDEX) for blocking/wakeup.
• Updates/expands the public API and semantics (set replaces vs post merges, reset clears before waiting, _safe wait variants that atomically consume matched bits, wait_all timeout returns 0, mutators return previous values).
• Updates unit and MT tests plus README/kernel.h docs to reflect new semantics and adds regression coverage.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
components/zkernel/src/k_event.c	New notification-backed k_event implementation (state owned by struct k_event, waiter list + wake-all semantics).
components/zkernel/include/boreas/zephyr/kernel.h	Updates struct k_event, K_EVENT_DEFINE, and public API declarations/docs (new _safe waits, set_masked, test, k_event_init signature).
components/zkernel/src/zkernel_internal.h	Centralizes the reserved notification index and enforces configTASK_NOTIFICATION_ARRAY_ENTRIES >= 2.
components/zkernel/src/k_sem.c	Switches to the shared Z_KERNEL_NOTIFY_INDEX (removes per-file index define).
test/main/test_k_event.c	Updates/adds single-thread tests for new semantics (replace vs merge, masked set, previous-value returns, _safe consumption, 32-bit coverage, static define).
test/main/test_k_event_mt.c	Updates MT behavior to use post, adds blocking _safe test and a wake-all regression test.
components/zkernel/README.md	Documents the notification-backed behavior and upstream semantics deltas.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.