Comtrol eCos - Manual (Page 63)

Alarms
Name
cyg_alarm_create, cyg_alarm_delete, cyg_alarm_initialize, cyg_alarm_enable,
cyg_alarm_disable — Run an alarm function when a number of events have occurred
Synopsis
#include < cyg/kernel/kapi.h >
void cyg_alarm_create(cyg_handle_t counter, cyg_alarm_t* alarmfn, cyg_addrword_t data,
cyg_handle_t* handle, cyg_alarm* alarm);
void cyg_alarm_delete(cyg_handle_t alarm);
void cyg_alarm_initialize(cyg_handle_t alarm, cyg_tick_count_t trigger,
cyg_tick_count_t interval);
void cyg_alarm_enable(cyg_handle_t alarm);
void cyg_alarm_disable(cyg_handle_t alarm);
Description
Kernel alarms are used together with counters and allow for action to be taken when a certain number of events
have occurred. If the counter is associated with a clock then the alarm action happens when the appropriate number
of clock ticks have occurred, in other words after a certain period of time.
Setting up an alarm involves a two-step process. First the alarm must be created with a call to cyg_alarm_create .
This takes five arguments. The first identifies the counter to which the alarm should be attached. If the alarm should
be attached to the system’s real-time clock then
cyg_real_time_clock and cyg_clock_to_counter can be
used to get hold of the appropriate handle. The next two arguments specify the action to be taken when the alarm
is triggered, in the form of a function pointer and some data. This function should take the form:
void
alarm_handler(cyg_handle_t alarm, cyg_addrword_t data)
{
...
}
The data argument passed to the alarm function corresponds to the third argument passed to cyg_alarm_create .
The fourth argument to cyg_alarm_create is used to return a handle to the newly-created alarm object, and the
final argument provides the memory needed for the alarm object and thus avoids any need for dynamic memory
allocation within the kernel.
Once an alarm has been created a further call to cyg_alarm_initialize is needed to activate it. The first argu-
ment specifies the alarm. The second argument indicates the number of events, for example clock ticks, that need
to occur before the alarm triggers. If the third argument is 0 then the alarm will only trigger once. A non-zero value
specifies that the alarm should trigger repeatedly, with an interval of the specified number of events.
63