ChibiOS/RT  3.1.5
Time and Virtual Timers
Collaboration diagram for Time and Virtual Timers:

Detailed Description

Time and Virtual Timers related APIs and services.

Special time constants

#define TIME_IMMEDIATE   ((systime_t)0)
 Zero time specification for some functions with a timeout specification. More...
 
#define TIME_INFINITE   ((systime_t)-1)
 Infinite time specification for all functions with a timeout specification. More...
 

Time conversion utilities

#define S2ST(sec)   ((systime_t)((uint32_t)(sec) * (uint32_t)CH_CFG_ST_FREQUENCY))
 Seconds to system ticks. More...
 
#define MS2ST(msec)
 Milliseconds to system ticks. More...
 
#define US2ST(usec)
 Microseconds to system ticks. More...
 
#define ST2S(n)   (((n) + CH_CFG_ST_FREQUENCY - 1UL) / CH_CFG_ST_FREQUENCY)
 System ticks to seconds. More...
 
#define ST2MS(n)
 System ticks to milliseconds. More...
 
#define ST2US(n)
 System ticks to microseconds. More...
 

Functions

void _vt_init (void)
 Virtual Timers initialization. More...
 
void chVTDoSetI (virtual_timer_t *vtp, systime_t delay, vtfunc_t vtfunc, void *par)
 Enables a virtual timer. More...
 
void chVTDoResetI (virtual_timer_t *vtp)
 Disables a Virtual Timer. More...
 
static void chVTObjectInit (virtual_timer_t *vtp)
 Initializes a virtual_timer_t object. More...
 
static systime_t chVTGetSystemTimeX (void)
 Current system time. More...
 
static systime_t chVTGetSystemTime (void)
 Current system time. More...
 
static systime_t chVTTimeElapsedSinceX (systime_t start)
 Returns the elapsed time since the specified start time. More...
 
static bool chVTIsTimeWithinX (systime_t time, systime_t start, systime_t end)
 Checks if the specified time is within the specified time window. More...
 
static bool chVTIsSystemTimeWithinX (systime_t start, systime_t end)
 Checks if the current system time is within the specified time window. More...
 
static bool chVTIsSystemTimeWithin (systime_t start, systime_t end)
 Checks if the current system time is within the specified time window. More...
 
static bool chVTGetTimersStateI (systime_t *timep)
 Returns the time interval until the next timer event. More...
 
static bool chVTIsArmedI (virtual_timer_t *vtp)
 Returns true if the specified timer is armed. More...
 
static bool chVTIsArmed (virtual_timer_t *vtp)
 Returns true if the specified timer is armed. More...
 
static void chVTResetI (virtual_timer_t *vtp)
 Disables a Virtual Timer. More...
 
static void chVTReset (virtual_timer_t *vtp)
 Disables a Virtual Timer. More...
 
static void chVTSetI (virtual_timer_t *vtp, systime_t delay, vtfunc_t vtfunc, void *par)
 Enables a virtual timer. More...
 
static void chVTSet (virtual_timer_t *vtp, systime_t delay, vtfunc_t vtfunc, void *par)
 Enables a virtual timer. More...
 
static void chVTDoTickI (void)
 Virtual timers ticker. More...
 

Macro Definition Documentation

#define TIME_IMMEDIATE   ((systime_t)0)

Zero time specification for some functions with a timeout specification.

Note
Not all functions accept TIME_IMMEDIATE as timeout parameter, see the specific function documentation.

Definition at line 45 of file chvt.h.

Referenced by chCondWaitTimeoutS(), chEvtWaitAllTimeout(), chEvtWaitAnyTimeout(), chEvtWaitOneTimeout(), chSemWaitTimeoutS(), chThdEnqueueTimeoutS(), chThdSleepS(), chThdSuspendTimeoutS(), and chVTDoSetI().

#define TIME_INFINITE   ((systime_t)-1)

Infinite time specification for all functions with a timeout specification.

Note
Not all functions accept TIME_INFINITE as timeout parameter, see the specific function documentation.

Definition at line 53 of file chvt.h.

Referenced by chIQGet(), chOQPut(), and chSchGoSleepTimeoutS().

#define S2ST (   sec)    ((systime_t)((uint32_t)(sec) * (uint32_t)CH_CFG_ST_FREQUENCY))

Seconds to system ticks.

Converts from seconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Parameters
[in]secnumber of seconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 107 of file chvt.h.

#define MS2ST (   msec)
Value:
((systime_t)(((((uint32_t)(msec)) * \
((uint32_t)CH_CFG_ST_FREQUENCY)) + 999UL) / 1000UL))
uint32_t systime_t
Type of system time.
Definition: chsystypes.h:51
#define CH_CFG_ST_FREQUENCY
System tick frequency.
Definition: chconf.h:49

Milliseconds to system ticks.

Converts from milliseconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Parameters
[in]msecnumber of milliseconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 120 of file chvt.h.

Referenced by test_start_timer().

#define US2ST (   usec)
Value:
((systime_t)(((((uint32_t)(usec)) * \
((uint32_t)CH_CFG_ST_FREQUENCY)) + 999999UL) / 1000000UL))
uint32_t systime_t
Type of system time.
Definition: chsystypes.h:51
#define CH_CFG_ST_FREQUENCY
System tick frequency.
Definition: chconf.h:49

Microseconds to system ticks.

Converts from microseconds to system ticks number.

Note
The result is rounded upward to the next tick boundary.
Parameters
[in]usecnumber of microseconds
Returns
The number of ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 134 of file chvt.h.

#define ST2S (   n)    (((n) + CH_CFG_ST_FREQUENCY - 1UL) / CH_CFG_ST_FREQUENCY)

System ticks to seconds.

Converts from system ticks number to seconds.

Note
The result is rounded up to the next second boundary.
Parameters
[in]nnumber of system ticks
Returns
The number of seconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 148 of file chvt.h.

#define ST2MS (   n)
Value:
(((n) * 1000UL + CH_CFG_ST_FREQUENCY - 1UL) / \
#define CH_CFG_ST_FREQUENCY
System tick frequency.
Definition: chconf.h:49

System ticks to milliseconds.

Converts from system ticks number to milliseconds.

Note
The result is rounded up to the next millisecond boundary.
Parameters
[in]nnumber of system ticks
Returns
The number of milliseconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 160 of file chvt.h.

#define ST2US (   n)
Value:
(((n) * 1000000UL + CH_CFG_ST_FREQUENCY - 1UL) / \
#define CH_CFG_ST_FREQUENCY
System tick frequency.
Definition: chconf.h:49

System ticks to microseconds.

Converts from system ticks number to microseconds.

Note
The result is rounded up to the next microsecond boundary.
Parameters
[in]nnumber of system ticks
Returns
The number of microseconds.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 173 of file chvt.h.

Function Documentation

void _vt_init ( void  )

Virtual Timers initialization.

Note
Internal use only.
Function Class:
Not an API, this function is for internal use only.

Definition at line 61 of file chvt.c.

References ch, ch_virtual_timers_list::vt_delta, ch_virtual_timers_list::vt_lasttime, ch_virtual_timers_list::vt_next, ch_virtual_timers_list::vt_prev, ch_virtual_timers_list::vt_systime, and ch_system::vtlist.

Referenced by chSysInit().

void chVTDoSetI ( virtual_timer_t vtp,
systime_t  delay,
vtfunc_t  vtfunc,
void *  par 
)

Enables a virtual timer.

The timer is enabled and programmed to trigger after the delay specified as parameter.

Precondition
The timer must not be already armed before calling this function.
Note
The callback function is invoked from interrupt context.
Parameters
[out]vtpthe virtual_timer_t structure pointer
[in]delaythe number of ticks before the operation timeouts, the special values are handled as follow:
  • TIME_INFINITE is allowed but interpreted as a normal time specification.
  • TIME_IMMEDIATE this value is not allowed.
[in]vtfuncthe timer callback function. After invoking the callback the timer is disabled and the structure can be disposed or reused.
[in]para parameter that will be passed to the callback function
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 95 of file chvt.c.

References ch, CH_CFG_ST_TIMEDELTA, chDbgCheck, chDbgCheckClassI(), chVTGetSystemTimeX(), TIME_IMMEDIATE, ch_virtual_timer::vt_delta, ch_virtual_timers_list::vt_delta, ch_virtual_timer::vt_func, ch_virtual_timers_list::vt_lasttime, ch_virtual_timer::vt_next, ch_virtual_timers_list::vt_next, ch_virtual_timer::vt_par, ch_virtual_timer::vt_prev, ch_virtual_timers_list::vt_prev, and ch_system::vtlist.

Referenced by chSchGoSleepTimeoutS(), and chVTSetI().

Here is the call graph for this function:

void chVTDoResetI ( virtual_timer_t vtp)

Disables a Virtual Timer.

Precondition
The timer must be in armed state before calling this function.
Parameters
[in]vtpthe virtual_timer_t structure pointer
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 190 of file chvt.c.

References ch, CH_CFG_ST_TIMEDELTA, chDbgAssert, chDbgCheck, chDbgCheckClassI(), chVTGetSystemTimeX(), ch_virtual_timer::vt_delta, ch_virtual_timers_list::vt_delta, ch_virtual_timer::vt_func, ch_virtual_timers_list::vt_lasttime, ch_virtual_timer::vt_next, ch_virtual_timers_list::vt_next, ch_virtual_timer::vt_prev, and ch_system::vtlist.

Referenced by chSchGoSleepTimeoutS(), and chVTResetI().

Here is the call graph for this function:

static void chVTObjectInit ( virtual_timer_t vtp)
inlinestatic

Initializes a virtual_timer_t object.

Note
Initializing a timer object is not strictly required because the function chVTSetI() initializes the object too. This function is only useful if you need to perform a chVTIsArmed() check before calling chVTSetI().
Parameters
[out]vtpthe virtual_timer_t structure pointer
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 210 of file chvt.h.

References ch_virtual_timer::vt_func.

static systime_t chVTGetSystemTimeX ( void  )
inlinestatic

Current system time.

Returns the number of system ticks since the chSysInit() invocation.

Note
The counter can reach its maximum and then restart from zero.
This function can be called from any context but its atomicity is not guaranteed on architectures whose word size is less than systime_t size.
Returns
The system time in ticks.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 228 of file chvt.h.

References ch, ch_virtual_timers_list::vt_systime, and ch_system::vtlist.

Referenced by _dbg_trace(), chThdSleepUntil(), chThdSleepUntilWindowed(), chVTDoResetI(), chVTDoSetI(), chVTDoTickI(), chVTGetSystemTime(), chVTGetTimersStateI(), chVTIsSystemTimeWithinX(), and chVTTimeElapsedSinceX().

static systime_t chVTGetSystemTime ( void  )
inlinestatic

Current system time.

Returns the number of system ticks since the chSysInit() invocation.

Note
The counter can reach its maximum and then restart from zero.
Returns
The system time in ticks.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 247 of file chvt.h.

References chSysLock(), chSysUnlock(), and chVTGetSystemTimeX().

Referenced by chVTIsSystemTimeWithin(), and test_wait_tick().

Here is the call graph for this function:

static systime_t chVTTimeElapsedSinceX ( systime_t  start)
inlinestatic

Returns the elapsed time since the specified start time.

Parameters
[in]startstart time
Returns
The elapsed time.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 265 of file chvt.h.

References chVTGetSystemTimeX().

Here is the call graph for this function:

static bool chVTIsTimeWithinX ( systime_t  time,
systime_t  start,
systime_t  end 
)
inlinestatic

Checks if the specified time is within the specified time window.

Note
When start==end then the function returns always true because the whole time range is specified.
This function can be called from any context.
Parameters
[in]timethe time to be verified
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 284 of file chvt.h.

Referenced by chThdSleepUntilWindowed(), chVTIsSystemTimeWithin(), and chVTIsSystemTimeWithinX().

static bool chVTIsSystemTimeWithinX ( systime_t  start,
systime_t  end 
)
inlinestatic

Checks if the current system time is within the specified time window.

Note
When start==end then the function returns always true because the whole time range is specified.
Parameters
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 304 of file chvt.h.

References chVTGetSystemTimeX(), and chVTIsTimeWithinX().

Here is the call graph for this function:

static bool chVTIsSystemTimeWithin ( systime_t  start,
systime_t  end 
)
inlinestatic

Checks if the current system time is within the specified time window.

Note
When start==end then the function returns always true because the whole time range is specified.
Parameters
[in]startthe start of the time window (inclusive)
[in]endthe end of the time window (non inclusive)
Return values
truecurrent time within the specified time window.
falsecurrent time not within the specified time window.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 322 of file chvt.h.

References chVTGetSystemTime(), and chVTIsTimeWithinX().

Here is the call graph for this function:

static bool chVTGetTimersStateI ( systime_t timep)
inlinestatic

Returns the time interval until the next timer event.

Note
The return value is not perfectly accurate and can report values in excess of CH_CFG_ST_TIMEDELTA ticks.
The interval returned by this function is only meaningful if more timers are not added to the list until the returned time.
Parameters
[out]timeppointer to a variable that will contain the time interval until the next timer elapses. This pointer can be NULL if the information is not required.
Returns
The time, in ticks, until next time event.
Return values
falseif the timers list is empty.
trueif the timers list contains at least one timer.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 343 of file chvt.h.

References ch, CH_CFG_ST_TIMEDELTA, chDbgCheckClassI(), chVTGetSystemTimeX(), ch_virtual_timer::vt_delta, ch_virtual_timers_list::vt_lasttime, ch_virtual_timers_list::vt_next, and ch_system::vtlist.

Here is the call graph for this function:

static bool chVTIsArmedI ( virtual_timer_t vtp)
inlinestatic

Returns true if the specified timer is armed.

Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
Returns
true if the timer is armed.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 373 of file chvt.h.

References chDbgCheckClassI(), and ch_virtual_timer::vt_func.

Referenced by chSchGoSleepTimeoutS(), chVTIsArmed(), and chVTResetI().

Here is the call graph for this function:

static bool chVTIsArmed ( virtual_timer_t vtp)
inlinestatic

Returns true if the specified timer is armed.

Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
Returns
true if the timer is armed.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 390 of file chvt.h.

References chSysLock(), chSysUnlock(), and chVTIsArmedI().

Here is the call graph for this function:

static void chVTResetI ( virtual_timer_t vtp)
inlinestatic

Disables a Virtual Timer.

Note
The timer is first checked and disabled only if armed.
Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 410 of file chvt.h.

References chVTDoResetI(), and chVTIsArmedI().

Referenced by chVTReset(), and chVTSetI().

Here is the call graph for this function:

static void chVTReset ( virtual_timer_t vtp)
inlinestatic

Disables a Virtual Timer.

Note
The timer is first checked and disabled only if armed.
Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 427 of file chvt.h.

References chSysLock(), chSysUnlock(), and chVTResetI().

Here is the call graph for this function:

static void chVTSetI ( virtual_timer_t vtp,
systime_t  delay,
vtfunc_t  vtfunc,
void *  par 
)
inlinestatic

Enables a virtual timer.

If the virtual timer was already enabled then it is re-enabled using the new parameters.

Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
[in]delaythe number of ticks before the operation timeouts, the special values are handled as follow:
  • TIME_INFINITE is allowed but interpreted as a normal time specification.
  • TIME_IMMEDIATE this value is not allowed.
[in]vtfuncthe timer callback function. After invoking the callback the timer is disabled and the structure can be disposed or reused.
[in]para parameter that will be passed to the callback function
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 456 of file chvt.h.

References chVTDoSetI(), and chVTResetI().

Referenced by chVTSet().

Here is the call graph for this function:

static void chVTSet ( virtual_timer_t vtp,
systime_t  delay,
vtfunc_t  vtfunc,
void *  par 
)
inlinestatic

Enables a virtual timer.

If the virtual timer was already enabled then it is re-enabled using the new parameters.

Precondition
The timer must have been initialized using chVTObjectInit() or chVTDoSetI().
Parameters
[in]vtpthe virtual_timer_t structure pointer
[in]delaythe number of ticks before the operation timeouts, the special values are handled as follow:
  • TIME_INFINITE is allowed but interpreted as a normal time specification.
  • TIME_IMMEDIATE this value is not allowed.
[in]vtfuncthe timer callback function. After invoking the callback the timer is disabled and the structure can be disposed or reused.
[in]para parameter that will be passed to the callback function
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 485 of file chvt.h.

References chSysLock(), chSysUnlock(), and chVTSetI().

Referenced by test_start_timer().

Here is the call graph for this function:

static void chVTDoTickI ( void  )
inlinestatic

Virtual timers ticker.

Note
The system lock is released before entering the callback and re-acquired immediately after. It is callback's responsibility to acquire the lock if needed. This is done in order to reduce interrupts jitter when many timers are in use.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 502 of file chvt.h.

References ch, CH_CFG_ST_TIMEDELTA, chDbgAssert, chDbgCheckClassI(), chSysLockFromISR(), chSysUnlockFromISR(), chVTGetSystemTimeX(), ch_virtual_timer::vt_delta, ch_virtual_timer::vt_func, ch_virtual_timers_list::vt_lasttime, ch_virtual_timer::vt_next, ch_virtual_timers_list::vt_next, ch_virtual_timer::vt_par, ch_virtual_timer::vt_prev, ch_virtual_timers_list::vt_systime, and ch_system::vtlist.

Referenced by chSysTimerHandlerI().

Here is the call graph for this function: