Alarm services

General-purpose watchdog timers. More...

Collaboration diagram for Alarm services:

Data Structures
struct	RT_ALARM_INFO
	Alarm status descriptor. More...

Functions
int	rt_alarm_start (RT_ALARM *alarm, RTIME value, RTIME interval)
	Start an alarm. More...
int	rt_alarm_stop (RT_ALARM *alarm)
	Stop an alarm. More...
int	rt_alarm_inquire (RT_ALARM *alarm, RT_ALARM_INFO *info)
	Query alarm status. More...
int	rt_alarm_create (RT_ALARM *alarm, const char *name, void(*handler)(void *arg), void *arg)
	Create an alarm object. More...
int	rt_alarm_delete (RT_ALARM *alarm)
	Delete an alarm. More...

Detailed Description

General-purpose watchdog timers.

Alarms are general-purpose watchdog timers. Alchemy tasks may create any number of alarms and use them to run a user-defined handler, after a specified initial delay has elapsed. Alarms can be either one shot or periodic; in the latter case, the real-time system automatically reprograms the alarm for the next shot according to a user-defined interval value.

Function Documentation

rt_alarm_create()

int rt_alarm_create	(	RT_ALARM *	alarm,
		const char *	name,
		void(*)(void *arg)	handler,
		void *	arg
	)

Create an alarm object.

This routine creates an object triggering an alarm routine at a specified time in the future. Alarms can be periodic or oneshot, depending on the reload interval value passed to rt_alarm_start().

Parameters

alarm	The address of an alarm descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the alarm. When non-NULL and non-empty, a copy of this string is used for indexing the created alarm into the object registry.
handler	The address of the routine to call when the alarm expires. This routine is passed the arg value.
arg	A user-defined opaque argument passed to the handler.

Returns

Zero is returned upon success. Otherwise:

• -ENOMEM is returned if the system fails to get memory from the local pool in order to create the alarm.
• -EEXIST is returned if the name is conflicting with an already registered alarm.
• -EPERM is returned if this service was called from an asynchronous context.

Tags

mode-unrestricted, switch-secondary

Note

Alarms are process-private objects and thus cannot be shared by multiple processes, even if they belong to the same Xenomai session.

rt_alarm_delete()

int rt_alarm_delete

(

RT_ALARM *

alarm

)

Delete an alarm.

This routine deletes an alarm object previously created by a call to rt_alarm_create().

Parameters

alarm

The alarm descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if alarm is not a valid alarm descriptor.
• -EPERM is returned if this service was called from an asynchronous context.

Tags

mode-unrestricted, switch-secondary

rt_alarm_inquire()

int rt_alarm_inquire	(	RT_ALARM *	alarm,
		RT_ALARM_INFO *	info
	)

Query alarm status.

This routine returns the status information about the specified alarm.

Parameters

alarm	The alarm descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns

Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

• -EINVAL is returned if alarm is not a valid alarm descriptor.

Tags

unrestricted, switch-primary

rt_alarm_start()

int rt_alarm_start	(	RT_ALARM *	alarm,
		RTIME	value,
		RTIME	interval
	)

Start an alarm.

This routine programs the trigger date of an alarm object. An alarm can be either periodic or oneshot, depending on the interval value.

Alarm handlers are always called on behalf of Xenomai's internal timer event routine. Therefore, Xenomai routines which can be called from such handlers are restricted to the set of services available on behalf of an asynchronous context.

This service overrides any previous setup of the expiry date and reload interval for the alarm.

Parameters

alarm	The alarm descriptor.
value	The relative date of the first expiry, expressed in clock ticks (see note).
interval	The reload value of the alarm. It is a periodic interval value to be used for reprogramming the next alarm shot, expressed in clock ticks (see note). If interval is equal to TM_INFINITE, the alarm will not be reloaded after it has expired.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if alarm is not a valid alarm descriptor.
• -EPERM is returned if this service was called from an invalid context.

Tags

xthread-only, switch-primary

Note

Each of the initial value and interval is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

rt_alarm_stop()

int rt_alarm_stop

(

RT_ALARM *

alarm

)

Stop an alarm.

This routine disables an alarm object, preventing any further expiry until it is re-enabled via rt_alarm_start().

Parameters

alarm

The alarm descriptor.

Returns

Zero is returned upon success. Otherwise:

• -EINVAL is returned if alarm is not a valid alarm descriptor.

Tags

unrestricted, switch-primary