Timer management services.
[Native RTAI API.]


Detailed Description

Timer management services.


Files

file  timer.c
 This file is part of the RTAI project.

Functions

SRTIME rt_timer_ns2ticks (SRTIME ns)
 Convert nanoseconds to internal clock ticks.
SRTIME rt_timer_ticks2ns (SRTIME ticks)
 Convert internal clock ticks to nanoseconds.
int rt_timer_inquire (RT_TIMER_INFO *info)
 Inquire about the timer.
RTIME rt_timer_read (void)
 Return the current system time.
RTIME rt_timer_tsc (void)
 Return the current TSC value.
void rt_timer_spin (RTIME ns)
 Busy wait burning CPU cycles.
int rt_timer_start (RTIME nstick)
 Start the system timer.
void rt_timer_stop (void)
 Stop the system timer.


Function Documentation

int rt_timer_inquire RT_TIMER_INFO *  info  ) 
 

Inquire about the timer.

Return various information about the status of the system timer.

Parameters:
info The address of a structure the timer information will be written to.
Returns:
This service always returns 0.
The information block returns the period and the current system date. The period can have the following values:

  • RT_TIMER_UNSET is a special value indicating that the system timer is inactive. A call to rt_timer_start() activates it.

  • RT_TIMER_ONESHOT is a special value indicating that the timer has been set up in oneshot mode.

  • Any other period value indicates that the system timer is currently running in periodic mode; it is a count of nanoseconds representing the period of the timer, i.e. the duration of a periodic tick or "jiffy".

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

SRTIME rt_timer_ns2ticks SRTIME  ns  ) 
 

Convert nanoseconds to internal clock ticks.

Convert a count of nanoseconds to internal clock ticks. This routine opearates on signed nanosecond values.

Parameters:
ns The count of nanoseconds to convert.
Returns:
The corresponding value expressed in internal clock ticks (see note). If the system timer is inactive or operating in oneshot mode, this routine returns ns unmodified.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed as CPU ticks (e.g. TSC value).

RTIME rt_timer_read void   ) 
 

Return the current system time.

Return the current time maintained by the system timer.

Returns:
The current time expressed in clock ticks (see note).
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.

void rt_timer_spin RTIME  ns  ) 
 

Busy wait burning CPU cycles.

Enter a busy waiting loop for a count of nanoseconds. The precision of this service largely depends on the availability of a time stamp counter on the current CPU.

Since this service is usually called with interrupts enabled, the caller might be preempted by other real-time activities, therefore the actual delay might be longer than specified.

Parameters:
ns The time to wait expressed in nanoseconds.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_timer_start RTIME  nstick  ) 
 

Start the system timer.

The real-time kernel needs a time source to provide the time-related services to the RTAI tasks. rt_timer_start() sets the current operation mode of the system timer. On architectures that provide a oneshot-programmable time source, the system timer can operate either in oneshot or periodic mode. In oneshot mode, the underlying hardware will be reprogrammed after each clock tick so that the next one occurs after a (possibly non-constant) specified interval, at the expense of a larger overhead due to hardware programming duties. Periodic mode provides timing services at a lower programming cost when the underlying hardware is a true PIT (and not a simple decrementer), but at the expense of a lower precision since all delays are rounded up to the constant interval value used to program the timer.

This service defines the time unit which will be relevant when specifying time intervals to the services taking timeout or delays as input parameters. In periodic mode, clock ticks will represent periodic jiffies. In oneshot mode, clock ticks will represent nanoseconds.

Parameters:
nstick The timer period in nanoseconds. If this parameter is equal to RT_TIMER_ONESHOT, the underlying hardware timer is set to operate in oneshot-programmable mode. In this mode, timing accuracy is higher - since it is not rounded to a constant time slice - at the expense of a lesser efficicency when many timers are simultaneously active. The oneshot mode gives better results in configuration involving a few tasks requesting timing services over different time scales that cannot be easily expressed as multiples of a single base tick, or would lead to a waste of high frequency periodical ticks.
Returns:
0 is returned on success. Otherwise:

  • -ENOSYS is returned if the underlying architecture does not support the requested oneshot timing.

Context: This routine can be called on behalf of a task or the initialization code.

void rt_timer_stop void   ) 
 

Stop the system timer.

This service stops the system timer previously started by a call to rt_timer_start(). Calling rt_timer_stop() whilst the system timer has not been started leads to a null-effect.

Context: This routine can be called on behalf of a task or the initialization code.

SRTIME rt_timer_ticks2ns SRTIME  ticks  ) 
 

Convert internal clock ticks to nanoseconds.

Convert a count of internal clock ticks to nanoseconds. This routine opearates on signed tick values.

Parameters:
ticks The count of internal clock ticks to convert (see note).
Returns:
The corresponding value expressed in nanoseconds.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed as CPU ticks (e.g. TSC value).

RTIME rt_timer_tsc void   ) 
 

Return the current TSC value.

Return the value of the time stamp counter (TSC) maintained by the CPU of the underlying architecture.

Returns:
The current value of the TSC.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8