Timer services.
[Xenomai nucleus.]

Collaboration diagram for Timer services.:

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).


Files

file  timer.h
 
Note:
Copyright (C) 2001,2002,2003 Philippe Gerum <rpm@xenomai.org>.

file  timer.c
 
Note:
Copyright (C) 2001,2002,2003,2007 Philippe Gerum <rpm@xenomai.org>.


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).

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:
timer The address of a valid timer descriptor.
Environments:

This service can be called from:

Rescheduling: never.

void xntimer_freeze ( void   ) 

Freeze all timers (from every time bases).

For internal use only.

This routine deactivates all active timers atomically.

Environments:

This service can be called from:

Rescheduling: never.

xnticks_t xntimer_get_date ( xntimer_t *  timer  )  [inline, static]

Return the absolute expiration date.

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

Parameters:
timer The 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:

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.

xnticks_t xntimer_get_interval ( xntimer_t *  timer  )  [inline, static]

Return the timer interval value.

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

Parameters:
timer The 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:

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:
timer The address of a valid timer descriptor.
now current date (in the monotonic time base)
Returns:
the number of overruns of timer at date now

xnticks_t xntimer_get_timeout ( xntimer_t *  timer  )  [inline, static]

Return the relative expiration date.

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

Parameters:
timer The 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:

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.

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:
timer The 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.
base The descriptor address of the time base the new timer depends on. See xntbase_alloc() for detailed explanations about time bases.
handler The 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:

Rescheduling: never.

void xntimer_start ( xntimer_t *  timer,
xnticks_t  value,
xnticks_t  interval,
xntmode_t  mode 
) [inline, static]

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:
timer The address of a valid timer descriptor.
value The date of the initial timer shot, expressed in clock ticks (see note).
interval The 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.
mode The 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:

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.

int xntimer_stop ( xntimer_t *  timer  )  [inline, static]

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:
timer The address of a valid timer descriptor.
Environments:

This service can be called from:

Rescheduling: never.

Note:
Must be called with nklock held, IRQs off.

void xntimer_tick_aperiodic ( void   ) 

Process a timer tick for the aperiodic master time base.

For internal use only.

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:

Rescheduling: never.

void xntimer_tick_periodic ( xntimer_t *  mtimer  ) 

Process a timer tick for a slave periodic time base.

For internal use only.

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:
mtimer The address of the cascading timer running in the master time base which announced the tick.
Environments:

This service can be called from:

Rescheduling: never.

Note:
Only active timers are inserted into the timer wheel.

Generated on Mon Mar 24 18:02:41 2008 for Xenomai API by  doxygen 1.5.3