KRN-WQ requirements

Requirement: Intrusive, static, ISR-safe submit KRN-WQ-001

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

Work items shall be intrusive and statically allocatable; submission shall be ISR-safe and O(1). Rationale: A bottom half is submitted from interrupts; it must cost one push and one bit set. Status: Accepted 2026-10-07 Verification: Test: wq/submit_from_isr; Analysis: no allocation and no list walk in emb_work_submit. Trace: SPEC-006 §4.3 Normative source.

Requirement: FIFO per queue in thread context KRN-WQ-002

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

Work executes in FIFO order per queue in thread context. Rationale: Deterministic order; handlers may use thread-only API. Status: Accepted 2026-10-07 Verification: Test: wq/fifo_order, wq/handler_may_block. Trace: SPEC-006 §4.3 Normative source.

Requirement: Delayed work over software timers KRN-WQ-003

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

Delayed work shall be implemented over software timers, not a separate timing mechanism. Rationale: One timeout structure (ADR-010); one set of accuracy rules. Status: Accepted 2026-10-07 Verification: Analysis: emb_dwork_t embeds emb_timer_storage_t; no other timing code in kernel/work/. Trace: SPEC-006 §4.1, §4.3; SPEC-003 §7 Normative source.

Requirement: Cancellation reports the state KRN-WQ-004

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

Cancellation shall report whether the item was pending, running, or idle. Rationale: The caller must know whether a handler may still run. Status: Accepted 2026-10-07 Verification: Test: wq/cancel_pending, wq/cancel_running, wq/cancel_idle. Trace: SPEC-006 §4.3 Normative source.

Requirement: Submit outcomes KRN-WQ-005

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

Submitting a queued item shall return EMB_EEXIST and change nothing; submitting an item running on the same queue shall return EMB_OK and re-append it after its handler returns; submitting an item running on another queue shall return EMB_EBUSY; an item shall never run concurrently with itself. Rationale: Idempotent submission without lost re-submissions and without handler re-entrancy (Zephyr’s v2 rule, R-001 §6). Status: Accepted 2026-10-07 Verification: Test: wq/submit_queued_eexist, wq/resubmit_while_running_runs_again, wq/submit_other_queue_ebusy. Trace: SPEC-006 §4.3, §12.5 Normative source.

Requirement: Synchronous cancel and flush KRN-WQ-006

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

cancel_sync shall wait until a running handler has returned; flush shall return when every item queued before the call has run; calling either from the queue’s own thread shall be misuse. Rationale: Teardown needs a point after which no handler touches the caller’s state. Status: Accepted 2026-10-07 Verification: Test: wq/cancel_sync_waits, wq/flush, misuse/wq_flush_from_handler. Trace: SPEC-006 §4.3, §6 Normative source.

Requirement: Delayed work scheduling KRN-WQ-007

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

dwork_schedule on a pending item shall return EMB_EEXIST and change nothing; reschedule shall replace a pending delay; cancel shall stop an armed timer or remove a queued item and report PENDING for both; the timer’s expiry shall submit the item in O(1) from the expiry path. Rationale: One queue hop per delayed item; deterministic re-arm semantics. Status: Accepted 2026-10-07 Verification: Test: wq/dwork_schedule_pending, wq/dwork_reschedule, wq/dwork_cancel_states. Trace: SPEC-006 §4.3, §12.6, §12.7 Normative source.

Requirement: System work queue KRN-WQ-008

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

With CONFIG_EMB_SYSTEM_WORKQ the system work queue shall exist from kernel start at CONFIG_EMB_SYSTEM_WORKQ_PRIO with CONFIG_EMB_SYSTEM_WORKQ_STACK; it shall be the default queue of software timers; the tiny profile shall default to no system queue. Rationale: Timer callbacks need a thread; the tiny profile cannot afford one by default. Status: Accepted 2026-10-07 Verification: Test: wq/system_queue_exists; footprint test of the tiny profile without it. Trace: SPEC-006 §4.3, §8; SPEC-003 §7.3; ADR-019 Normative source.

Requirement: Work queue thread KRN-WQ-009

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

A work queue’s thread shall wait on the K_WORK notification bit, drain the FIFO one item at a time with the item marked RUNNING outside the critical section, and run handlers at the queue’s priority. Rationale: Fixes the implementation shape so that latency is the thread’s dispatch latency plus the handlers ahead. Status: Accepted 2026-10-07 Verification: Analysis: kernel/work/ review; Test: wq/latency_measured with the trace events. Trace: SPEC-006 §4.1, §4.3, §4.4 Normative source.

Requirement: Lifecycle misuse KRN-WQ-010

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

Destroying a queue with queued or running items, flushing or synchronously cancelling from the queue’s own thread, and returning from a handler while owning a mutex shall be misuse per SPEC-001 §5.3. Rationale: Each would leave work or locks in an undefined owner. Status: Accepted 2026-10-07 Verification: Test: misuse/wq_* in checked and release configurations (TEST-010). Trace: SPEC-006 §6 Normative source.

Requirement: Trace and statistics KRN-WQ-011

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

Submit, start with submit-to-start latency, end with duration, cancel, and delayed scheduling shall be trace events; maximum FIFO length, worst latency, and longest handler with its address shall be optional statistics per queue. Rationale: Work queue latency is the latency of every timer callback and bottom half. Status: Accepted 2026-10-07 Verification: Test: trace decoder; statistics API test. Trace: SPEC-006 §7; OBS-005 Normative source.