KRN-NOTIF requirements

Requirement: Per-thread bits, ISR-settable KRN-NOTIF-001

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Owner-only wait KRN-NOTIF-002

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: O(1), allocation free KRN-NOTIF-003

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Binding on every waitable object KRN-NOTIF-004

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Direct waiters unaffected KRN-NOTIF-005

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Bit budget KRN-NOTIF-006

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Kernel bits KRN-NOTIF-007

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Level semantics and hand-off KRN-NOTIF-008

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Binding lifecycle KRN-NOTIF-009

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.

Requirement: Rights in isolated profiles KRN-NOTIF-010

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md links outgoing: KRN-CAP-002

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 Normative source.

Requirement: Trace KRN-NOTIF-011

status: Accepted evidence: not evaluated design_source: requirements/KRN-NOTIF.md links outgoing: OBS-005

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 Normative source.

Requirement: Binding mask and initial readiness KRN-NOTIF-012

status: Proposed evidence: not evaluated design_source: requirements/KRN-NOTIF.md

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 Normative source.