SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
STK C Timer API

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

Collaboration diagram for STK C Timer API:

Topics

 STK C PeriodicTrigger API
 Pure C interface for stk::time::PeriodicTrigger.
 STK C Timer Synchronous API
 Blocking variants of the timer control functions.

Namespaces

namespace  stk
 Namespace of STK package.

Classes

struct  stk_timerhost_config_t
 Optional configuration of the timer host tasks, see stk_timerhost_init_ex(). More...
struct  stk_timer_mem_t
 Opaque memory container for a stk_timer_t instance. More...
struct  stk_timer_info_t
 Consistent snapshot of a timer, see stk_timer_query_sync(). More...

Macros

#define STK_C_TIMER_COMMAND_QUEUE_MAX   (32U)
#define STK_C_TIMER_HANDLER_STACK_SIZE   (256U)
 Stack size of the timer handler, increase if your timers consume more (default: 256).
#define STK_C_TIMER_THREADS_COUNT   (1U)
 Number of handler tasks serving expired timers in task mode (default: 1). Sizes stk_timerhost_config_t::handler_stack and is forwarded to STK_TIMER_THREADS_COUNT of the C++ implementation.
#define STK_TIMER_IMPL_SIZE   (14U)
 A memory size (multiples of uint64_t) required for the stk_timer_t instance.
#define STK_TIMER_COMMAND_QUEUE_SIZE   (STK_C_TIMER_COMMAND_QUEUE_MAX)
#define STK_TIMER_THREADS_COUNT   (STK_C_TIMER_THREADS_COUNT)
#define STK_TIMER_HANDLER_STACK_SIZE   (STK_C_TIMER_HANDLER_STACK_SIZE)

Typedefs

typedef struct stk_timerhost_config_t stk_timerhost_config_t
 Optional configuration of the timer host tasks, see stk_timerhost_init_ex().
typedef struct stk_timerhost_t stk_timerhost_t
 Opaque handle to a TimerHost instance (one per CPU core).
typedef struct stk_timer_mem_t stk_timer_mem_t
 Opaque memory container for a stk_timer_t instance.
typedef struct stk_timer_t stk_timer_t
 Opaque handle to a concrete timer managed by stk_timerhost_t.
typedef enum stk_timer_result_t stk_timer_result_t
 Outcome of a timer or host command, mirrors stk::time::TimerHost::EResult.
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 (task mode) or inline from stk_timerhost_process() (polled mode).
typedef struct stk_timer_info_t stk_timer_info_t
 Consistent snapshot of a timer, see stk_timer_query_sync().

Enumerations

enum  stk_timer_result_t {
  STK_TIMER_RES_CANCELLED = -5 ,
  STK_TIMER_RES_INVALID_PARAM = -4 ,
  STK_TIMER_RES_QUEUE_FULL = -3 ,
  STK_TIMER_RES_NOT_READY = -2 ,
  STK_TIMER_RES_FAIL = -1 ,
  STK_TIMER_RES_OK = 0 ,
  STK_TIMER_RES_ACTIVE = 1 ,
  STK_TIMER_RES_INACTIVE = 2 ,
  STK_TIMER_RES_NOT_PERIODIC = 3 ,
  STK_TIMER_RES_QUEUED = 4
}
 Outcome of a timer or host command, mirrors stk::time::TimerHost::EResult. More...

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.
void stk_timerhost_config_init (stk_timerhost_config_t *cfg)
 Fill a configuration with defaults (default weights, internal stack buffers).
stk_add_result_t stk_timerhost_init_ex (stk_timerhost_t *host, stk_kernel_t *kernel, bool privileged, const stk_timerhost_config_t *cfg)
 Initialize the TimerHost in task mode with explicit weights / stacks and report failures.
void stk_timerhost_init_polled (stk_timerhost_t *host)
 Initialize the TimerHost in polled mode (no kernel tasks are created).
stk_timeout_t stk_timerhost_process (stk_timerhost_t *host)
 Run the host once (polled mode only): execute pending commands, evaluate deadlines and invoke the callback of every expired timer inline.
stk_timer_result_t 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_mem_t *const membuf, stk_timer_callback_t callback, void *user_data)
 Construct a timer in the supplied memory buffer.
void stk_timer_destroy (stk_timer_t *tmr)
 Destroy a timer (calls the C++ destructor in-place).
stk_timer_result_t stk_timer_start (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
 Start a timer.
stk_timer_result_t stk_timer_stop (stk_timerhost_t *host, stk_timer_t *tmr)
 Stop a running timer.
stk_timer_result_t stk_timer_reset (stk_timerhost_t *host, stk_timer_t *tmr)
 Reset a periodic timer's deadline (re-arm from now).
stk_timer_result_t stk_timer_restart (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
 Atomically stop and re-start a timer.
stk_timer_result_t stk_timer_start_or_reset (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period_ticks)
 Start the timer if inactive, or reset its deadline if already active and periodic.
stk_timer_result_t stk_timer_set_period (stk_timerhost_t *host, stk_timer_t *tmr, uint32_t period_ticks)
 Change the period of a running periodic timer without affecting the current deadline.
bool stk_timer_is_active (const stk_timer_t *tmr)
 Check whether a timer is currently active (started and not yet expired/stopped).
uint32_t stk_timer_get_period (const stk_timer_t *tmr)
 Get the timer's reload period.
int64_t stk_timer_get_deadline (const stk_timer_t *tmr)
 Get the absolute expiration tick count of the timer's next deadline.
int64_t stk_timer_get_timestamp (const stk_timer_t *tmr)
 Get the tick count at which the timer last expired.
uint32_t stk_timer_get_remaining_ticks (const stk_timer_t *tmr)
 Get remaining ticks until next expiration.
stk::time::TimerHost * stk_timerhost_get_instance (stk_timerhost_t *host)
 Get the underlying C++ stk::time::TimerHost object wrapped by a stk_timerhost_t handle.
stk::time::Timer * stk_timer_get_instance (stk_timer_t *tmr)
 Get the underlying C++ stk::time::Timer object wrapped by a stk_timer_t handle.
stk::time::PeriodicTrigger * stk_periodic_trigger_get_instance (stk_periodic_trigger_t *trig)
 Get the underlying C++ stk::time::PeriodicTrigger object wrapped by a stk_periodic_trigger_t handle.

Detailed Description

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

Macro Definition Documentation

◆ STK_C_TIMER_COMMAND_QUEUE_MAX

#define STK_C_TIMER_COMMAND_QUEUE_MAX   (32U)

Definition at line 73 of file stk_c_time.h.

◆ STK_C_TIMER_HANDLER_STACK_SIZE

#define STK_C_TIMER_HANDLER_STACK_SIZE   (256U)

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

Definition at line 81 of file stk_c_time.h.

◆ STK_C_TIMER_THREADS_COUNT

#define STK_C_TIMER_THREADS_COUNT   (1U)

Number of handler tasks serving expired timers in task mode (default: 1). Sizes stk_timerhost_config_t::handler_stack and is forwarded to STK_TIMER_THREADS_COUNT of the C++ implementation.

Note
Must have the same value in every translation unit of the application.

Definition at line 91 of file stk_c_time.h.

Referenced by stk_timerhost_config_init(), and stk_timerhost_init_ex().

◆ STK_TIMER_COMMAND_QUEUE_SIZE

#define STK_TIMER_COMMAND_QUEUE_SIZE   (STK_C_TIMER_COMMAND_QUEUE_MAX)

Definition at line 680 of file stk_c_time.h.

◆ STK_TIMER_HANDLER_STACK_SIZE

#define STK_TIMER_HANDLER_STACK_SIZE   (STK_C_TIMER_HANDLER_STACK_SIZE)

Definition at line 684 of file stk_c_time.h.

◆ STK_TIMER_IMPL_SIZE

#define STK_TIMER_IMPL_SIZE   (14U)

A memory size (multiples of uint64_t) required for the stk_timer_t instance.

Note
The timer holds 64-bit tick values, the size covers LP64 targets (the 32-bit value is sufficient for 32-bit ones, but one value keeps the memory type portable). Verified at build time by ConstructIn() in stk_timer_create(), increase this value if it fails.

Definition at line 124 of file stk_c_time.h.

◆ STK_TIMER_THREADS_COUNT

#define STK_TIMER_THREADS_COUNT   (STK_C_TIMER_THREADS_COUNT)

Definition at line 682 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 (task mode) or inline from stk_timerhost_process() (polled mode).

Parameters
[in]hostTimerHost that fired the timer.
[in]timerThe timer that expired.
[in]user_dataOpaque 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 169 of file stk_c_time.h.

◆ stk_timer_info_t

typedef struct stk_timer_info_t stk_timer_info_t

Consistent snapshot of a timer, see stk_timer_query_sync().

◆ stk_timer_mem_t

typedef struct stk_timer_mem_t stk_timer_mem_t

Opaque memory container for a stk_timer_t instance.

Note
Declare as static or on the stack (not on the heap), it must outlive the timer.
Aligned to 8 bytes because the timer holds 64-bit Ticks values.

◆ stk_timer_result_t

Outcome of a timer or host command, mirrors stk::time::TimerHost::EResult.

Note
Negative values are errors: nothing was queued. Positive values report the state of the timer, or that the outcome is unknown. STK_TIMER_RES_OK is 0: a check like if(stk_timer_start(...)) means "failed", compare with STK_TIMER_RES_OK explicitly.
The control functions are asynchronous: STK_TIMER_RES_OK means the command was accepted into the command queue, it is executed later by the tick task and its outcome is not reported. The timer state checks (ACTIVE / INACTIVE / NOT_PERIODIC) are advisory: they are evaluated from the state applied by the tick task so far. The synchronous functions (stk_timer_start_sync() and the others) report the exact outcome instead.

◆ 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 136 of file stk_c_time.h.

◆ stk_timerhost_config_t

typedef struct stk_timerhost_config_t stk_timerhost_config_t

Optional configuration of the timer host tasks, see stk_timerhost_init_ex().

Note
Always fill with stk_timerhost_config_init() first, then override the fields of interest.
Weights are strategy-specific and forwarded to the kernel unchanged (see stk::time::TimerHost, "Scheduling weights"). With the preemption-threshold strategy the weights must be set explicitly, the default weight is not neutral for it.
Externally supplied stacks must outlive the host, be distinct from each other and satisfy the alignment / memory protection requirements of the platform.

◆ stk_timerhost_t

typedef struct stk_timerhost_t stk_timerhost_t

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

Definition at line 117 of file stk_c_time.h.

Enumeration Type Documentation

◆ stk_timer_result_t

Outcome of a timer or host command, mirrors stk::time::TimerHost::EResult.

Note
Negative values are errors: nothing was queued. Positive values report the state of the timer, or that the outcome is unknown. STK_TIMER_RES_OK is 0: a check like if(stk_timer_start(...)) means "failed", compare with STK_TIMER_RES_OK explicitly.
The control functions are asynchronous: STK_TIMER_RES_OK means the command was accepted into the command queue, it is executed later by the tick task and its outcome is not reported. The timer state checks (ACTIVE / INACTIVE / NOT_PERIODIC) are advisory: they are evaluated from the state applied by the tick task so far. The synchronous functions (stk_timer_start_sync() and the others) report the exact outcome instead.
Enumerator
STK_TIMER_RES_CANCELLED 

The wait for a free command queue slot was cancelled, nothing is queued.

STK_TIMER_RES_INVALID_PARAM 

An argument is out of range (e.g. zero period for stk_timer_set_period()).

STK_TIMER_RES_QUEUE_FULL 

Command queue is full and the caller can not wait (ISR, kernel not started, polled mode, tick task).

STK_TIMER_RES_NOT_READY 

Host is not initialized (or its initialization failed), or it has been shut down.

STK_TIMER_RES_FAIL 

Unspecified failure.

STK_TIMER_RES_OK 

The command was accepted into the command queue.

STK_TIMER_RES_ACTIVE 

The timer is active, but the command requires it to be inactive.

STK_TIMER_RES_INACTIVE 

The timer is not active, but the command requires it to be active.

STK_TIMER_RES_NOT_PERIODIC 

The timer is not periodic, but the command requires it to be.

STK_TIMER_RES_QUEUED 

Synchronous API only: the calling context can not wait, the command was queued asynchronously, its outcome is unknown.

Definition at line 148 of file stk_c_time.h.

148 {
153 STK_TIMER_RES_FAIL = -1,
154 STK_TIMER_RES_OK = 0,
stk_timer_result_t
Outcome of a timer or host command, mirrors stk::time::TimerHost::EResult.
Definition stk_c_time.h:148
@ STK_TIMER_RES_CANCELLED
The wait for a free command queue slot was cancelled, nothing is queued.
Definition stk_c_time.h:149
@ STK_TIMER_RES_NOT_PERIODIC
The timer is not periodic, but the command requires it to be.
Definition stk_c_time.h:157
@ STK_TIMER_RES_QUEUED
Synchronous API only: the calling context can not wait, the command was queued asynchronously,...
Definition stk_c_time.h:158
@ STK_TIMER_RES_NOT_READY
Host is not initialized (or its initialization failed), or it has been shut down.
Definition stk_c_time.h:152
@ STK_TIMER_RES_INVALID_PARAM
An argument is out of range (e.g. zero period for stk_timer_set_period()).
Definition stk_c_time.h:150
@ STK_TIMER_RES_QUEUE_FULL
Command queue is full and the caller can not wait (ISR, kernel not started, polled mode,...
Definition stk_c_time.h:151
@ STK_TIMER_RES_FAIL
Unspecified failure.
Definition stk_c_time.h:153
@ STK_TIMER_RES_OK
The command was accepted into the command queue.
Definition stk_c_time.h:154
@ STK_TIMER_RES_INACTIVE
The timer is not active, but the command requires it to be active.
Definition stk_c_time.h:156
@ STK_TIMER_RES_ACTIVE
The timer is active, but the command requires it to be inactive.
Definition stk_c_time.h:155

Function Documentation

◆ stk_periodic_trigger_get_instance()

stk::time::PeriodicTrigger * stk_periodic_trigger_get_instance ( stk_periodic_trigger_t * trig)

Get the underlying C++ stk::time::PeriodicTrigger object wrapped by a stk_periodic_trigger_t handle.

Parameters
[in]trigTrigger handle obtained via stk_periodic_trigger_create().
Returns
Pointer to the wrapped stk::time::PeriodicTrigger instance. Never NULL for a valid handle.
Note
C++ callers only (guarded by __cplusplus); not part of the C ABI.

Definition at line 548 of file stk_c_time.cpp.

549{
550 STK_ASSERT(trig != nullptr);
551
552 return &trig->handle;
553}
#define STK_ASSERT(e)
Runtime assertion. Halts execution if the expression e evaluates to false.
Definition stk_defs.h:532
PeriodicTrigger handle

References stk_periodic_trigger_t::handle, and STK_ASSERT.

◆ stk_timer_create()

stk_timer_t * stk_timer_create ( stk_timer_mem_t *const membuf,
stk_timer_callback_t callback,
void * user_data )

Construct a timer in the supplied memory buffer.

Parameters
[in]membufPointer to the caller-supplied memory container, must not be NULL.
[in]callbackFunction to call when the timer expires (must not be NULL).
[in]user_dataOpaque pointer forwarded to callback on expiration.
Returns
Timer handle on success, or NULL if membuf is NULL.
Note
The handle is valid until stk_timer_destroy() is called and membuf must stay valid (not reused, not freed) for that time. There is no limit on the number of timers.
The timer is created inactive, start it with stk_timer_start().
Examples
low_power_c/example.c, and timer_c/example.c.

Definition at line 239 of file stk_c_time.cpp.

242{
243 STK_ASSERT(membuf != nullptr);
244 STK_ASSERT(callback != nullptr);
245
246 stk_timer_t *result = nullptr;
247 if ((membuf != nullptr) && (callback != nullptr))
248 {
249 result = ConstructIn<stk_timer_t>(*membuf, callback, user_data);
250 }
251
252 return result;
253}
static T * ConstructIn(Mem &mem, Args &&... args)
Construct object T in-place inside a C memory container.
Definition stk_c.h:2970

References stk::ConstructIn(), and STK_ASSERT.

Referenced by RunExample().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stk_timer_destroy()

void stk_timer_destroy ( stk_timer_t * tmr)

Destroy a timer (calls the C++ destructor in-place).

Parameters
[in]tmrTimer handle. May be NULL (no-op).
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.
The timer memory is owned by the caller and may be reused right after this call. Stop the timer with stk_timer_stop_sync() first: it returns only when the host holds no reference to the timer and no callback of it is running. The asynchronous stk_timer_stop() only queues the request and gives no such guarantee.

Definition at line 255 of file stk_c_time.cpp.

256{
257 if (tmr != nullptr)
258 {
259 // destroying an active timer is a programming error
260 STK_ASSERT(!tmr->IsActive());
261
262 tmr->~stk_timer_t();
263 }
264}
bool IsActive() const
Check whether the timer is currently active.

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

Here is the call graph for this function:

◆ stk_timer_get_deadline()

int64_t stk_timer_get_deadline ( const stk_timer_t * tmr)

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

Parameters
[in]tmrTimer handle.
Returns
Absolute deadline (ticks). Meaningful only when the timer is active.

Definition at line 446 of file stk_c_time.cpp.

447{
448 STK_ASSERT(tmr != nullptr);
449
450 return static_cast<int64_t>(tmr->GetDeadline());
451}
Ticks GetDeadline() const
Get the absolute time in ticks at which the timer will expire.

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

Here is the call graph for this function:

◆ stk_timer_get_instance()

stk::time::Timer * stk_timer_get_instance ( stk_timer_t * tmr)

Get the underlying C++ stk::time::Timer object wrapped by a stk_timer_t handle.

Parameters
[in]tmrTimer handle obtained via stk_timer_create().
Returns
Pointer to the wrapped stk::time::Timer instance. Never NULL for a valid handle.
Note
C++ callers only (guarded by __cplusplus); not part of the C ABI.
Warning
The concrete object is an internal subclass used to bridge to the C callback; do not static_cast or delete it - treat it strictly as a stk::time::Timer base pointer.

Definition at line 541 of file stk_c_time.cpp.

542{
543 STK_ASSERT(tmr != nullptr);
544
545 return tmr;
546}

References STK_ASSERT.

◆ stk_timer_get_period()

uint32_t stk_timer_get_period ( const stk_timer_t * tmr)

Get the timer's reload period.

Parameters
[in]tmrTimer handle.
Returns
Period in ticks, or 0 for a one-shot timer.

Definition at line 439 of file stk_c_time.cpp.

440{
441 STK_ASSERT(tmr != nullptr);
442
443 return tmr->GetPeriod();
444}
uint32_t GetPeriod() const
Get the reload period of the timer.

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

Here is the call graph for this function:

◆ stk_timer_get_remaining_ticks()

uint32_t stk_timer_get_remaining_ticks ( const stk_timer_t * tmr)

Get remaining ticks until next expiration.

Parameters
[in]tmrTimer 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 460 of file stk_c_time.cpp.

461{
462 STK_ASSERT(tmr != nullptr);
463
464 return tmr->GetRemainingTicks();
465}
uint32_t GetRemainingTicks() const
Get remaining ticks until the timer next expires.

References stk::time::Timer::GetRemainingTicks(), 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 * tmr)

Get the tick count at which the timer last expired.

Parameters
[in]tmrTimer handle.
Returns
Expiration timestamp (ticks). Zero if the timer has never fired.

Definition at line 453 of file stk_c_time.cpp.

454{
455 STK_ASSERT(tmr != nullptr);
456
457 return static_cast<int64_t>(tmr->GetTimestamp());
458}
Ticks GetTimestamp() const
Get the tick count at which the timer last expired.

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

Here is the call graph for this function:

◆ stk_timer_is_active()

bool stk_timer_is_active ( const stk_timer_t * tmr)

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

Parameters
[in]tmrTimer handle.
Returns
true if the timer is active.
Note
Advisory - may change immediately after the call.

Definition at line 432 of file stk_c_time.cpp.

433{
434 STK_ASSERT(tmr != nullptr);
435
436 return tmr->IsActive();
437}

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

Here is the call graph for this function:

◆ stk_timer_reset()

stk_timer_result_t stk_timer_reset ( stk_timerhost_t * host,
stk_timer_t * tmr )

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

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle. Must be active and periodic (period != 0).
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_INACTIVE, STK_TIMER_RES_NOT_PERIODIC, STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...

Definition at line 295 of file stk_c_time.cpp.

296{
297 STK_ASSERT(host != nullptr);
298 STK_ASSERT(tmr != nullptr);
299
300 return ToCTimerResult(host->handle.Reset(*tmr));
301}
EResult Reset(Timer &tmr)
Reset periodic timer's deadline.
TimerHost handle

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

Here is the call graph for this function:

◆ stk_timer_restart()

stk_timer_result_t stk_timer_restart ( stk_timerhost_t * host,
stk_timer_t * tmr,
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]hostTimerHost managing the timer.
[in]tmrTimer handle (active or inactive).
[in]delayInitial delay in ticks before the first expiration.
[in]periodReload period in ticks (0 = one-shot).
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...

Definition at line 303 of file stk_c_time.cpp.

304{
305 STK_ASSERT(host != nullptr);
306 STK_ASSERT(tmr != nullptr);
307
308 // refresh host association before timer can fire
309 tmr->SetHostHandle(host);
310
311 return ToCTimerResult(host->handle.Restart(*tmr, delay, period));
312}
EResult Restart(Timer &tmr, uint32_t delay, uint32_t period=0)
Atomically stop and re-start timer.
void SetHostHandle(stk_timerhost_t *host_handle)

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

Here is the call graph for this function:

◆ stk_timer_set_period()

stk_timer_result_t stk_timer_set_period ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t period_ticks )

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]hostTimerHost managing the timer.
[in]tmrTimer handle. Must be active and periodic.
[in]period_ticksNew reload period in ticks. Must be non-zero.
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_INVALID_PARAM, STK_TIMER_RES_INACTIVE, STK_TIMER_RES_NOT_PERIODIC, STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...

Definition at line 325 of file stk_c_time.cpp.

326{
327 STK_ASSERT(host != nullptr);
328 STK_ASSERT(tmr != nullptr);
329
330 return ToCTimerResult(host->handle.SetPeriod(*tmr, period_ticks));
331}
EResult SetPeriod(Timer &tmr, uint32_t period)
Change the period of a running periodic timer without affecting its current deadline.

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

Here is the call graph for this function:

◆ stk_timer_start()

stk_timer_result_t stk_timer_start ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t delay,
uint32_t period )

Start a timer.

Parameters
[in]hostTimerHost that will manage this timer.
[in]tmrTimer handle. Must not already be active.
[in]delayInitial delay in ticks before the first expiration.
[in]periodReload period in ticks. Pass 0 for a one-shot timer.
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_ACTIVE, STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...
Examples
low_power_c/example.c, and timer_c/example.c.

Definition at line 273 of file stk_c_time.cpp.

277{
278 STK_ASSERT(host != nullptr);
279 STK_ASSERT(tmr != nullptr);
280
281 // refresh host association before timer can fire
282 tmr->SetHostHandle(host);
283
284 return ToCTimerResult(host->handle.Start(*tmr, delay, period));
285}
EResult Start(Timer &tmr, uint32_t delay, uint32_t period=0)
Start timer.

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

Referenced by RunExample().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stk_timer_start_or_reset()

stk_timer_result_t stk_timer_start_or_reset ( stk_timerhost_t * host,
stk_timer_t * tmr,
uint32_t delay,
uint32_t period_ticks )

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

Collapses the common pattern:

else stk_timer_start(host, t, delay, period);
stk_timer_result_t stk_timer_start(stk_timerhost_t *host, stk_timer_t *tmr, uint32_t delay, uint32_t period)
Start a timer.
bool stk_timer_is_active(const stk_timer_t *tmr)
Check whether a timer is currently active (started and not yet expired/stopped).
stk_timer_result_t stk_timer_reset(stk_timerhost_t *host, stk_timer_t *tmr)
Reset a periodic timer's deadline (re-arm from now).

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

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle (active or inactive).
[in]delayInitial delay in ticks (used only when starting).
[in]period_ticksReload period in ticks (used only when starting, 0 = one-shot).
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...

Definition at line 314 of file stk_c_time.cpp.

315{
316 STK_ASSERT(host != nullptr);
317 STK_ASSERT(tmr != nullptr);
318
319 // refresh host association (harmless if timer is already active on host)
320 tmr->SetHostHandle(host);
321
322 return ToCTimerResult(host->handle.StartOrReset(*tmr, delay, period_ticks));
323}
EResult StartOrReset(Timer &tmr, uint32_t delay, uint32_t period=0)
Start timer if inactive, or reset its deadline if already active and periodic.

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

Here is the call graph for this function:

◆ stk_timer_stop()

stk_timer_result_t stk_timer_stop ( stk_timerhost_t * host,
stk_timer_t * tmr )

Stop a running timer.

Parameters
[in]hostTimerHost managing the timer.
[in]tmrTimer handle. Must be currently active.
Returns
STK_TIMER_RES_OK if the command was accepted, otherwise the reason: STK_TIMER_RES_INACTIVE, STK_TIMER_RES_NOT_READY, STK_TIMER_RES_QUEUE_FULL, ...

Definition at line 287 of file stk_c_time.cpp.

288{
289 STK_ASSERT(host != nullptr);
290 STK_ASSERT(tmr != nullptr);
291
292 return ToCTimerResult(host->handle.Stop(*tmr));
293}
EResult Stop(Timer &tmr)
Stop running timer.

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

Here is the call graph for this function:

◆ stk_timerhost_config_init()

void stk_timerhost_config_init ( stk_timerhost_config_t * cfg)

Fill a configuration with defaults (default weights, internal stack buffers).

Parameters
[out]cfgConfiguration to initialize.

Definition at line 143 of file stk_c_time.cpp.

144{
145 STK_ASSERT(cfg != nullptr);
146
147 cfg->tick_weight = static_cast<stk_weight_t>(DEFAULT_WEIGHT);
148 cfg->handler_weight = static_cast<stk_weight_t>(DEFAULT_WEIGHT);
149 cfg->tick_stack = nullptr;
150 cfg->tick_stack_size = 0U;
151 cfg->handler_stack_size = 0U;
152
153 for (size_t i = 0U; i < STK_C_TIMER_THREADS_COUNT; ++i)
154 {
155 cfg->handler_stack[i] = nullptr;
156 }
157}
int32_t stk_weight_t
Task weight value.
Definition stk_c.h:184
#define STK_C_TIMER_THREADS_COUNT
Number of handler tasks serving expired timers in task mode (default: 1). Sizes stk_timerhost_config_...
Definition stk_c_time.h:91
static constexpr Weight DEFAULT_WEIGHT
Weight value: default weight of value (1) (see SwitchStrategySmoothWeightedRoundRobin).
Definition stk_common.h:290
stk_word_t * tick_stack
Stack of the tick task, or NULL for the internal buffer (default).
Definition stk_c_time.h:109
stk_weight_t tick_weight
Weight of the tick task (default: kernel default weight).
Definition stk_c_time.h:107
stk_word_t * handler_stack[(1U)]
Stack of each handler task, a NULL entry selects the internal buffer (default).
Definition stk_c_time.h:111
stk_weight_t handler_weight
Weight of every handler task (default: kernel default weight).
Definition stk_c_time.h:108
size_t tick_stack_size
Size of tick_stack in stk_word_t elements, ignored if tick_stack is NULL.
Definition stk_c_time.h:110
size_t handler_stack_size
Size of every non-NULL handler_stack entry in stk_word_t elements.
Definition stk_c_time.h:112

References stk::DEFAULT_WEIGHT, stk_timerhost_config_t::handler_stack, stk_timerhost_config_t::handler_stack_size, stk_timerhost_config_t::handler_weight, STK_ASSERT, STK_C_TIMER_THREADS_COUNT, stk_timerhost_config_t::tick_stack, stk_timerhost_config_t::tick_stack_size, and stk_timerhost_config_t::tick_weight.

◆ 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_nrCPU 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.
Examples
low_power_c/example.c, and timer_c/example.c.

Definition at line 120 of file stk_c_time.cpp.

121{
122 stk_timerhost_t *result = nullptr;
123
124 if (core_nr < STK_C_CPU_COUNT)
125 {
126 result = &s_TimerHosts[core_nr];
127 }
128
129 return result;
130}
#define STK_C_CPU_COUNT
Number of kernel instances / CPU cores supported (default: 1).
Definition stk_c.h:89

References STK_C_CPU_COUNT.

Referenced by RunExample().

Here is the caller graph for this function:

◆ stk_timerhost_get_instance()

stk::time::TimerHost * stk_timerhost_get_instance ( stk_timerhost_t * host)

Get the underlying C++ stk::time::TimerHost object wrapped by a stk_timerhost_t handle.

Parameters
[in]hostTimerHost handle obtained via stk_timerhost_get().
Returns
Pointer to the wrapped stk::time::TimerHost instance. Never NULL for a valid handle.
Note
C++ callers only (guarded by __cplusplus); not part of the C ABI.

Definition at line 534 of file stk_c_time.cpp.

535{
536 STK_ASSERT(host != nullptr);
537
538 return &host->handle;
539}

References stk_timerhost_t::handle, and STK_ASSERT.

◆ 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]hostTimerHost handle.
Returns
Advisory active timer count (may change immediately after the call).

Definition at line 221 of file stk_c_time.cpp.

222{
223 STK_ASSERT(host != nullptr);
224
225 return host->handle.GetSize();
226}
size_t GetSize() const
Return number of currently active timers.

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]hostTimerHost handle.
Returns
Tick count (may be one tick-task wake cycle stale).

Definition at line 228 of file stk_c_time.cpp.

229{
230 STK_ASSERT(host != nullptr);
231
232 return static_cast<int64_t>(host->handle.GetTimeNow());
233}
Ticks GetTimeNow() const
Get current time.

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]hostTimerHost handle obtained via stk_timerhost_get().
[in]kernelKernel instance the timer tasks will be added to.
[in]privilegedIf 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.
Examples
low_power_c/example.c, and timer_c/example.c.

Definition at line 132 of file stk_c_time.cpp.

135{
136 STK_ASSERT(host != nullptr);
137 STK_ASSERT(kernel != nullptr);
138
140 (privileged ? ACCESS_PRIVILEGED : ACCESS_USER));
141}
@ ACCESS_USER
Unprivileged access mode (access to some hardware is restricted, see CPU manual for details)....
Definition stk_common.h:37
@ ACCESS_PRIVILEGED
Privileged access mode (access to hardware is fully unrestricted).
Definition stk_common.h:38
void InitializeTimerHost(stk_kernel_t *kernel, stk::time::TimerHost *th, EAccessMode amode)
Definition stk_c.cpp:93

References stk::ACCESS_PRIVILEGED, stk::ACCESS_USER, stk_timerhost_t::handle, stk::interop_c_helper::InitializeTimerHost(), and STK_ASSERT.

Referenced by RunExample().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ stk_timerhost_init_ex()

stk_add_result_t stk_timerhost_init_ex ( stk_timerhost_t * host,
stk_kernel_t * kernel,
bool privileged,
const stk_timerhost_config_t * cfg )

Initialize the TimerHost in task mode with explicit weights / stacks and report failures.

Same as stk_timerhost_init() but applies cfg and returns the result of adding the internal tasks to the kernel.

Parameters
[in]hostTimerHost handle obtained via stk_timerhost_get().
[in]kernelKernel instance the timer tasks will be added to.
[in]privilegedIf true the handler tasks run in privileged mode, otherwise in user mode (the tick task always runs in user mode).
[in]cfgWeights and stacks, or NULL for defaults (equivalent to stk_timerhost_config_init()).
Returns
STK_ADD_OK on success, otherwise the first failure reported by the kernel, e.g. STK_ADD_FAIL_POOL_FULL (no free task slots), STK_ADD_FAIL_DUPLICATE (shared stack), STK_ADD_FAIL_INVALID (e.g. HRT kernel: use stk_timerhost_init_polled() there).
Note
On failure the host is unusable; tasks added before the failure stay registered with the kernel.
The host occupies 1 + STK_C_TIMER_THREADS_COUNT kernel task slots.
See also
stk_add_result_t, stk_timerhost_config_t

Definition at line 159 of file stk_c_time.cpp.

163{
164 // C result enum must stay in sync with its C++ counterpart (values are cast directly)
165 STK_STATIC_ASSERT_DESC(static_cast<int32_t>(STK_ADD_FAIL_INVALID) == static_cast<int32_t>(stk::ADD_FAIL_INVALID), "stk_add_result_t mismatch");
166 STK_STATIC_ASSERT_DESC(static_cast<int32_t>(STK_ADD_FAIL_DUPLICATE) == static_cast<int32_t>(stk::ADD_FAIL_DUPLICATE), "stk_add_result_t mismatch");
167 STK_STATIC_ASSERT_DESC(static_cast<int32_t>(STK_ADD_FAIL_POOL_FULL) == static_cast<int32_t>(stk::ADD_FAIL_POOL_FULL), "stk_add_result_t mismatch");
168 STK_STATIC_ASSERT_DESC(static_cast<int32_t>(STK_ADD_OK) == static_cast<int32_t>(stk::ADD_OK), "stk_add_result_t mismatch");
169
170 STK_ASSERT(host != nullptr);
171 STK_ASSERT(kernel != nullptr);
172
173 TimerHost::Config tcfg; // defaults
174
175 if (cfg != nullptr)
176 {
177 tcfg.tick_weight = static_cast<Weight>(cfg->tick_weight);
178 tcfg.handler_weight = static_cast<Weight>(cfg->handler_weight);
179 tcfg.tick_stack = cfg->tick_stack;
182
183 for (size_t i = 0U; i < STK_C_TIMER_THREADS_COUNT; ++i)
184 {
185 tcfg.handler_stack[i] = cfg->handler_stack[i];
186 }
187 }
188
189 return static_cast<stk_add_result_t>(interop_c_helper::InitializeTimerHostEx(kernel, &host->handle,
190 (privileged ? ACCESS_PRIVILEGED : ACCESS_USER), tcfg));
191}
#define STK_STATIC_ASSERT_DESC(X, DESC)
Compile-time assertion with a custom error description. Produces a compilation error if X is false.
Definition stk_defs.h:548
stk_add_result_t
Result of stk_kernel_add_task() and stk_kernel_add_task_hrt().
Definition stk_c.h:220
@ STK_ADD_FAIL_POOL_FULL
No free kernel slot left. In a dynamic kernel retry later, once a task has exited.
Definition stk_c.h:223
@ STK_ADD_OK
Task was added.
Definition stk_c.h:224
@ STK_ADD_FAIL_INVALID
Invalid call: task is NULL, kernel is not initialized, adding is not allowed in the current kernel mo...
Definition stk_c.h:221
@ STK_ADD_FAIL_DUPLICATE
The task (or its stack) is already added to the kernel. Application design failure.
Definition stk_c.h:222
@ ADD_FAIL_POOL_FULL
No free kernel slot left (TASKS_MAX reached). In KERNEL_DYNAMIC mode retry later, once a task has exi...
Definition stk_common.h:152
@ ADD_FAIL_INVALID
Invalid call: task is nullptr, kernel is not initialized, or adding is not allowed in the current ker...
Definition stk_common.h:150
@ ADD_OK
Task was added.
Definition stk_common.h:153
@ ADD_FAIL_DUPLICATE
The task (or its stack) is already added to the kernel. Application design failure.
Definition stk_common.h:151
int32_t Weight
Weight value (aka priority).
Definition stk_common.h:236
EAddResult InitializeTimerHostEx(stk_kernel_t *kernel, stk::time::TimerHost *th, EAccessMode amode, const stk::time::TimerHost::Config &cfg)
Definition stk_c.cpp:98
Optional configuration of the timer tasks, see Initialize().
Weight handler_weight
Weight of every handler task (default: DEFAULT_WEIGHT).
size_t handler_stack_size
Size of every non-null handler_stack entry in elements of Word (>= STK_STACK_SIZE_MIN).
size_t tick_stack_size
Size of tick_stack in elements of Word (>= STK_STACK_SIZE_MIN), ignored if tick_stack is nullptr.
Word * tick_stack
Stack of the tick task, or nullptr to use the internal buffer (default).
Weight tick_weight
Weight of the tick task (default: DEFAULT_WEIGHT).
Word * handler_stack[1U]
Stack of each handler task, a nullptr entry selects the internal buffer (default).

References stk::ACCESS_PRIVILEGED, stk::ACCESS_USER, stk::ADD_FAIL_DUPLICATE, stk::ADD_FAIL_INVALID, stk::ADD_FAIL_POOL_FULL, stk::ADD_OK, stk_timerhost_t::handle, stk::time::TimerHost::Config::handler_stack, stk_timerhost_config_t::handler_stack, stk::time::TimerHost::Config::handler_stack_size, stk_timerhost_config_t::handler_stack_size, stk::time::TimerHost::Config::handler_weight, stk_timerhost_config_t::handler_weight, stk::interop_c_helper::InitializeTimerHostEx(), STK_ADD_FAIL_DUPLICATE, STK_ADD_FAIL_INVALID, STK_ADD_FAIL_POOL_FULL, STK_ADD_OK, STK_ASSERT, STK_C_TIMER_THREADS_COUNT, STK_STATIC_ASSERT_DESC, stk::time::TimerHost::Config::tick_stack, stk_timerhost_config_t::tick_stack, stk::time::TimerHost::Config::tick_stack_size, stk_timerhost_config_t::tick_stack_size, stk::time::TimerHost::Config::tick_weight, and stk_timerhost_config_t::tick_weight.

Here is the call graph for this function:

◆ stk_timerhost_init_polled()

void stk_timerhost_init_polled ( stk_timerhost_t * host)

Initialize the TimerHost in polled mode (no kernel tasks are created).

The application drives the host by calling stk_timerhost_process() periodically; expired timer callbacks run inline from that call. This is the mode to use with an HRT kernel, where Initialize/stk_timerhost_init() is rejected.

Parameters
[in]hostTimerHost handle.
Note
Mutually exclusive with stk_timerhost_init() / stk_timerhost_init_ex(), call one of them before any other timer API. Cannot fail, needs no kernel, task slots, weights or stacks.

Definition at line 193 of file stk_c_time.cpp.

194{
195 STK_ASSERT(host != nullptr);
196
197 host->handle.InitializePolled();
198}
void InitializePolled()
Initialize timer host instance in polled mode (no kernel tasks are created).

References stk_timerhost_t::handle, stk::time::TimerHost::InitializePolled(), 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]hostTimerHost handle.
Returns
Advisory empty flag (may change immediately after the call).

Definition at line 214 of file stk_c_time.cpp.

215{
216 STK_ASSERT(host != nullptr);
217
218 return host->handle.IsEmpty();
219}
bool IsEmpty() const
Return true if no timers are currently active.

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

Here is the call graph for this function:

◆ stk_timerhost_process()

stk_timeout_t stk_timerhost_process ( stk_timerhost_t * host)

Run the host once (polled mode only): execute pending commands, evaluate deadlines and invoke the callback of every expired timer inline.

Parameters
[in]hostTimerHost handle initialized with stk_timerhost_init_polled().
Returns
Ticks until the earliest active deadline: STK_NO_WAIT if a timer is already overdue (call again without delay), STK_WAIT_INFINITE if no timer is active.
Note
Never blocks. Call from a single context only, not concurrently and not from a timer callback. stk_timer_start() and the other control functions stay callable from any task and take effect at the next call.
A timer fires on the first call at or after its deadline, so the calling period is the timer resolution. Callback execution time counts against the caller (e.g. the WCET of an HRT job).
Warning
Only valid after stk_timerhost_init_polled().

Definition at line 200 of file stk_c_time.cpp.

201{
202 STK_ASSERT(host != nullptr);
203
204 return static_cast<stk_timeout_t>(host->handle.Process());
205}
int32_t stk_timeout_t
Timeout value.
Definition stk_c.h:175
Timeout Process()
Run the host once (polled mode only): execute pending commands, evaluate deadlines and invoke OnExpir...

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

Here is the call graph for this function:

◆ stk_timerhost_shutdown()

stk_timer_result_t stk_timerhost_shutdown ( stk_timerhost_t * host)

Gracefully shut down the TimerHost.

Parameters
[in]hostTimerHost handle.
Returns
STK_TIMER_RES_OK if the request was accepted, otherwise the error, e.g. STK_TIMER_RES_QUEUE_FULL or STK_TIMER_RES_NOT_READY (not initialized or already shut down).
Note
All active timers are stopped. Task mode: after shutdown the host must not be used until it is initialized again. Polled mode: the host stays usable.
Examples
timer_c/example.c.

Definition at line 207 of file stk_c_time.cpp.

208{
209 STK_ASSERT(host != nullptr);
210
211 return ToCTimerResult(host->handle.Shutdown());
212}
EResult Shutdown()
Shutdown host instance. All timers are stopped and removed from the host.

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

Referenced by on_shutdown_timer_expired().

Here is the call graph for this function:
Here is the caller graph for this function: