Periodic and one-shot software timer API backed by the active RTOS. More...

Typedefs
typedef struct ove_timer *	ove_timer_t
	Opaque handle for a software timer object.

typedef void(*	ove_timer_fn) (ove_timer_t timer, void *user_data)
	Timer expiry callback function prototype.

Functions
int	ove_timer_init (ove_timer_t timer, ove_timer_storage_t storage, ove_timer_fn callback, void *user_data, uint32_t period_ms, int one_shot)
	Initialise a software timer using caller-supplied static storage.

void	ove_timer_deinit (ove_timer_t timer)
	Stop and release resources held by a timer initialised with ove_timer_init().

int	ove_timer_init_ns (ove_timer_t timer, ove_timer_storage_t storage, ove_timer_fn callback, void *user_data, uint64_t period_ns, int one_shot)
	Initialise a software timer with a nanosecond period using caller-supplied static storage.

int	ove_timer_set_period_ns (ove_timer_t timer, uint64_t period_ns)
	Change the period of an existing timer and (re)arm it.

int	ove_timer_create (ove_timer_t timer, ove_timer_fn callback, void user_data, uint32_t period_ms, int one_shot)
	Allocate and initialise a software timer from the heap.

int	ove_timer_create_ns (ove_timer_t timer, ove_timer_fn callback, void user_data, uint64_t period_ns, int one_shot)
	Allocate and initialise a software timer with a nanosecond period from the heap.

void	ove_timer_destroy (ove_timer_t timer)
	Stop and free a timer allocated with ove_timer_create().

int	ove_timer_start (ove_timer_t timer)
	Start (arm) a timer.

int	ove_timer_stop (ove_timer_t timer)
	Stop a running timer without invoking its callback.

int	ove_timer_reset (ove_timer_t timer)
	Restart a timer's countdown from the beginning of its period.

Detailed Description

Periodic and one-shot software timer API backed by the active RTOS.

Note: All functions in this group require CONFIG_OVE_TIMER to be defined. When CONFIG_OVE_TIMER is not set, every function is replaced by a static inline stub that returns OVE_ERR_NOT_SUPPORTED.

Two allocation strategies are available:

_create() / _destroy() — heap-allocated. Available only when OVE_HEAP_TIMER is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
_init() / _deinit() — caller-supplied storage. Available in both modes. See OVE_TIMER_DEFINE_STATIC for a one-step static helper.

Typedef Documentation

◆ ove_timer_fn

typedef void(* ove_timer_fn) (ove_timer_t timer, void *user_data)

Timer expiry callback function prototype.

Invoked by the RTOS timer service task (or equivalent) when the timer period elapses. Implementations must be non-blocking and short.

Parameters

[in]	timer	Handle of the timer that fired.
[in]	user_data	Opaque pointer supplied at timer creation time.

Function Documentation

◆ ove_timer_init()

int ove_timer_init	(	ove_timer_t *	timer,
		ove_timer_storage_t *	storage,
		ove_timer_fn	callback,
		void *	user_data,
		uint32_t	period_ms,
		int	one_shot
	)

Initialise a software timer using caller-supplied static storage.

Creates a timer in the stopped state. Call ove_timer_start() to arm it.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[out]	timer	Receives the opaque timer handle on success.
[in]	storage	Pointer to statically allocated backend storage. Must remain valid for the lifetime of the timer.
[in]	callback	Function invoked when the timer expires. Must not be NULL.
[in]	user_data	Opaque pointer forwarded to `callback` on each expiry. May be NULL.
[in]	period_ms	Timer period in milliseconds. Must be > 0.
[in]	one_shot	Non-zero to create a one-shot timer (fires once then stops automatically); zero for a periodic timer that reloads automatically.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_deinit, ove_timer_create, ove_timer_start

◆ ove_timer_deinit()

void ove_timer_deinit ( ove_timer_t timer )

Stop and release resources held by a timer initialised with ove_timer_init().

Stops the timer if it is running. The static storage supplied at init time is not freed.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[in] timer Handle returned by ove_timer_init().

See also: ove_timer_init

◆ ove_timer_init_ns()

int ove_timer_init_ns	(	ove_timer_t *	timer,
		ove_timer_storage_t *	storage,
		ove_timer_fn	callback,
		void *	user_data,
		uint64_t	period_ns,
		int	one_shot
	)

Initialise a software timer with a nanosecond period using caller-supplied static storage.

Identical to ove_timer_init except the period is specified in nanoseconds. Used primarily by the async runtime substrate (CONFIG_OVE_ASYNC) to drive the Embassy time driver at sub-ms granularity.

Effective resolution is backend-dependent:

Zephyr: underlying tick (K_NSEC); typically µs-class.
FreeRTOS: rounded up to configTICK_RATE_HZ; typically 1 ms.
NuttX: POSIX timer resolution; typically µs.
POSIX: timer_create with CLOCK_MONOTONIC; nsec.

Note: Requires CONFIG_OVE_TIMER. When CONFIG_OVE_ASYNC is off, the function is still available — it just isn't routed by the async substrate.

Parameters

[out]	timer	Receives the opaque timer handle on success.
[in]	storage	Pointer to statically allocated backend storage.
[in]	callback	Function invoked when the timer expires. Must not be NULL.
[in]	user_data	Opaque pointer forwarded to `callback`.
[in]	period_ns	Timer period in nanoseconds. Must be > 0.
[in]	one_shot	Non-zero for one-shot, zero for periodic.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_init, ove_timer_create_ns

◆ ove_timer_set_period_ns()

int ove_timer_set_period_ns	(	ove_timer_t	timer,
		uint64_t	period_ns
	)

Change the period of an existing timer and (re)arm it.

Atomically updates the timer's period to period_ns and arms it so the next fire happens after that period. If the timer was already running it is restarted with the new period (no stale fire of the old period). Designed for one-shot alarm reprogramming patterns where the deadline keeps changing — used by the Embassy time driver to re-arm its global alarm at each schedule_wake.

Underlying primitive per backend:

FreeRTOS: xTimerChangePeriod (atomic period change + arm).
POSIX: timer_settime with a new itimerspec.
Zephyr: k_timer_start with the new period.
NuttX: timer_settime.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[in]	timer	Timer handle to reprogram.
[in]	period_ns	New period in nanoseconds. Must be > 0; backends round up to the resolution floor.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_init_ns, ove_timer_start, ove_timer_stop

◆ ove_timer_create()

int ove_timer_create	(	ove_timer_t *	timer,
		ove_timer_fn	callback,
		void *	user_data,
		uint32_t	period_ms,
		int	one_shot
	)

Allocate and initialise a software timer from the heap.

Creates a timer in the stopped state. Call ove_timer_start() to arm it.

Note: Requires CONFIG_OVE_TIMER and OVE_HEAP_TIMER (i.e. CONFIG_OVE_ZERO_HEAP must not be set).

Parameters

[out]	timer	Receives the opaque timer handle on success.
[in]	callback	Function invoked when the timer expires. Must not be NULL.
[in]	user_data	Opaque pointer forwarded to `callback` on each expiry. May be NULL.
[in]	period_ms	Timer period in milliseconds. Must be > 0.
[in]	one_shot	Non-zero to create a one-shot timer; zero for a periodic auto-reloading timer.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_destroy, ove_timer_init, ove_timer_start

◆ ove_timer_create_ns()

int ove_timer_create_ns	(	ove_timer_t *	timer,
		ove_timer_fn	callback,
		void *	user_data,
		uint64_t	period_ns,
		int	one_shot
	)

Allocate and initialise a software timer with a nanosecond period from the heap.

Identical to ove_timer_create except the period is specified in nanoseconds. See ove_timer_init_ns for the per-backend resolution floor.

Note: Requires CONFIG_OVE_TIMER and OVE_HEAP_TIMER.

Parameters

[out]	timer	Receives the opaque timer handle on success.
[in]	callback	Function invoked when the timer expires. Must not be NULL.
[in]	user_data	Opaque pointer forwarded to `callback`.
[in]	period_ns	Timer period in nanoseconds. Must be > 0.
[in]	one_shot	Non-zero for one-shot, zero for periodic.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_create, ove_timer_init_ns

◆ ove_timer_destroy()

void ove_timer_destroy ( ove_timer_t timer )

Stop and free a timer allocated with ove_timer_create().

Note: Requires CONFIG_OVE_TIMER and OVE_HEAP_TIMER.

Parameters

[in] timer Handle returned by ove_timer_create().

See also: ove_timer_create

◆ ove_timer_start()

int ove_timer_start ( ove_timer_t timer )

Start (arm) a timer.

If the timer is already running, it is restarted from the beginning of its period. Has no effect if the timer is in a terminated state.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[in] timer Timer handle to start.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_stop, ove_timer_reset

◆ ove_timer_stop()

int ove_timer_stop ( ove_timer_t timer )

Stop a running timer without invoking its callback.

If the timer is already stopped, this function has no effect.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[in] timer Timer handle to stop.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_start, ove_timer_reset

◆ ove_timer_reset()

int ove_timer_reset ( ove_timer_t timer )

Restart a timer's countdown from the beginning of its period.

Equivalent to stopping and then starting the timer, but performed atomically with respect to the RTOS timer service. Useful for implementing watchdog-style "kick" patterns.

Note: Requires CONFIG_OVE_TIMER.

Parameters

[in] timer Timer handle to reset.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_timer_start, ove_timer_stop

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ove_timer_fn

Function Documentation

◆ ove_timer_init()

◆ ove_timer_deinit()

◆ ove_timer_init_ns()

◆ ove_timer_set_period_ns()

◆ ove_timer_create()

◆ ove_timer_create_ns()

◆ ove_timer_destroy()

◆ ove_timer_start()

◆ ove_timer_stop()

◆ ove_timer_reset()