Zephyr OS Counter Alarms: Handle a Deadline That Passes While You Arm It
Reading a counter and then programming a nearby absolute alarm leaves a race: the counter can pass the requested value before the alarm is active. Without a deliberate late-setting policy, a missed near-term deadline can look like a request to wait for the next wrap. Treat that ambiguity as part of the scheduling design rather than assuming every absolute value is safely in the future.
This discussion is anchored to Zephyr 4.4.0's counter header. It proposes application checks and development tests, not a verified timing margin for a particular board. The live counter documentation entry is a navigation aid; version-specific claims here come from the tagged interface.
Distinguish absolute ticks from a relative delay
The tagged counter API makes an absolute alarm refer to a counter value, while a relative alarm is based on the reading taken during the call. It defines a guard period for detecting late absolute alarms, -ETIME for late setting, and an EXPIRE_WHEN_LATE flag for immediate expiry. The alarm API is not thread-safe.
Choose the form that represents the application's requirement. If a task needs a delay from when submission reaches the driver, a relative request may be appropriate. If it must preserve a previously established phase or timestamp, converting it to a fresh relative delay can silently move the intended event. Neither form eliminates the need to handle scheduling and submission outcomes.
For a hypothetical periodic sampler, repeatedly asking for a delay after each completed operation changes the schedule differently from advancing a fixed absolute deadline. Decide whether missed periods should be skipped, reported, or processed before selecting the API flags.
Size a guard against arming latency
The guard period exists to distinguish a recently missed absolute value from an intended value after wrap. In the documented model, a sufficiently close passed value is treated as late; a passed value outside that window can be treated as intentional wraparound. It is not a general promise of deadline accuracy.
Determine the selected counter's tick rate, direction, top value and driver capabilities. Then assess the longest credible delay between requesting the alarm and actually arming it. Interrupt interference and critical sections may matter to that delay. A guard selected from an unloaded demonstration is weak evidence for a loaded product.
Avoid making the guard arbitrarily large. Increasing the late-detection window also changes which absolute targets can be interpreted as intended future events. Review it against the application's maximum scheduling horizon and wrap behavior, not only against the nearest deadline.
Make late expiry one application decision
When a deadline has passed, specify whether the action remains useful. A status refresh might execute immediately; a precisely timed sample might instead be recorded as missed. That choice should be visible in the scheduling policy rather than emerging accidentally from a retry loop.
Keep the submission result and callback handling consistent. Do not assume an error result and a notification path are mutually exclusive under every selected late-expiry policy. Inspect and test the concrete driver behavior before implementing a fallback that could execute the same application action twice.
Give each scheduled operation an identity or generation so that cancellation, replacement and notification can be reconciled. Serialize access to a shared alarm channel. This ownership rule concerns concurrent application callers; it should not be replaced by an assumption that the driver API provides thread safety.
Exercise the wrap boundary deliberately
A useful development test arms targets comfortably ahead, very close ahead, just behind, and across wrap. Repeat with the intended guard and late-expiry setting under representative interference. Observe both the return value and callback count, including the order in which application state changes.
Do not infer acceptable behavior merely because a callback eventually arrives. Check whether it represents the intended period, an intentional wrap, or a late action. Record missed work separately from completed work so timing failures do not disappear inside otherwise successful execution.
The design is ready when a deadline that passes during arming has one documented outcome and cannot unexpectedly wait an entire counter cycle or execute twice. That is the practical value of reviewing the guard period together with application policy.
