STK C Timer API

Pure C interface for stk::time::TimerHost and stk::time::TimerHost::Timer. More...

Collaboration diagram for STK C Timer API:

Topics
	STK C PeriodicTrigger API
	Pure C interface for stk::time::PeriodicTrigger.

Macros
#define	STK_C_TIMER_MAX   32
	Maximum number of concurrent stk_timer_t instances per core (default: 32).
#define	STK_C_TIMER_HANDLER_STACK_SIZE   256
	Stack size of the timer handler, increase if your timers consume more (default: 256).

Typedefs
typedef struct stk_timerhost_t	stk_timerhost_t
	Opaque handle to a TimerHost instance (one per CPU core).
typedef struct stk_timer_t	stk_timer_t
	Opaque handle to a concrete timer managed by stk_timerhost_t.
typedef void(*	stk_timer_callback_t) (stk_timerhost_t *host, stk_timer_t *timer, void *user_data)
	Timer expiration callback invoked from within the TimerHost handler task.

Functions
stk_timerhost_t *	stk_timerhost_get (uint8_t core_nr)
	Obtain the pre-allocated TimerHost for the given CPU core.
void	stk_timerhost_init (stk_timerhost_t *host, stk_kernel_t *kernel, bool privileged)
	Initialize the TimerHost and register its internal tasks with the kernel.
bool	stk_timerhost_shutdown (stk_timerhost_t *host)
	Gracefully shut down the TimerHost.
bool	stk_timerhost_is_empty (const stk_timerhost_t *host)
	Return true when no timers are currently active on this host.
size_t	stk_timerhost_get_size (const stk_timerhost_t *host)
	Return the number of currently active timers on this host.
int64_t	stk_timerhost_get_time_now (const stk_timerhost_t *host)
	Return the last tick count snapshot maintained by the host's tick task.
stk_timer_t *	stk_timer_create (stk_timer_callback_t callback, void *user_data)
	Allocate a timer from the static pool.
void	stk_timer_destroy (stk_timer_t *timer)
	Return a timer handle back to the static pool.
bool	stk_timer_start (stk_timerhost_t *host, stk_timer_t *timer, uint32_t delay, uint32_t period)
	Start a timer.
bool	stk_timer_stop (stk_timerhost_t *host, stk_timer_t *timer)
	Stop a running timer.
bool	stk_timer_reset (stk_timerhost_t *host, stk_timer_t *timer)
	Reset a periodic timer's deadline (re-arm from now).
bool	stk_timer_restart (stk_timerhost_t *host, stk_timer_t *timer, uint32_t delay, uint32_t period)
	Atomically stop and re-start a timer.
bool	stk_timer_start_or_reset (stk_timerhost_t *host, stk_timer_t *timer, uint32_t delay, uint32_t period)
	Start the timer if inactive, or reset its deadline if already active and periodic.
bool	stk_timer_set_period (stk_timerhost_t *host, stk_timer_t *timer, uint32_t period)
	Change the period of a running periodic timer without affecting the current deadline.
bool	stk_timer_is_active (const stk_timer_t *timer)
	Check whether a timer is currently active (started and not yet expired/stopped).
uint32_t	stk_timer_get_period (const stk_timer_t *timer)
	Get the timer's reload period.
int64_t	stk_timer_get_deadline (const stk_timer_t *timer)
	Get the absolute expiration tick count of the timer's next deadline.
int64_t	stk_timer_get_timestamp (const stk_timer_t *timer)
	Get the tick count at which the timer last expired.
uint32_t	stk_timer_get_remaining_time (const stk_timer_t *timer)
	Get remaining ticks until next expiration.

Detailed Description

Pure C interface for stk::time::TimerHost and stk::time::TimerHost::Timer.

Macro Definition Documentation

STK_C_TIMER_HANDLER_STACK_SIZE

#define STK_C_TIMER_HANDLER_STACK_SIZE   256

Stack size of the timer handler, increase if your timers consume more (default: 256).

Definition at line 52 of file stk_c_time.h.

STK_C_TIMER_MAX

#define STK_C_TIMER_MAX   32

Maximum number of concurrent stk_timer_t instances per core (default: 32).

Note

Increase if your application needs more simultaneous timers.

Definition at line 45 of file stk_c_time.h.

Typedef Documentation

stk_timer_callback_t

typedef void(* stk_timer_callback_t) (stk_timerhost_t *host, stk_timer_t *timer, void *user_data)

Timer expiration callback invoked from within the TimerHost handler task.

Parameters

[in]	host	TimerHost that fired the timer.
[in]	timer	The timer that expired.
[in]	user_data	Opaque pointer supplied at timer creation time.

Warning

Must not call blocking kernel services (e.g. stk_mutex_lock with a non-zero timeout) unless the handler task stack is large enough.

Definition at line 74 of file stk_c_time.h.

stk_timer_t

typedef struct stk_timer_t stk_timer_t

Opaque handle to a concrete timer managed by stk_timerhost_t.

Definition at line 65 of file stk_c_time.h.

stk_timerhost_t

typedef struct stk_timerhost_t stk_timerhost_t

Opaque handle to a TimerHost instance (one per CPU core).

Definition at line 61 of file stk_c_time.h.

Function Documentation

stk_timer_create()

stk_timer_t * stk_timer_create	(	stk_timer_callback_t	callback,
		void *	user_data )

Allocate a timer from the static pool.

Parameters

[in]	callback	Function to call when the timer expires (must not be NULL).
[in]	user_data	Opaque pointer forwarded to callback on expiration.

Returns

Timer handle, or NULL if the pool is exhausted (STK_C_TIMER_MAX reached).

Note

The returned handle is valid until stk_timer_destroy() is called. It must not be active (i.e. not currently started) when destroyed.

Definition at line 181 of file stk_c_time.cpp.

{
    STK_ASSERT(callback != nullptr);
 
    sync::ScopedCriticalSection __cs;
 
    for (uint32_t i = 0; i < STK_C_TIMERS_TOTAL; ++i)
    {
        if (!s_Timers[i].busy)
        {
            s_Timers[i].busy = true;
            s_Timers[i].timer.handle.Initialize(callback, user_data);
 
            return &s_Timers[i].timer;
        }
    }
 
    // pool exhausted, you must increase STK_C_TIMER_MAX
    STK_ASSERT(false);
    return nullptr;
}

References s_Timers, STK_ASSERT, and STK_C_TIMERS_TOTAL.

stk_timer_destroy()

void stk_timer_destroy

(

stk_timer_t *

timer

)

Return a timer handle back to the static pool.

Parameters

[in]

timer

Timer handle.

Warning

The timer must have been stopped (or never started) before calling this. Destroying an active timer is a programming error and triggers an assertion.

Definition at line 203 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    // destroying an active timer is a programming error
    STK_ASSERT(!timer->handle.IsActive());
 
    sync::ScopedCriticalSection __cs;
 
    for (uint32_t i = 0; i < STK_C_TIMERS_TOTAL; ++i)
    {
        if (s_Timers[i].busy && (&s_Timers[i].timer == timer))
        {
            timer->handle.Reset();
            s_Timers[i].busy = false;
            return;
        }
    }
 
    // timer not found in the pool: indicates a double-free or corruption
    STK_ASSERT(false);
}

References stk_timer_t::handle, stk::time::TimerHost::Timer::IsActive(), CTimerWrapper::Reset(), s_Timers, STK_ASSERT, and STK_C_TIMERS_TOTAL.

Here is the call graph for this function:

stk_timer_get_deadline()

int64_t stk_timer_get_deadline

(

const stk_timer_t *

timer

)

Get the absolute expiration tick count of the timer's next deadline.

Parameters

[in]

timer

Timer handle.

Returns

Absolute deadline (ticks). Meaningful only when the timer is active.

Definition at line 311 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    return (int64_t)timer->handle.GetDeadline();
}

References stk::time::TimerHost::Timer::GetDeadline(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_period()

uint32_t stk_timer_get_period

(

const stk_timer_t *

timer

)

Get the timer's reload period.

Parameters

[in]

timer

Timer handle.

Returns

Period in ticks, or 0 for a one-shot timer.

Definition at line 304 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    return timer->handle.GetPeriod();
}

References stk::time::TimerHost::Timer::GetPeriod(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_remaining_time()

uint32_t stk_timer_get_remaining_time

(

const stk_timer_t *

timer

)

Get remaining ticks until next expiration.

Parameters

[in]

timer

Timer handle.

Returns

Remaining ticks, or 0 if already expired or not active.

Note

Computed from the last value written by the host's tick task - may be up to one tick-task wake cycle stale.

Definition at line 325 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    return timer->handle.GetRemainingTime();
}

References stk::time::TimerHost::Timer::GetRemainingTime(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_get_timestamp()

int64_t stk_timer_get_timestamp

(

const stk_timer_t *

timer

)

Get the tick count at which the timer last expired.

Parameters

[in]

timer

Timer handle.

Returns

Expiration timestamp (ticks). Zero if the timer has never fired.

Definition at line 318 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    return (int64_t)timer->handle.GetTimestamp();
}

References stk::time::TimerHost::Timer::GetTimestamp(), stk_timer_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timer_is_active()

bool stk_timer_is_active

(

const stk_timer_t *

timer

)

Check whether a timer is currently active (started and not yet expired/stopped).

Parameters

[in]

timer

Timer handle.

Returns

true if the timer is active.

Note

Advisory - may change immediately after the call.

Definition at line 297 of file stk_c_time.cpp.

{
    STK_ASSERT(timer != nullptr);
 
    return timer->handle.IsActive();
}

References stk_timer_t::handle, stk::time::TimerHost::Timer::IsActive(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_reset()

bool stk_timer_reset	(	stk_timerhost_t *	host,
		stk_timer_t *	timer )

Reset a periodic timer's deadline (re-arm from now).

Parameters

[in]	host	TimerHost managing the timer.
[in]	timer	Timer handle. Must be active and periodic (period != 0).

Returns

true on success, false if preconditions are not met or the command queue is full.

Definition at line 255 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(timer != nullptr);
 
    return host->handle.Reset(timer->handle);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::Reset(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_restart()

bool stk_timer_restart	(	stk_timerhost_t *	host,
		stk_timer_t *	timer,
		uint32_t	delay,
		uint32_t	period )

Atomically stop and re-start a timer.

Unlike calling stk_timer_stop() + stk_timer_start(), this operation is atomic with respect to the tick task: the timer cannot fire between the implicit stop and re-start. Consumes only one command queue slot.

Parameters

[in]	host	TimerHost managing the timer.
[in]	timer	Timer handle (active or inactive).
[in]	delay	Initial delay in ticks before the first expiration.
[in]	period	Reload period in ticks (0 = one-shot).

Returns

true on success, false if the command queue is full.

Definition at line 263 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(timer != nullptr);
 
    // refresh host association before timer can fire
    timer->handle.SetHostHandle(host);
 
    return host->handle.Restart(timer->handle, delay, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::Restart(), CTimerWrapper::SetHostHandle(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_set_period()

bool stk_timer_set_period	(	stk_timerhost_t *	host,
		stk_timer_t *	timer,
		uint32_t	period )

Change the period of a running periodic timer without affecting the current deadline.

The new period takes effect on the next reload after the current deadline fires. To apply immediately, follow with stk_timer_reset().

Parameters

[in]	host	TimerHost managing the timer.
[in]	timer	Timer handle. Must be active and periodic.
[in]	period	New reload period in ticks. Must be non-zero.

Returns

true on success, false if preconditions are not met or the command queue is full.

Definition at line 285 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(timer != nullptr);
 
    return host->handle.SetPeriod(timer->handle, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, stk::time::TimerHost::SetPeriod(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_start()

bool stk_timer_start	(	stk_timerhost_t *	host,
		stk_timer_t *	timer,
		uint32_t	delay,
		uint32_t	period )

Start a timer.

Parameters

[in]	host	TimerHost that will manage this timer.
[in]	timer	Timer handle. Must not already be active.
[in]	delay	Initial delay in ticks before the first expiration.
[in]	period	Reload period in ticks. Pass 0 for a one-shot timer.

Returns

true on success, false if the timer is already active or the command queue is full.

Definition at line 233 of file stk_c_time.cpp.

{
    STK_ASSERT(host  != nullptr);
    STK_ASSERT(timer != nullptr);
 
    // refresh host association before timer can fire
    timer->handle.SetHostHandle(host);
 
    return host->handle.Start(timer->handle, delay, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, CTimerWrapper::SetHostHandle(), stk::time::TimerHost::Start(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_start_or_reset()

bool stk_timer_start_or_reset	(	stk_timerhost_t *	host,
		stk_timer_t *	timer,
		uint32_t	delay,
		uint32_t	period )

Start the timer if inactive, or reset its deadline if already active and periodic.

Collapses the common pattern:

if (stk_timer_is_active(t)) stk_timer_reset(host, t);
else                        stk_timer_start(host, t, delay, period);

into a single atomic operation, eliminating the TOCTOU race. If the timer is active but one-shot, no action is taken.

Parameters

[in]	host	TimerHost managing the timer.
[in]	timer	Timer handle (active or inactive).
[in]	delay	Initial delay in ticks (used only when starting).
[in]	period	Reload period in ticks (used only when starting, 0 = one-shot).

Returns

true on success, false if the command queue is full.

Definition at line 274 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(timer != nullptr);
 
    // refresh host association (harmless if timer is already active on host)
    timer->handle.SetHostHandle(host);
 
    return host->handle.StartOrReset(timer->handle, delay, period);
}

References stk_timer_t::handle, stk_timerhost_t::handle, CTimerWrapper::SetHostHandle(), stk::time::TimerHost::StartOrReset(), and STK_ASSERT.

Here is the call graph for this function:

stk_timer_stop()

bool stk_timer_stop	(	stk_timerhost_t *	host,
		stk_timer_t *	timer )

Stop a running timer.

Parameters

[in]	host	TimerHost managing the timer.
[in]	timer	Timer handle. Must be currently active.

Returns

true on success, false if the timer is not active or the command queue is full.

Definition at line 247 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
    STK_ASSERT(timer != nullptr);
 
    return host->handle.Stop(timer->handle);
}

References stk_timer_t::handle, stk_timerhost_t::handle, STK_ASSERT, and stk::time::TimerHost::Stop().

Here is the call graph for this function:

stk_timerhost_get()

stk_timerhost_t * stk_timerhost_get

(

uint8_t

core_nr

)

Obtain the pre-allocated TimerHost for the given CPU core.

Parameters

[in]

core_nr

CPU core index (0 … STK_C_CPU_COUNT-1).

Returns

TimerHost handle, or NULL if core_nr is out of range.

Note

The host instance exists in static storage; do not free it.

Definition at line 130 of file stk_c_time.cpp.

{
    if (core_nr >= STK_C_CPU_COUNT)
        return nullptr;
 
    return &s_TimerHosts[core_nr];
}

References s_TimerHosts, and STK_C_CPU_COUNT.

stk_timerhost_get_size()

size_t stk_timerhost_get_size

(

const stk_timerhost_t *

host

)

Return the number of currently active timers on this host.

Parameters

[in]

host

TimerHost handle.

Returns

Advisory active timer count (may change immediately after the call).

Definition at line 163 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.GetSize();
}

References stk::time::TimerHost::GetSize(), stk_timerhost_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_get_time_now()

int64_t stk_timerhost_get_time_now

(

const stk_timerhost_t *

host

)

Return the last tick count snapshot maintained by the host's tick task.

Parameters

[in]

host

TimerHost handle.

Returns

Tick count (may be one tick-task wake cycle stale).

Definition at line 170 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return (int64_t)host->handle.GetTimeNow();
}

References stk::time::TimerHost::GetTimeNow(), stk_timerhost_t::handle, and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_init()

void stk_timerhost_init	(	stk_timerhost_t *	host,
		stk_kernel_t *	kernel,
		bool	privileged )

Initialize the TimerHost and register its internal tasks with the kernel.

Parameters

[in]	host	TimerHost handle obtained via stk_timerhost_get().
[in]	kernel	Kernel instance the timer tasks will be added to.
[in]	privileged	If true the internal handler tasks run in privileged mode, otherwise they run in user mode.

Note

Must be called before stk_kernel_start() and before any stk_timer_* operations on this host.

Definition at line 138 of file stk_c_time.cpp.

{
    STK_ASSERT(host   != nullptr);
    STK_ASSERT(kernel != nullptr);
 
    host->handle.Initialize(reinterpret_cast<IKernel *>(kernel),
        (privileged ? ACCESS_PRIVILEGED : ACCESS_USER));
}

References stk::ACCESS_PRIVILEGED, stk::ACCESS_USER, stk_timerhost_t::handle, stk::time::TimerHost::Initialize(), and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_is_empty()

bool stk_timerhost_is_empty

(

const stk_timerhost_t *

host

)

Return true when no timers are currently active on this host.

Parameters

[in]

host

TimerHost handle.

Returns

Advisory empty flag (may change immediately after the call).

Definition at line 156 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.IsEmpty();
}

References stk_timerhost_t::handle, stk::time::TimerHost::IsEmpty(), and STK_ASSERT.

Here is the call graph for this function:

stk_timerhost_shutdown()

bool stk_timerhost_shutdown

(

stk_timerhost_t *

host

)

Gracefully shut down the TimerHost.

Parameters

[in]

host

TimerHost handle.

Returns

true on success, false if the internal command queue is full.

Note

All active timers are stopped. After shutdown the host must not be used.

Definition at line 149 of file stk_c_time.cpp.

{
    STK_ASSERT(host != nullptr);
 
    return host->handle.Shutdown();
}

References stk_timerhost_t::handle, stk::time::TimerHost::Shutdown(), and STK_ASSERT.

Here is the call graph for this function: