# KRN-NOTIF requirements ::::{req} Per-thread bits, ISR-settable :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Owner-only wait :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} O(1), allocation free :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Binding on every waitable object :id: 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_` for every object type; model scenario `binding_hook`. **Trace:** SPEC-006 §3; ADR-027 [Normative source](../../requirements/KRN-NOTIF.md). :::: ::::{req} Direct waiters unaffected :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Bit budget :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Kernel bits :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Level semantics and hand-off :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Binding lifecycle :id: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Rights in isolated profiles :id: KRN-NOTIF-010 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-NOTIF.md :links: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Trace :id: KRN-NOTIF-011 :status: Accepted :evidence: not evaluated :design_source: requirements/KRN-NOTIF.md :links: 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](../../requirements/KRN-NOTIF.md). :::: ::::{req} Binding mask and initial readiness :id: 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](../../requirements/KRN-NOTIF.md). ::::