Timer Service

One-shot and periodic timers with millisecond resolution (ADR-001). More...

Files
file	src/oal/timer/sapi_timer.c
	Timer service: validates parameters, then dispatches to the backend registered via sapi_timer_register_backend() (ADR-005).

Data Structures
struct	sapi_timer_config_t
	Configuration for sapi_timer_create(). More...

Typedefs
typedef struct sapi_timer_impl_s *	sapi_timer_handle_t
typedef void(*)	sapi_timer_callback_t(sapi_timer_handle_t handle, void *user_ctx)
	Signature for a timer expiry callback.

Enumerations
enum	sapi_timer_mode_t { SAPI_TIMER_MODE_ONE_SHOT = 0 , SAPI_TIMER_MODE_PERIODIC = 1 }
	Whether a timer fires once or repeatedly every period_ms. More...

Functions
	SAFEAPI_DECLARE_STORAGE (sapi_timer_storage_t, 64U)
sapi_status_t	sapi_timer_create (sapi_timer_storage_t *storage, const sapi_timer_config_t *config, sapi_timer_handle_t *out_handle)
	Creates a timer bound to caller-owned storage. Does not start it.
sapi_status_t	sapi_timer_start (sapi_timer_handle_t handle)
	Starts (or restarts) a created timer.
sapi_status_t	sapi_timer_stop (sapi_timer_handle_t handle)
	Stops a running timer; safe to call on an already-stopped timer.
sapi_status_t	sapi_timer_destroy (sapi_timer_handle_t handle)
	Destroys a timer, releasing any backend resources bound to it.
sapi_status_t	sapi_timer_now (sapi_timestamp_ms_t *out_now_ms)
	Returns the current monotonic time base used by all timers.

Detailed Description

One-shot and periodic timers with millisecond resolution (ADR-001).

Typedef Documentation

sapi_timer_handle_t

typedef struct sapi_timer_impl_s* sapi_timer_handle_t

Opaque handle bound to a sapi_timer_storage_t after sapi_timer_create().

Definition at line 31 of file sapi_timer.h.

sapi_timer_callback_t

typedef void(*) sapi_timer_callback_t(sapi_timer_handle_t handle, void *user_ctx)

Signature for a timer expiry callback.

Parameters

handle	The timer that expired.
user_ctx	Opaque context pointer supplied at creation time.

REQ-OAL-TIMER-003: the callback executes in a bounded-time, non-blocking context (exact context - task/ISR - is backend-defined and documented by the backend implementation).

Definition at line 49 of file sapi_timer.h.

Enumeration Type Documentation

sapi_timer_mode_t

enum sapi_timer_mode_t

Whether a timer fires once or repeatedly every period_ms.

Enumerator
SAPI_TIMER_MODE_ONE_SHOT	Fires once after period_ms, then stops.
SAPI_TIMER_MODE_PERIODIC	Fires every period_ms until stopped.

Definition at line 34 of file sapi_timer.h.

Function Documentation

SAFEAPI_DECLARE_STORAGE()

SAFEAPI_DECLARE_STORAGE	(	sapi_timer_storage_t	,
		64U	)

Opaque caller-owned storage for one timer instance. Size is part of the ABI.

sapi_timer_create()

sapi_status_t sapi_timer_create	(	sapi_timer_storage_t *	storage,
		const sapi_timer_config_t *	config,
		sapi_timer_handle_t *	out_handle )

Creates a timer bound to caller-owned storage. Does not start it.

Parameters

storage	Caller-owned storage the timer's state is placed into. Must not be NULL and must outlive the timer.
config	Timer configuration. Must not be NULL; config->callback must not be NULL and config->period_ms must be > 0.
out_handle	Receives the created timer's handle. Must not be NULL.

Returns

SAPI_STATUS_OK; SAPI_STATUS_INVALID_PARAM for a bad argument; SAPI_STATUS_NOT_INITIALIZED if no backend is registered (sapi_timer_register_backend()); SAPI_STATUS_NOT_SUPPORTED if the registered backend does not implement create. REQ-OAL-TIMER-010

Definition at line 44 of file sapi_timer.c.

sapi_timer_start()

sapi_status_t sapi_timer_start

(

sapi_timer_handle_t

handle

)

Starts (or restarts) a created timer.

Parameters

handle

Timer to start. Must not be NULL.

Returns

SAPI_STATUS_OK, SAPI_STATUS_INVALID_PARAM, SAPI_STATUS_NOT_INITIALIZED, or SAPI_STATUS_NOT_SUPPORTED (see sapi_timer_create()). REQ-OAL-TIMER-011

Definition at line 79 of file sapi_timer.c.

sapi_timer_stop()

sapi_status_t sapi_timer_stop

(

sapi_timer_handle_t

handle

)

Stops a running timer; safe to call on an already-stopped timer.

Parameters

handle

Timer to stop. Must not be NULL.

Returns

See sapi_timer_start(). REQ-OAL-TIMER-012

Definition at line 96 of file sapi_timer.c.

sapi_timer_destroy()

sapi_status_t sapi_timer_destroy

(

sapi_timer_handle_t

handle

)

Destroys a timer, releasing any backend resources bound to it.

Parameters

handle

Timer to destroy. Must not be NULL. Invalid to use after this call.

Returns

See sapi_timer_start(). REQ-OAL-TIMER-013

Definition at line 113 of file sapi_timer.c.

sapi_timer_now()

sapi_status_t sapi_timer_now

(

sapi_timestamp_ms_t *

out_now_ms

)

Returns the current monotonic time base used by all timers.

Parameters

out_now_ms

Receives the current time in milliseconds. Must not be NULL; set to 0 if this call fails.

Returns

SAPI_STATUS_OK, SAPI_STATUS_INVALID_PARAM, SAPI_STATUS_NOT_INITIALIZED, or SAPI_STATUS_NOT_SUPPORTED (see sapi_timer_create()). REQ-OAL-TIMER-014

Definition at line 130 of file sapi_timer.c.