Alarm services.
[Native Xenomai API.]

Collaboration diagram for Alarm services.:

Detailed Description

Alarms are general watchdog timers. Any Xenomai task 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 kernel automatically reprograms the alarm for the next shot according to a user-defined interval value.


Files

file  alarm.c
 This file is part of the Xenomai project.

Functions

int rt_alarm_create (RT_ALARM *alarm, const char *name, rt_alarm_t handler, void *cookie)
int rt_alarm_delete (RT_ALARM *alarm)
int rt_alarm_start (RT_ALARM *alarm, RTIME value, RTIME interval)
int rt_alarm_stop (RT_ALARM *alarm)
int rt_alarm_inquire (RT_ALARM *alarm, RT_ALARM_INFO *info)
int rt_alarm_create (RT_ALARM *alarm, const char *name)
int rt_alarm_wait (RT_ALARM *alarm)

Function Documentation

int rt_alarm_create ( RT_ALARM *  alarm,
const char *  name 
)

Create an alarm object from user-space.

Initializes an alarm object from a user-space application. Alarms can be made periodic or oneshot, depending on the reload interval value passed to rt_alarm_start() for them. In this mode, the basic principle is to define some alarm server task which routinely waits for the next incoming alarm event through the rt_alarm_wait() syscall.

Parameters:
alarm The address of an alarm descriptor Xenomai will use to store the alarm-related data. This descriptor must always be valid while the alarm is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the alarm. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created alarm.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: possible.

Note:
It is possible to combine kernel-based alarm handling with waiter threads pending on the same alarm object from user-space through the rt_alarm_wait() service. For this purpose, the rt_alarm_handler() routine which is internally invoked to wake up alarm servers in user-space is accessible to user-provided alarm handlers in kernel space, and should be called from there in order to unblock any thread sleeping on the rt_alarm_wait() service.

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

Create an alarm object from kernel space.

Create an object triggering an alarm routine at a specified time in the future. Alarms can be made periodic or oneshot, depending on the reload interval value passed to rt_alarm_start() for them. In kernel space, alarms are immediately notified on behalf of the timer interrupt to a user-defined handler.

Parameters:
alarm The address of an alarm descriptor Xenomai will use to store the alarm-related data. This descriptor must always be valid while the alarm is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the alarm. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created alarm.
handler The address of the routine to call when the alarm expires. This routine will be passed the address of the current alarm descriptor, and the opaque cookie.
cookie A user-defined opaque cookie the real-time kernel will pass to the alarm handler as its second argument.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: possible.

Note:
It is possible to combine kernel-based alarm handling with waiter threads pending on the same alarm object from user-space through the rt_alarm_wait() service. For this purpose, the rt_alarm_handler() routine which is internally invoked to wake up alarm servers in user-space is accessible to user-provided alarm handlers in kernel space, and should be called from there in order to unblock any thread sleeping on the rt_alarm_wait() service.

int rt_alarm_delete ( RT_ALARM *  alarm  ) 

Delete an alarm.

Destroy an alarm. An alarm exists in the system since rt_alarm_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:
alarm The descriptor address of the affected alarm.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: never.

int rt_alarm_inquire ( RT_ALARM *  alarm,
RT_ALARM_INFO *  info 
)

Inquire about an alarm.

Return various information about the status of a given alarm.

Parameters:
alarm The descriptor address of the inquired alarm.
info The address of a structure the alarm information will be written to.
The expiration date returned in the information block is converted to the current time unit. The special value TM_INFINITE is returned if alarm is currently inactive/stopped. In single-shot mode, it might happen that the alarm has already expired when this service is run (even if the associated handler has not been fired yet); in such a case, 1 is returned.

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

Environments:

This service can be called from:

Rescheduling: never.

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

Start an alarm.

Program the trigger date of an alarm object. An alarm can be either periodic or oneshot, depending on the reload value passed to this routine. The given alarm must have been previously created by a call to rt_alarm_create().

Alarm handlers are always called on behalf of Xenomai's internal timer tick handler, so the Xenomai services which can be called from such handlers are restricted to the set of services available on behalf of any ISR.

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

Parameters:
alarm The descriptor address of the affected alarm.
value The relative date of the initial alarm shot, 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:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: never.

Note:
The initial value and interval will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

int rt_alarm_stop ( RT_ALARM *  alarm  ) 

Stop an alarm.

Disarm an alarm object previously armed using rt_alarm_start() so that it will not trigger until is is re-armed.

Parameters:
alarm The descriptor address of the released alarm.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: never.

int rt_alarm_wait ( RT_ALARM *  alarm  ) 

Wait for the next alarm shot.

This user-space only call allows the current task to suspend execution until the specified alarm triggers. The priority of the current task is raised above all other Xenomai tasks - except those also undergoing an alarm or interrupt wait (see rt_intr_wait()) - so that it would preempt any of them under normal circumstances (i.e. no scheduler lock).

Parameters:
alarm The descriptor address of the awaited alarm.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: always.

Examples:
user_alarm.c.

Generated on Mon Mar 24 18:02:41 2008 for Xenomai API by  doxygen 1.5.3