KRN-TIM requirements¶
Kernel time used for scheduling and timeouts shall be monotonic. Rationale: A clock that moves backward makes deadlines meaningless. Status: Accepted (v0.1) Verification: Test: Trace: v0.1 §7.5; SPEC-003 §3 |
Timeout correctness shall not depend on wall-clock time. Rationale: Calendar time is adjusted, stepped, and synchronized; deadlines must not move with it. Status: Accepted (v0.1) Verification: Test: pending timeouts are unaffected by Trace: v0.1 §7.5; SPEC-003 §2, §10 |
Finite timeout handling shall remain correct across underlying counter wraparound. Rationale: 24-bit, 32-bit, and 16-bit hardware counters wrap within seconds to days. Status: Accepted (v0.1) Verification: Test: Trace: v0.1 §7.5; SPEC-003 §5.2 |
The kernel shall permit tickless operation. Rationale: Power and deadline precision (ADR-017, 04 §4). Status: Accepted (v0.1) Verification: Test: the conformance suite passes in tickless mode on native and on a Cortex-M emulated target. Trace: v0.1 §7.5; SPEC-003 §4.2 |
One-shot and periodic software timers shall have defined callback-context semantics. Rationale: Callback context confusion is a leading cause of RTOS bugs. Status: Accepted (v0.1) Verification: Test: callback context observed with Trace: v0.1 §7.5; SPEC-003 §7.3 |
Timer operations on real-time paths shall have bounded behavior for a defined configuration. Rationale: Timer start and stop are called from ISRs and critical paths. Status: Accepted (v0.1) Verification: Analysis: Trace: v0.1 §7.5; SPEC-003 §5.1, §7.2 |
Time conversion and tick-rate behavior shall be explicitly documented to avoid silent truncation or overflow. Rationale: Unit bugs are silent until a field failure. Status: Accepted (v0.1) Verification: Inspection: SPEC-001 §7.3 and each port’s time section; Test: conversion vectors (API-023). Trace: v0.1 §7.5; SPEC-001 §7.3; SPEC-003 §11 |
Kernel monotonic time shall be a 64-bit tick count in the base and larger profiles; the tiny profile may select a 32-bit count with wrap-safe comparison. Rationale: 64 bits remove wrap handling where the core can afford it; 32 bits keep the ATmega328P affordable (ADR-017). Status: Accepted (03 §4.1) Verification: Test: both profiles in the time test matrix. Trace: 03 §4.1; SPEC-003 §3 |
The tick unit shall be the configuration constant Rationale: The API unit must not change with the clock mode, or application code is not portable between them. Status: Accepted (03 §4.1, refined 2026-10-07) Verification: Test: identical conversion results in periodic and tickless modes. Trace: 03 §4.1; SPEC-003 §3, §4.2 |
Public time types shall be distinct: Rationale: See API-022. Status: Accepted (03 §4.1) Verification: Test: negative compile tests (API-022). Trace: 03 §4.1; SPEC-001 §7.1 |
Absolute-deadline variants shall exist for sleep and for every blocking operation, so that periodic work does not accumulate drift. Rationale: See API-002. Status: Accepted (03 §4.1) Verification: Analysis: API-002 check; Test: a periodic loop with Trace: 03 §4.1; SPEC-003 §6 |
A high-resolution cycle counter API shall exist for measurement where hardware provides one; it shall not be the scheduling clock. Rationale: Cycle counters wrap fast and may stop in sleep; they measure, they do not schedule. Status: Accepted (03 §4.1) Verification: Analysis: no kernel timeout path reads Trace: 03 §4.1; SPEC-003 §9 |
Software timer callbacks shall execute by default on a work queue in thread context. Rationale: Interrupt-context callbacks are dangerous for general code (ADR-019). Status: Accepted (03 §4.3) Verification: Test: default timer callback observes Trace: 03 §4.3; SPEC-003 §7.3 |
A timer may be created with Rationale: A few callbacks need interrupt-level latency; the rest must not pay for it or risk it. Status: Accepted (03 §4.3) Verification: Test: a blocking call from an Trace: 03 §4.3; SPEC-003 §7.3 |
One-shot and periodic timers shall be supported; a periodic timer’s next expiry shall be computed from the previous expiry, not from callback completion. Rationale: Re-arming from completion accumulates callback latency into the period. Status: Accepted (03 §4.3) Verification: Test: a periodic timer’s expiry instants are exact multiples of the period from the first expiry over 10 000 periods on native. Trace: 03 §4.3; SPEC-003 §7.4 |
64-bit time values shall be read and written under a critical section or a sequence lock; the kernel shall not depend on 64-bit atomic loads, stores, or read-modify-write operations. Rationale: 32-bit targets do not provide them under EmbCC (09 §6). Status: Accepted (03 §4.1) Verification: Analysis: no Trace: 03 §4.1; SPEC-003 §3.1 |
The kernel shall support a periodic-tick mode and a tickless mode selected at configuration time. Every time, timeout, sleep, and timer requirement shall hold identically in both modes, and the conformance suite shall run in both. Rationale: A mode that changes behavior is a fork in disguise. Status: Accepted 2026-10-07 Verification: Test: conformance suite in both modes on native and on an emulated Cortex-M. Trace: SPEC-003 §4 |
In tickless mode the kernel shall program the timer source for the earliest of: the earliest armed timeout, the earliest software timer, the running thread’s quantum expiry when time slicing applies, the next budget replenishment when temporal protection is enabled, and Rationale: Missing an input means a late wake; an expensive computation means it cannot run on every change. Status: Accepted 2026-10-07 Verification: Test: each input is the earliest in turn and the observed wake matches; Analysis: no loop over all timers in the reprogram path. Trace: SPEC-003 §4.2 |
In tickless mode, on any interrupt that ends idle, the kernel shall update the clock from the hardware counter and process expired deadlines before any scheduling decision is made. Rationale: A wake from a non-timer interrupt must still see correct time and wake threads whose timeouts have passed. Status: Accepted 2026-10-07 Verification: Test: a GPIO-class interrupt wakes the idle core after a timeout deadline has passed; the timed-out thread runs before the interrupt’s own woken thread when its priority is higher. Trace: SPEC-003 §4.2, §4.3 |
Each port shall implement Rationale: One contract for every timer source keeps the kernel’s time code portable (KRN-IRQ-015 for timers). Status: Accepted 2026-10-07 Verification: Test: port conformance for the timer contract on each architecture; Analysis: configuration-time divisibility check. Trace: SPEC-003 §4.3 |
Armed timeouts and timers shall be kept in an intrusive structure with O(1) removal on the base profile (bounded O(armed nodes) removal on the tiny singly linked profile), O(1) access to the earliest deadline, and expiry in deadline order with arming order as the tie-break. The default shall be a doubly linked list ordered by absolute deadline; an alternative structure may be selected per profile behind the same interface only on the basis of measurements. Rationale: ADR-010; intrusive nodes satisfy KRN-TCB-007 and KRN-RQ-004. Status: Accepted 2026-10-07 Verification: Test: ordering and tie-break tests; Demonstration: insertion cost measured versus armed count per reference board. Trace: SPEC-003 §5.1; ADR-010 |
In the 32-bit tick profile, a finite timeout shall be clamped to Rationale: This is the condition under which wrap-safe comparison is correct (KRN-TIM-003). Status: Accepted 2026-10-07 Verification: Test: boundary tests at Trace: SPEC-003 §5.2 |
Arming with a duration shall compute the deadline as Rationale: API-024 at the kernel boundary. Status: Accepted 2026-10-07 Verification: Test: saturation and past-deadline cases for every blocking primitive. Trace: SPEC-003 §5.2; API-024 |
Rationale: Sleep is a wait with no object; zero sleep as yield is the common expectation and gives equal-priority threads a turn. Status: Accepted 2026-10-07 Verification: Test: conformance tests for sleep, sleep_until, zero sleep ordering among equal-priority threads, and cancellation. Trace: SPEC-003 §6; KRN-THR-009; KRN-SCH-008 |
The kernel shall provide Rationale: Timers are driven from ISRs as often as from threads; teardown needs a synchronous stop. Status: Accepted 2026-10-07 Verification: Test: API conformance including each function from ISR context where allowed. Trace: SPEC-003 §7.2 |
At expiry, a work-queue timer shall submit its embedded work item to its configured queue in O(1) without calling application code; an Rationale: KRN-TIM-013 and 014 at the mechanism level; the expiry path must stay bounded regardless of callback behavior. Status: Accepted 2026-10-07 Verification: Test: callback context tests; Analysis: expiry path Trace: SPEC-003 §7.3, §7.4 |
A periodic timer shall be re-armed from its previous deadline before its callback is run; whole periods already past at expiry shall be skipped and counted as overruns; an expiry whose work item is still queued from the previous expiry shall coalesce and count as an overrun. Expiry and overrun counts shall be readable and a trace point shall record each overrun. Rationale: No drift (KRN-TIM-015), no unbounded backlog, and visibility when the system cannot keep up. Status: Accepted 2026-10-07 Verification: Test: overload and sleep-past-several-periods scenarios on native; counts and trace match the model. Trace: SPEC-003 §7.4 |
Destroying a timer whose callback is pending or running shall be misuse: a kernel fault in checked builds and Rationale: Use-after-destroy in a work queue is otherwise undetectable. Status: Accepted 2026-10-07 Verification: Test: misuse suite for timers in both build kinds. Trace: SPEC-003 §7.5; KRN-OBJ-001 |
When time slicing is enabled for the running thread’s priority level, the kernel shall track its quantum expiry as a per-CPU deadline included in the next-deadline computation, and at expiry shall move the thread to the tail of its class only if another READY thread exists at the same effective priority. Rationale: Round-robin without a timer object per thread, and v0.1 §5.8’s rule that an uncontested quantum does not rotate. Status: Accepted 2026-10-07 Verification: Test: round-robin ordering tests in both clock modes; uncontested quantum does not cause a switch. Trace: SPEC-003 §8; KRN-SCH-007, KRN-SCH-026, KRN-SCH-037 |
The kernel shall provide Rationale: Benchmarks and critical-section statistics need a cheap fine-grained counter (KRN-RT-004 to 006). Status: Accepted 2026-10-07 Verification: Test: monotonic within a non-sleeping interval; frequency matches the documented source within tolerance on HIL. Trace: SPEC-003 §9 |
When Rationale: KRN-TIM-002 made concrete. Status: Accepted 2026-10-07 Verification: Test: pending deadlines unchanged across set and adjust; Analysis: no reference to wall-clock symbols from Trace: SPEC-003 §10 |
Rationale: Refines KRN-TIM-016 into the two concrete mechanisms EmbCC’s atomic support allows (09 §6). Status: Accepted 2026-10-07 Verification: Test: clock read torture test under continuous timer updates on each architecture; Analysis: no masking instruction in the sequence-lock read path. Trace: SPEC-003 §3.1; KRN-TIM-016 |
The timer interrupt body shall be bounded to updating the clock, expiring due deadlines, charging the quantum, setting the reschedule flag, and reprogramming the next deadline, and shall emit the trace points Rationale: KRN-IRQ-031 at the time subsystem’s side. Status: Accepted 2026-10-07 Verification: Analysis: handler stack usage and cycle budget; Demonstration: timer jitter benchmark. Trace: SPEC-003 §4.1, §5.3; KRN-IRQ-031 |
Each architecture port’s documentation shall state its timer source, counter width, frequency and the exact tick values it supports, maximum interval, tickless capability and the sleep states in which the counter runs, wake latency from each state, and cycle counter source. Rationale: Tickless and power decisions depend on facts only the port knows. Status: Accepted 2026-10-07 Verification: Inspection: Trace: SPEC-003 §11, §13 |
Checked builds shall detect and raise a kernel fault for arming an already armed timeout node, a blocking call from an Rationale: These are the time-related misuses that corrupt state silently in release builds. Status: Accepted 2026-10-07 Verification: Test: Trace: SPEC-003 §12; API-015 |