KRN-NOTIF - Notifications and Notification Binding¶

Documentation revision: 2026-10-14 (ADR-039; M1 amendment log). Existing status dates record original design acceptance, not validation of the revised wording. New implementation obligations remain Proposed until implemented and verified.

Group KRN-NOTIF. Design: docs/specs/SPEC-006-notifications-and-work-queues.md §2, §3. Related groups: KRN-WAIT (a notification wait is a wait with reason NOTIFY), KRN-SYNC (semaphores and events as bound objects), KRN-IPC (queues and pipes as bound objects), KRN-WQ (work queues run on a kernel bit), KRN-CAP (the NOTIFY and BIND rights).

KRN-NOTIF-001 to 006 originate in docs/architecture/03-kernel-architecture.md §6.1 (004 to 006 added by ADR-027). All are restated here as the authoritative copy. New requirements start at 007.

Requirements¶

KRN-NOTIF-001 Per-thread bits, ISR-settable¶

Statement. Each thread shall own a notification bit set that can be set from ISR context without blocking. Rationale. The cheapest completion path from an interrupt to a thread (R-001 §6). Status. Accepted 2026-10-07 Verification. Test: notif/set_from_isr; Analysis: emb_notify_set is @ctx thread isr. Trace. SPEC-006 §2; 03 §6.1

KRN-NOTIF-002 Owner-only wait¶

Statement. Only the owning thread shall wait on its notifications. Rationale. One possible waiter makes the structure a single slot and every operation O(1). Status. Accepted 2026-10-07 Verification. Analysis: emb_notify_wait has no thread argument. Trace. SPEC-006 §2.2

KRN-NOTIF-003 O(1), allocation free¶

Statement. Notification set and wait shall be O(1) and allocation free. Rationale. It is the primitive everything else is built on. Status. Accepted 2026-10-07 Verification. Benchmark: harness operation T8 (R-003 §4); Analysis: no list and no allocation in the path. Trace. SPEC-006 §2.2; R-003 §4 T8

KRN-NOTIF-004 Binding on every waitable object¶

Statement. Every waitable kernel object shall support binding to one notification bit of one thread; the set shall be O(1) and shall happen on every transition to the ready condition. Rationale. Multi-object wait without poll objects (ADR-027). Status. Accepted 2026-10-07 Verification. Test: notif/bind_<object> for every object type; model scenario binding_hook. Trace. SPEC-006 §3; ADR-027

KRN-NOTIF-005 Direct waiters unaffected¶

Statement. Binding shall not change the object’s own wait-queue semantics for threads blocked directly on it. Rationale. A binding is an observer of transitions, not a waiter. Status. Accepted 2026-10-07 Verification. Test: notif/bind_with_direct_waiter (the direct waiter is served, no bit is set). Trace. SPEC-006 §3.2; SPEC-004 §6.3

KRN-NOTIF-006 Bit budget¶

Statement. The base profile shall reserve at least 16 notification bits for application use after the kernel-reserved bits; the tiny profile may select 8 bits with at least 4 reserved for the application. Rationale. Bindings need spare bits (answers 08 Q7). Status. Accepted 2026-10-07 Verification. Analysis: EMB_NOTIFY_APP_BITS is 24, 12, or 4 for 32, 16, 8-bit words. Trace. SPEC-006 §1, §2.1

KRN-NOTIF-007 Kernel bits¶

Statement. The high EMB_NOTIFY_KERNEL_BITS of the word are reserved for the kernel (K_WORK, K_FAULT, K_BUDGET, rest reserved); application code shall not be able to set them (EMB_EINVAL), and they shall not be settable across a partition boundary. Rationale. Work queues, supervisor fault delivery, and budget notices need bits the application cannot forge. Status. Accepted 2026-10-07 Verification. Test: misuse/notify_kernel_bit; isolated profile test part/notify_kernel_bit_cross_partition. Trace. SPEC-006 §2.1, §2.2

KRN-NOTIF-008 Level semantics and hand-off¶

Statement. Bits set while nobody waits shall persist until consumed; a set that satisfies the waiting owner shall hand over the satisfied bits, apply the waiter’s CLEAR to those bits, and wake it in the same step; a bound object’s transition shall produce no lost wakeup and at most one spurious pass of the bound thread. Rationale. The edge-plus-re-check contract the multi-source pattern relies on (SPEC-006 §3.2, §3.3). Status. Accepted 2026-10-07 Verification. Test: notif/level_then_wait, notif/all_across_two_sets, notif/bound_multi_source; model scenarios notify_set_in_window, notify_level, notify_all_two_sets, bound_two_sems. Trace. SPEC-006 §2.2, §3.2

KRN-NOTIF-009 Binding lifecycle¶

Statement. bind on an already bound object shall return EMB_EEXIST; unbind shall remove the binding; destroying the object shall not touch the thread’s bits; a set to a terminated or restarted thread shall be dropped (detected by generation where generations are checked). Rationale. Deterministic ownership of the single binding slot; no dangling-pointer action. Status. Accepted 2026-10-07 Verification. Test: notif/bind_twice, notif/unbind_rebind, notif/bind_target_restarted (isolated profile). Trace. SPEC-006 §3.1, §3.2

KRN-NOTIF-010 Rights in isolated profiles¶

Statement. In isolated profiles, setting another partition’s thread notification shall require a thread capability with the NOTIFY right, and binding an object shall require the object’s BIND right and the thread’s NOTIFY right. Rationale. A notification is a cross-partition signal; capabilities govern it like every other cross-partition action. Status. Accepted 2026-10-07 Verification. Test: part/notify_without_right returns EMB_EPERM. Trace. SPEC-006 §2.2, §3.1; KRN-CAP-002

KRN-NOTIF-011 Trace¶

Statement. Notification set (with whether it woke the owner), wait begin and result, and binding signals shall be trace events compiled out when tracing is disabled. Rationale. “Who set my bit” is the first debugging question of event-driven code. Status. Accepted 2026-10-07 Verification. Test: trace decoder reconstructs every set of the conformance run. Trace. SPEC-006 §7; OBS-005

KRN-NOTIF-012 Binding mask and initial readiness¶

Statement. Public binding operations shall take one nonzero application-bit mask, reject zero, multiple bits, and kernel bits, and preserve the object’s existing readiness. A caller shall bind before producers start or check and drain existing readiness before its first notification wait; edge-driven consumers shall drain their selected sources before waiting again. Rationale. Matches the M1 semaphore API and prevents confusing a bit index with a mask or waiting for an edge that already occurred. Status. Proposed 2026-10-14; mask validation is implemented for semaphore binding, broader lifecycle validation is pending. Verification. Existing tests/conformance/test_sem.c binding cases; planned initial-ready, multi-item drain, and invalid-mask cases mapped individually in the traceability matrix. Trace. SPEC-006 §3; A18; A23