Xenomai  3.0.5
Timer services

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

Collaboration diagram for Timer services:

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...
 
void xntimer_init (struct xntimer *timer, struct xnclock *clock, void(*handler)(struct xntimer *timer), struct xnsched *sched, int flags)
 Initialize a timer object. More...
 
void __xntimer_migrate (struct xntimer *timer, struct xnsched *sched)
 Migrate a timer. More...
 
unsigned long long xntimer_get_overruns (struct xntimer *timer, xnticks_t now)
 Get the count of overruns for the last tick. More...
 
static int program_htick_shot (unsigned long delay, struct clock_event_device *cdev)
 Program next host tick as a Xenomai timer event. More...
 
static void switch_htick_mode (enum clock_event_mode mode, struct clock_event_device *cdev)
 Tick mode switch emulation callback. More...
 
int xntimer_grab_hardware (void)
 Grab the hardware timer on all real-time CPUs. More...
 
void xntimer_release_hardware (void)
 Release hardware timers. 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
timerThe address of the timer object to be migrated.
schedThe address of the destination per-CPU scheduler slot.
Tags
unrestricted, atomic-entry

◆ program_htick_shot()

static int program_htick_shot ( unsigned long  delay,
struct clock_event_device *  cdev 
)
static

Program next host tick as a Xenomai timer event.

Program the next shot for the host tick on the current CPU. Emulation is done using a nucleus timer attached to the master timebase.

Parameters
delayThe time delta from the current date to the next tick, expressed as a count of nanoseconds.
cdevAn pointer to the clock device which notifies us.
Tags
unrestricted

◆ switch_htick_mode()

void switch_htick_mode ( enum clock_event_mode  mode,
struct clock_event_device *  cdev 
)
static

Tick mode switch emulation callback.

Changes the host tick mode for the tick device of the current CPU.

Parameters
modeThe new mode to switch to. The possible values are:
  • CLOCK_EVT_MODE_ONESHOT, for a switch to oneshot mode.
  • CLOCK_EVT_MODE_PERIODIC, for a switch to periodic mode. The current implementation for the generic clockevent layer Linux exhibits should never downgrade from a oneshot to a periodic tick mode, so this mode should not be encountered. This said, the associated code is provided, basically for illustration purposes.
  • CLOCK_EVT_MODE_SHUTDOWN, indicates the removal of the current tick device. Normally, the nucleus only interposes on tick devices which should never be shut down, so this mode should not be encountered.
Parameters
cdevAn opaque pointer to the clock device which notifies us.
Tags
unrestricted
Note
GENERIC_CLOCKEVENTS is required from the host kernel.

◆ 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
timerThe 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
timerThe 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,
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 (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
timerThe 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_grab_hardware()

int xntimer_grab_hardware ( void  )

Grab the hardware timer on all real-time CPUs.

xntimer_grab_hardware() grabs and tunes the hardware timer for all real-time CPUs.

Host tick emulation is performed for sharing the clock chip between Linux and Xenomai.

Returns
a positive value is returned on success, representing the duration of a Linux periodic tick expressed as a count of nanoseconds; zero should be returned when the Linux kernel does not undergo periodic timing on the given CPU (e.g. oneshot mode). Otherwise:
  • -EBUSY is returned if the hardware timer has already been grabbed. xntimer_release_hardware() must be issued before xntimer_grab_hardware() is called again.
  • -ENODEV is returned if the hardware timer cannot be used. This situation may occur after the kernel disabled the timer due to invalid calibration results; in such a case, such hardware is unusable for any timing duties.
Tags
secondary-only

References xnsched::cpu, and xnintr_init().

◆ 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
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.
clockThe 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.
handlerThe routine to call upon expiration of the timer.
schedAn 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.
flagsA set of flags describing the timer. The valid flags are:
  • XNTIMER_NOBLCK, the timer won't be frozen while GDB takes over control of the application.

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

◆ xntimer_interval()

xnticks_t xntimer_interval ( struct xntimer *  timer)
inlinestatic

Return the timer interval value.

Return the timer interval value in nanoseconds.

Parameters
timerThe 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_release_hardware()

void xntimer_release_hardware ( void  )

Release hardware timers.

Releases hardware timers previously grabbed by a call to xntimer_grab_hardware().

Tags
secondary-only

References xnsched::cpu.

◆ 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
timerThe address of a valid timer descriptor.
valueThe date of the initial timer shot, expressed in nanoseconds.
intervalThe 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.
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 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
timerThe address of a valid timer descriptor.
Tags
unrestricted, atomic-entry