Xenomai API  2.6.4
Timer services.
Collaboration diagram for Timer services.:

Files

file  timer.h
file  timer.c

Functions

static int xntimer_start (xntimer_t *timer, xnticks_t value, xnticks_t interval, xntmode_t mode)
 Arm a timer.
static void xntimer_stop (xntimer_t *timer)
 Disarm a timer.
static xnticks_t xntimer_get_date (xntimer_t *timer)
 Return the absolute expiration date.
static xnticks_t xntimer_get_timeout (xntimer_t *timer)
 Return the relative expiration date.
static xnticks_t xntimer_get_interval (xntimer_t *timer)
 Return the timer interval value.
void xntimer_tick_aperiodic (void)
 Process a timer tick for the aperiodic master time base.
void xntimer_tick_periodic (xntimer_t *mtimer)
 Process a timer tick for a slave periodic time base.
void xntimer_init (xntimer_t *timer, xntbase_t *base, void(*handler)(xntimer_t *timer))
 Initialize a timer object.
void xntimer_destroy (xntimer_t *timer)
 Release a timer object.
unsigned long xntimer_get_overruns (xntimer_t *timer, xnticks_t now)
 Get the count of overruns for the last tick.
void xntimer_freeze (void)
 Freeze all timers (from every time bases).

Detailed Description

The Xenomai timer facility always operate the timer hardware in oneshot mode, regardless of the time base in effect. Periodic timing is obtained through a software emulation, using cascading timers.

Depending on the time base used, the timer object stores time values either as count of jiffies (periodic), or as count of CPU ticks (aperiodic).

Function Documentation

void xntimer_destroy ( xntimer_t *  timer)

Release a timer object.

Destroys a timer. After it has been destroyed, all resources associated with the timer have been released. The timer is automatically deactivated before deletion if active on entry.

Parameters
timerThe address of a valid timer descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

References xntimer_stop().

Referenced by rt_alarm_delete(), rtdm_timer_destroy(), xnpod_delete_thread(), and xnpod_shutdown().

void xntimer_freeze ( void  )

Freeze all timers (from every time bases).

This routine deactivates all active timers atomically.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: never.

Referenced by xnpod_disable_timesource().

xnticks_t xntimer_get_date ( xntimer_t *  timer)
inlinestatic

Return the absolute expiration date.

Return the next expiration date of a timer in absolute clock ticks (see note).

Parameters
timerThe address of a valid timer descriptor.
Returns
The expiration date converted to the current time unit. The special value XN_INFINITE is returned if timer is currently inactive.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Note
This service is sensitive to the current operation mode of the associated time base, as defined by the xnpod_init_timebase() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

Referenced by rt_task_inquire().

xnticks_t xntimer_get_interval ( xntimer_t *  timer)
inlinestatic

Return the timer interval value.

Return the timer interval value in clock ticks (see note).

Parameters
timerThe address of a valid timer descriptor.
Returns
The expiration date converted to the current time unit. The special value XN_INFINITE is returned if timer is currently inactive or aperiodic.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Note
This service is sensitive to the current operation mode of the associated time base, as defined by the xnpod_init_timebase() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.
unsigned long xntimer_get_overruns ( xntimer_t *  timer,
xnticks_t  now 
)

Get the count of overruns for the last tick.

This service returns the count of pending overruns for the last tick of a given timer, as measured by the difference between the expected expiry date of the timer and the date now passed as argument.

Parameters
timerThe address of a valid timer descriptor.
nowcurrent date (in the monotonic time base)
Returns
the number of overruns of timer at date now

Referenced by xnpod_wait_thread_period().

xnticks_t xntimer_get_timeout ( xntimer_t *  timer)
inlinestatic

Return the relative expiration date.

Return the next expiration date of a timer in relative clock ticks (see note).

Parameters
timerThe address of a valid timer descriptor.
Returns
The expiration date converted to the current time unit. The special value XN_INFINITE is returned if timer is currently inactive. In oneshot mode, it might happen that the timer has already expired when this service is run (even if the associated handler has not been fired yet); in such a case, 1 is returned.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Note
This service is sensitive to the current operation mode of the associated time base, as defined by the xnpod_init_timebase() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

Referenced by rt_alarm_inquire().

void xntimer_init ( xntimer_t *  timer,
xntbase_t *  base,
void(*)(xntimer_t *timer)  handler 
)

Initialize a timer object.

Creates a timer. When created, a timer is left disarmed; it must be started using xntimer_start() in order to be activated.

Parameters
timerThe address of a timer descriptor the nucleus will use to store the object-specific data. This descriptor must always be valid while the object is active therefore it must be allocated in permanent memory.
baseThe descriptor address of the time base the new timer depends on. See xntbase_alloc() for detailed explanations about time bases.
handlerThe routine to call upon expiration of the timer.

There is no limitation on the number of timers which can be created/active concurrently.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Referenced by rt_alarm_create(), timer_create(), and xnpod_init().

void xntimer_start ( xntimer_t *  timer,
xnticks_t  value,
xnticks_t  interval,
xntmode_t  mode 
)
inlinestatic

Arm a timer.

Activates a timer so that the associated timeout handler will be fired after each expiration time. A timer can be either periodic or single-shot, depending on the reload value passed to this routine. The given timer must have been previously initialized, and will be clocked according to the policy defined by the time base specified in xntimer_init().

Parameters
timerThe address of a valid timer descriptor.
valueThe date of the initial timer shot, expressed in clock ticks (see note).
intervalThe reload value of the timer. It is a periodic interval value to be used for reprogramming the next timer shot, expressed in clock ticks (see note). If interval is equal to XN_INFINITE, the timer will not be reloaded after it has expired.
modeThe timer mode. It can be XN_RELATIVE if value shall be interpreted as a relative date, XN_ABSOLUTE for an absolute date based on the monotonic clock of the related time base (as returned my xntbase_get_jiffies()), or XN_REALTIME if the absolute date is based on the adjustable real-time clock of the time base (as returned by xntbase_get_time().
Returns
0 is returned upon success, or -ETIMEDOUT if an absolute date in the past has been given.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Note
This service is sensitive to the current operation mode of the associated time base, as defined by the xnpod_init_timebase() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.
Must be called with nklock held, IRQs off.

Referenced by rt_alarm_start(), rtdm_timer_start(), timer_settime(), xnpod_enable_timesource(), xnpod_set_thread_periodic(), xnpod_set_thread_tslice(), and xnpod_suspend_thread().

int xntimer_stop ( xntimer_t *  timer)
inlinestatic

Disarm a timer.

This service deactivates a timer previously armed using xntimer_start(). Once disarmed, the timer can be subsequently re-armed using the latter service.

Parameters
timerThe address of a valid timer descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: never.

Note
Must be called with nklock held, IRQs off.

Referenced by rt_alarm_stop(), rtdm_timer_stop(), timer_settime(), xnpod_resume_thread(), xnpod_set_thread_periodic(), xnpod_set_thread_tslice(), and xntimer_destroy().

void xntimer_tick_aperiodic ( void  )

Process a timer tick for the aperiodic master time base.

This routine informs all active timers that the clock has been updated by processing the outstanding timer list. Elapsed timer actions will be fired.

Environments:

This service can be called from:

  • Interrupt service routine, nklock locked, interrupts off

Rescheduling: never.

References xnsched::htimer, xnsched::lflags, and xnsched::status.

Referenced by xntbase_tick().

void xntimer_tick_periodic ( xntimer_t *  mtimer)

Process a timer tick for a slave periodic time base.

The periodic timer tick is cascaded from a software timer managed from the master aperiodic time base; in other words, periodic timing is emulated by software timers running in aperiodic timing mode. There may be several concurrent periodic time bases (albeit a single aperiodic time base - i.e. the master one called "nktbase" - may exist at any point in time).

This routine informs all active timers that the clock has been updated by processing the timer wheel. Elapsed timer actions will be fired.

Parameters
mtimerThe address of the cascading timer running in the master time base which announced the tick.

Environments:

This service can be called from:

  • Interrupt service routine, nklock locked, interrupts off

Rescheduling: never.

Note
Only active timers are inserted into the timer wheel.