Timer management services.

Collaboration diagram for Timer management services.:

Data Structures
struct	rt_timer_info
	Structure containing timer-information useful to users. More...
Files
file	timer.h
	This file is part of the Xenomai project.
file	timer.c
	This file is part of the Xenomai project.
Typedefs
typedef struct rt_timer_info	RT_TIMER_INFO
	Structure containing timer-information useful to users.
Functions
SRTIME	rt_timer_ns2tsc (SRTIME ns)
	Convert nanoseconds to local CPU clock ticks.
SRTIME	rt_timer_tsc2ns (SRTIME ticks)
	Convert local CPU clock ticks to nanoseconds.
RTIME	rt_timer_tsc (void)
	Return the current TSC value.
RTIME	rt_timer_read (void)
	Return the current system time.
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.
void	rt_timer_spin (RTIME ns)
	Busy wait burning CPU cycles.
int	rt_timer_set_mode (RTIME nstick)
	Set the system clock rate.

---

Detailed Description

Timer-related services allow to control the Xenomai system timer which is used in all timed operations.

---

Typedef Documentation

typedef struct rt_timer_info RT_TIMER_INFO

Structure containing timer-information useful to users.

See also:

rt_timer_inquire()

---

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:

• TM_UNSET is a special value indicating that the system timer is inactive. A call to rt_timer_set_mode() re-activates it.

• TM_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".

Environments:

This service can be called from:

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

Rescheduling: never.

References xntbase_get_time().

SRTIME rt_timer_ns2ticks

(

SRTIME

ns

)

Convert nanoseconds to internal clock ticks.

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

Parameters:

ns	The count of nanoseconds to convert.

Returns:

The corresponding value expressed in internal clock ticks.

Environments:

This service can be called from:

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

Rescheduling: never.

Examples:

cross-link.c, and rtcansend.c.

SRTIME rt_timer_ns2tsc

(

SRTIME

ns

)

Convert nanoseconds to local CPU clock ticks.

Convert a count of nanoseconds to local CPU clock ticks. This routine operates on signed nanosecond values.

Parameters:

ns	The count of nanoseconds to convert.

Returns:

The corresponding value expressed in CPU clock ticks.

Environments:

This service can be called from:

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

Rescheduling: never.

RTIME rt_timer_read

(

void

)

Return the current system time.

Return the current time maintained by the master time base.

Returns:

The current time expressed in clock ticks (see note).

Environments:

This service can be called from:

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

Rescheduling: never.

Note:

The value returned will represent a count of jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

Examples:

cross-link.c, and trivial-periodic.c.

int rt_timer_set_mode

(

RTIME

nstick

)

Set the system clock rate.

This routine switches to periodic timing mode and sets the clock tick rate, or resets the current timing mode to aperiodic/oneshot mode depending on the value of the nstick parameter. Since the native skin automatically sets its time base according to the configured policy and period at load time (see CONFIG_XENO_OPT_NATIVE_PERIOD), calling rt_timer_set_mode() is not required from applications unless the pre-defined mode and period need to be changed dynamically.

This service sets 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 time base period in nanoseconds. If this parameter is equal to the special TM_ONESHOT value, the time base is set to operate in a tick-less fashion (i.e. oneshot mode). Other values are interpreted as the time between two consecutive clock ticks in periodic timing mode (i.e. clock HZ = 1e9 / nstick).

Returns:

0 is returned on success. Otherwise:

• -ENODEV is returned if the underlying architecture does not support the requested periodic timing. Aperiodic/oneshot timing is always supported.

Environments:

This service can be called from:

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

Rescheduling: never.

References xntbase_switch().

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.

Environments:

This service can be called from:

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

Rescheduling: never.

SRTIME rt_timer_ticks2ns

(

SRTIME

ticks

)

Convert internal clock ticks to nanoseconds.

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

Parameters:

ticks

The count of internal clock ticks to convert.

Returns:

The corresponding value expressed in nanoseconds.

Environments:

This service can be called from:

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

Rescheduling: never.

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.

Environments:

This service can be called from:

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

Rescheduling: never.

SRTIME rt_timer_tsc2ns

(

SRTIME

ticks

)

Convert local CPU clock ticks to nanoseconds.

Convert a local CPU clock ticks to nanoseconds. This routine operates on signed tick values.

Parameters:

ticks

The count of local CPU clock ticks to convert.

Returns:

The corresponding value expressed in nanoseconds.

Environments:

This service can be called from:

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

Rescheduling: never.