Timer services

The Xenomai timer facility depends on a clock source (xnclock) for scheduling the next activation times. More...

Functions
void	xntimer_destroy (struct xntimer *timer)
	Release a timer object. More...
static xnticks_t	xntimer_interval (struct xntimer *timer)
	Return the timer interval value. More...
int	xntimer_start (struct xntimer *timer, xnticks_t value, xnticks_t interval, xntmode_t mode)
	Arm a timer. More...
xnticks_t	xntimer_get_date (struct xntimer *timer)
	Return the absolute expiration date. More...
static void	xntimer_stop (struct xntimer *timer)
	Disarm a timer. More...
static xnticks_t	xntimer_get_timeout (struct xntimer *timer)
	Return the relative expiration date. More...
unsigned long long	xntimer_get_overruns (struct xntimer *timer, struct xnthread *waiter, xnticks_t now)
	Get the count of overruns for the last tick. More...
void	__xntimer_migrate (struct xntimer *timer, struct xnsched *sched)
	Migrate a timer. More...
void	xntimer_init (struct xntimer *timer, struct xnclock *clock, void(*handler)(struct xntimer *timer), struct xnsched *sched, int flags)
	Initialize a timer object. More...

Detailed Description

The Xenomai timer facility depends on a clock source (xnclock) for scheduling the next activation times.

The core provides and depends on a monotonic clock source (nkclock) with nanosecond resolution, driving the platform timer hardware exposed by the interrupt pipeline.

Function Documentation

__xntimer_migrate()

void __xntimer_migrate	(	struct xntimer *	timer,
		struct xnsched *	sched
	)

Migrate a timer.

This call migrates a timer to another cpu. In order to avoid pathological cases, it must be called from the CPU to which timer is currently attached.

Parameters

timer	The address of the timer object to be migrated.
sched	The address of the destination per-CPU scheduler slot.

Tags

unrestricted, atomic-entry

xntimer_destroy()

void xntimer_destroy

(

struct xntimer *

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.

Tags

unrestricted

xntimer_get_date()

xnticks_t xntimer_get_date

(

struct xntimer *

timer

)

Return the absolute expiration date.

Return the next expiration date of a timer as an absolute count of nanoseconds.

Parameters

timer

The address of a valid timer descriptor.

Returns

The expiration date in nanoseconds. The special value XN_INFINITE is returned if timer is currently disabled.

Tags

unrestricted, atomic-entry

xntimer_get_overruns()

unsigned long long xntimer_get_overruns	(	struct xntimer *	timer,
		struct xnthread *	waiter,
		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.
waiter	The thread for which the overrun count is being collected.
now	current date (as xnclock_read_raw(xntimer_clock(timer)))

Returns

the number of overruns of timer at date now

Tags

unrestricted, atomic-entry

xntimer_get_timeout()

xnticks_t xntimer_get_timeout ( struct xntimer *  timer )

inlinestatic

Return the relative expiration date.

This call returns the count of nanoseconds remaining until the timer expires.

Parameters

timer

The address of a valid timer descriptor.

Returns

The count of nanoseconds until expiry. The special value XN_INFINITE is returned if timer is currently disabled. It might happen that the timer expires when this service runs (even if the associated handler has not been fired yet); in such a case, 1 is returned.

Tags

unrestricted, atomic-entry

xntimer_init()

void xntimer_init	(	struct xntimer *	timer,
		struct xnclock *	clock,
		void(*)(struct xntimer *timer)	handler,
		struct xnsched *	sched,
		int	flags
	)

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.
clock	The clock the timer relates to. Xenomai defines a monotonic system clock, with nanosecond resolution, named nkclock. In addition, external clocks driven by other tick sources may be created dynamically if CONFIG_XENO_OPT_EXTCLOCK is defined.
handler	The routine to call upon expiration of the timer.
sched	An optional pointer to the per-CPU scheduler slot the new timer is affine to. If non-NULL, the timer will fire on the CPU sched is bound to, otherwise it will fire either on the current CPU if real-time, or on the first real-time CPU.
flags	A set of flags describing the timer. A set of clock gravity hints can be passed via the flags argument, used for optimizing the built-in heuristics aimed at latency reduction:

• XNTIMER_IGRAVITY, the timer activates a leaf timer handler.
• XNTIMER_KGRAVITY, the timer activates a kernel thread.
• XNTIMER_UGRAVITY, the timer activates a user-space thread.

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

Tags

unrestricted

Referenced by rtdm_timer_init().

xntimer_interval()

xnticks_t xntimer_interval ( struct xntimer *  timer )

inlinestatic

Return the timer interval value.

Return the timer interval value in nanoseconds.

Parameters

timer

The address of a valid timer descriptor.

Returns

The duration of a period in nanoseconds. The special value XN_INFINITE is returned if timer is currently disabled or one shot.

Tags

unrestricted, atomic-entry

xntimer_start()

int xntimer_start	(	struct xntimer *	timer,
		xnticks_t	value,
		xnticks_t	interval,
		xntmode_t	mode
	)

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 one-shot, depending on the reload value passed to this routine. The given timer must have been previously initialized.

A timer is attached to the clock specified in xntimer_init().

Parameters

timer	The address of a valid timer descriptor.
value	The date of the initial timer shot, expressed in nanoseconds.
interval	The reload value of the timer. It is a periodic interval value to be used for reprogramming the next timer shot, expressed in nanoseconds. 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 xnclock_read_monotonic()), or XN_REALTIME if the absolute date is based on the adjustable real-time date for the relevant clock (obtained from xnclock_read_realtime()).

Returns

0 is returned upon success, or -ETIMEDOUT if an absolute date in the past has been given. In such an event, the timer is nevertheless armed for the next shot in the timeline if interval is different from XN_INFINITE.

Tags

unrestricted, atomic-entry

xntimer_stop()

int xntimer_stop ( struct xntimer *  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

timer

The address of a valid timer descriptor.

Tags

unrestricted, atomic-entry