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 argument 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.

Alarms can be temporarily disabled and reenabled using cyg_alarm_disable and cyg_alarm_enable. Alternatively another call to cyg_alarm_initialize can be used to modify the behaviour of an existing alarm. If an alarm is no longer required then the associated resources can be released using cyg_alarm_delete.

If two or more alarms are registered for precisely the same counter tick, the order of execution of the alarm functions is unspecified.

Handler context

The alarm function is invoked when a counter tick occurs, in other words when there is a call to cyg_counter_tick, and will happen in the same context. If the alarm is associated with the system's real-time clock then by default this will be DSR context, following a clock interrupt. If the alarm is associated with some other application-specific counter then the details will depend on how that counter is updated.

It is also possible to configure the kernel to call kernel RTC alarms in a thread context, instead of a DSR context. This is enabled with the option "Call RTC events from a thread" (CYGIMP_KERNEL_COUNTERS_RTC_TICK_THREAD). When enabled, a dedicated thread is created for running kernel alarm handlers. This can be useful in improving deterministic real-time behaviour as lengthy alarm handlers in a DSR context could disrupt normal scheduling.

As an additional variation, normally the scheduler is locked while running all the alarm handlers, preventing DSRs (and any higher priority threads) from running. However if the "Reduce DSR latency" option is enabled, the scheduler will briefly be unlocked at a safe point between each alarm handler call, in order to allow DSRs to run. This reduces the worst case DSR latency to that of the longest single running alarm handler. However note that if enabled, this option effects all counters and clocks in the system, not just those associated with the kernel RTC.

Valid calling contexts

cyg_alarm_createcyg_alarm_initialize is typically called during system initialization but may also be called in thread context. The same applies to cyg_alarm_delete. cyg_alarm_initialize, cyg_alarm_disable and cyg_alarm_enable may be called during initialization or from thread or DSR context, but cyg_alarm_enable and cyg_alarm_initialize may be expensive operations and should only be called when necessary.