Collaboration diagram for Time base services.:

Files
file	timebase.h

file	timebase.c

Functions
int	xntbase_alloc (const char name, u_long period, u_long flags, xntbase_t *basep)
	Allocate a time base. More...

void	xntbase_free (xntbase_t *base)
	Free a time base. More...

int	xntbase_update (xntbase_t *base, u_long period)
	Change the period of a time base. More...

int	xntbase_switch (const char name, u_long period, xntbase_t *basep)
	Replace a time base. More...

void	xntbase_start (xntbase_t *base)
	Start a time base. More...

void	xntbase_stop (xntbase_t *base)
	Stop a time base. More...

void	xntbase_tick (xntbase_t *base)
	Announce a clock tick to a time base. More...

xnticks_t	xntbase_convert (xntbase_t srcbase, xnticks_t ticks, xntbase_t dstbase)
	Convert a clock value into another time base. More...

static xnticks_t	xntbase_get_time (xntbase_t *base)
	Get the clock time for a given time base. More...

void	xntbase_adjust_time (xntbase_t *base, xnsticks_t delta)
	Adjust the clock time for the system. More...

Detailed Description

Xenomai implements the notion of time base, by which software timers that belong to different skins may be clocked separately according to distinct frequencies, or aperiodically. In the periodic case, delays and timeouts are given in counts of ticks; the duration of a tick is specified by the time base. In the aperiodic case, timings are directly specified in nanoseconds.

Only a single aperiodic (i.e. tick-less) time base may exist in the system, and the nucleus provides for it through the nktbase object. All skins depending on aperiodic timings should bind to the latter (see xntbase_alloc()), also known as the master time base.

Skins depending on periodic timings may create and bind to their own time base. Such a periodic time base is managed as a timed slave object of the master time base. A cascading software timer fired by the master time base according to the appropriate frequency, triggers in turn the update process of the associated timed slave, which eventually fires the elapsed software timers controlled by the periodic time base. In other words, Xenomai emulates periodic timing over an aperiodic policy.

Xenomai always controls the underlying timer hardware in a tick-less fashion, also known as the oneshot mode.

Function Documentation

void xntbase_adjust_time	(	xntbase_t *	base,
		xnsticks_t	delta
	)

Adjust the clock time for the system.

Xenomai tracks the current time as a monotonously increasing count of ticks since the epoch. The epoch is initially the same as the underlying machine time, and it is always synchronised across all active time bases.

This service changes the epoch for the system by applying the specified tick delta on the master's wallclock offset and resynchronizing all other time bases.

Parameters

base	The address of the initiating time base.
delta	The adjustment of the system time expressed in ticks of the specified time base.

Note: This routine must be entered nklock locked, interrupts off.

Environments:

This service can be called from:

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

Rescheduling: never.

Referenced by clock_settime().

int xntbase_alloc	(	const char *	name,
		u_long	period,
		u_long	flags,
		xntbase_t **	basep
	)

Allocate a time base.

A time base is an abstraction used to provide private clocking information to real-time skins, by which they may operate either in aperiodic or periodic mode, possibly according to distinct clock frequencies in the latter case. This abstraction is required in order to support several RTOS emulators running concurrently, which may exhibit different clocking policies and/or period.

Once allocated, a time base may be attached to all software timers created directly or indirectly by a given skin, and influences all timed services accordingly.

The xntbase_alloc() service allocates a new time base to the caller, and returns the address of its descriptor. The new time base is left in a disabled state (unless period equals XN_APERIODIC_TICK), calling xntbase_start() is needed to enable it.

Parameters

name	The symbolic name of the new time base. This information is used to report status information when reading from /proc/xenomai/timebases; it has currently no other usage.
period	The duration of the clock tick for the new time base, given as a count of nanoseconds. The special XN_APERIODIC_TICK value may be used to retrieve the master - aperiodic - time base, which is always up and running when a real-time skin has called the xnpod_init() service. All other values are meant to define the clock rate of a periodic time base. For instance, passing 1000000 (ns) in the period parameter will create a periodic time base clocked at a frequency of 1Khz.
flags	A bitmask composed as follows: - XNTBISO causes the target timebase to be isolated from global wallclock offset updates as performed by xntbase_adjust_time().
basep	A pointer to a memory location which will be written upon success with the address of the allocated time base. If period equals XN_APERIODIC_TICK, the address of the built-in master time base descriptor will be copied back to this location.

Returns: 0 is returned on success. Otherwise:

-ENOMEM is returned if no system memory is available to allocate a new time base descriptor.

Environments:

This service can be called from:

Kernel module initialization code
User-space task in secondary mode

Rescheduling: never.

Note: Any periodic time base allocated by a real-time skin must be released by a call to xntbase_free() before the kernel module implementing the skin may be unloaded.

Referenced by xntbase_switch().

xnticks_t xntbase_convert	(	xntbase_t *	srcbase,
		xnticks_t	ticks,
		xntbase_t *	dstbase
	)

Convert a clock value into another time base.

Parameters

srcbase	The descriptor address of the source time base.
ticks	The clock value expressed in the source time base to convert to the destination time base.
dstbase	The descriptor address of the destination time base.

Returns: The converted count of ticks in the destination time base is returned.

Environments:

This service can be called from:

Kernel module initialization code
Kernel-based task
User-space task

Rescheduling: never.

void xntbase_free ( xntbase_t * base )

Free a time base.

This service disarms all outstanding timers from the affected periodic time base, destroys the aperiodic cascading timer, then releases the time base descriptor.

Parameters

base	The address of the time base descriptor to release.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
User-space task in secondary mode

Rescheduling: never.

Note: Requests to free the master time base are silently caught and discarded; in such a case, outstanding aperiodic timers are left untouched.

Referenced by xntbase_switch().

xnticks_t xntbase_get_time ( xntbase_t * base )

inlinestatic

Get the clock time for a given time base.

This service returns the (external) clock time as maintained by the specified time base. This value is adjusted with the wallclock offset as defined by xntbase_adjust_time().

Parameters

base	The address of the time base to query.

Returns: The current time (in jiffies) if the specified time base runs in periodic mode, or the machine time (converted to nanoseconds) as maintained by the hardware if base refers to the master time base.

Environments:

This service can be called from:

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

Rescheduling: never.

Referenced by clock_gettime(), clock_settime(), rt_task_sleep_until(), rt_timer_inquire(), and xnregistry_bind().

void xntbase_start ( xntbase_t * base )

Start a time base.

This service enables a time base, using a cascading timer running in the master time base as the source of periodic clock ticks. The time base is synchronised on the Xenomai system clock. Timers attached to the started time base are immediated armed.

Parameters

base	The address of the time base descriptor to start.

Environments:

This service can be called from:

Kernel module initialization code
Kernel-based task
User-space task

Rescheduling: never.

Note: Requests to enable the master time base are silently caught and discarded; only the internal service xnpod_enable_timesource() is allowed to start the latter. The master time base remains enabled until no real-time skin remains attached to the nucleus.

Referenced by xntbase_switch().

void xntbase_stop ( xntbase_t * base )

Stop a time base.

This service disables a time base, stopping the cascading timer running in the master time base which is used to clock it. Outstanding timers attached to the stopped time base are immediated disarmed.

Stopping a time base also invalidates its clock setting.

Parameters

base	The address of the time base descriptor to stop.

Environments:

This service can be called from:

Kernel module initialization code
Kernel-based task
User-space task

Note: Requests to disable the master time base are silently caught and discarded; only the internal service xnpod_disable_timesource() is allowed to stop the latter. The master time base remains enabled until no real-time skin remains attached to the nucleus.

int xntbase_switch	(	const char *	name,
		u_long	period,
		xntbase_t **	basep
	)

Replace a time base.

This service is useful for switching the current time base of a real-time skin between aperiodic and periodic modes, by providing a new time base descriptor as needed. The original time base descriptor is freed as a result of this operation (unless it refers to the master time base). The new time base is automatically started by a call to xntbase_start() if the original time base was enabled at the time of the call, or left in a disabled state otherwise.

This call handles all mode transitions and configuration changes carefully, i.e. periodic <-> periodic, aperiodic <-> aperiodic, periodic <-> aperiodic.

Parameters

name	The symbolic name of the new time base. This information is used to report status information when reading from /proc/xenomai/timebases; it has currently no other usage.
period	The duration of the clock tick for the time base, given as a count of nanoseconds. This value is meant to define the new clock rate of the new periodic time base (i.e. 1e9 / period).
basep	A pointer to a memory location which will be first read to pick the address of the original time base to be replaced, then written back upon success with the address of the new time base. A null pointer is allowed on input in basep, in which case the new time base will be created as if xntbase_alloc() had been called directly.

Returns: 0 is returned on success. Otherwise:

-ENOMEM is returned if no system memory is available to allocate a new time base descriptor.

Environments:

This service can be called from:

Kernel module initialization code
User-space task in secondary mode

Rescheduling: never.

References xntbase_alloc(), xntbase_free(), xntbase_start(), and xntbase_update().

Referenced by rt_timer_set_mode().

void xntbase_tick ( xntbase_t * base )

Announce a clock tick to a time base.

This service announces a new clock tick to a time base. Normally, only specialized nucleus code would announce clock ticks. However, under certain circumstances, it may be useful to allow client code to send such notifications on their own.

Notifying a clock tick to a time base causes the timer management code to check for outstanding timers, which may in turn fire off elapsed timeout handlers. Additionally, periodic time bases (i.e. all but the master time base) would also update their count of elapsed jiffies, in case the current processor has been defined as the internal time keeper (i.e. CPU# == XNTIMER_KEEPER_ID).

Parameters

base	The address of the time base descriptor to announce a tick to.

Environments:

This service can be called from:

Interrupt context only.

Rescheduling: never.

References xntimer_tick_aperiodic().

int xntbase_update	(	xntbase_t *	base,
		u_long	period
	)

Change the period of a time base.

Parameters

base	The address of the time base descriptor to update.
period	The duration of the clock tick for the time base, given as a count of nanoseconds. This value is meant to define the new clock rate of the affected periodic time base (i.e. 1e9 / period).

Returns: 0 is returned on success. Otherwise:

-EINVAL is returned if an attempt is made to set a null period.

Environments:

This service can be called from:

Kernel module initialization code
Kernel-based task
User-space task

Rescheduling: never.

Note: Requests to update the master time base are silently caught and discarded. The master time base has a fixed aperiodic policy which may not be changed.

Referenced by xntbase_switch().

Files

Functions

Detailed Description

Function Documentation