Alarm services.
[Native Xenomai API.]

---

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)
	Create an alarm object from kernel space.
int	rt_alarm_delete (RT_ALARM *alarm)
	Delete an alarm.
int	rt_alarm_start (RT_ALARM *alarm, RTIME value, RTIME interval)
	Start an alarm.
int	rt_alarm_stop (RT_ALARM *alarm)
	Stop an alarm.
int	rt_alarm_inquire (RT_ALARM *alarm, RT_ALARM_INFO *info)
	Inquire about an alarm.
int	rt_alarm_create (RT_ALARM *alarm, const char *name)
	Create an alarm object from user-space.
int	rt_alarm_wait (RT_ALARM *alarm)
	Wait for the next alarm shot.

---

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: -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the alarm. -EEXIST is returned if the name is already in use by some registered object. -EPERM is returned if this service was called from an asynchronous context. Environments: This service can be called from: User-space task 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: -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the alarm. -EEXIST is returned if the name is already in use by some registered object. -EPERM is returned if this service was called from an asynchronous context. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task 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: -EINVAL is returned if alarm is not a alarm descriptor. -EIDRM is returned if alarm is a deleted alarm descriptor. -EPERM is returned if this service was called from an asynchronous context. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task 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: -EINVAL is returned if alarm is not a alarm descriptor. -EIDRM is returned if alarm is a deleted alarm descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task 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: -EINVAL is returned if alarm is not a alarm descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never. Note: This service is sensitive to the current operation mode of the system timer, as defined by the CONFIG_XENO_OPT_TIMING_PERIOD parameter. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

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: -EINVAL is returned if alarm is not a alarm descriptor. -EIDRM is returned if alarm is a deleted alarm descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task 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: -EINVAL is returned if alarm is not an alarm descriptor. -EPERM is returned if this service was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked). -EIDRM is returned if alarm is a deleted alarm descriptor, including if the deletion occurred while the caller was waiting for its next shot. -EINTR is returned if rt_task_unblock() has been called for the current task before the next alarm shot. Environments: This service can be called from: User-space task Rescheduling: always.

---