timer.h

Go to the documentation of this file.

#ifndef TIMER_H
#define TIMER_H
#include <stdint.h>

/**  
 * \addtogroup Timer Timer module
 *
 * \brief The timer module provides an event interface to the hardware timers.
 *
 * The module uses the 16-bit <b>timer 1</b> of the ATmega32. The timer is dynamically
 * configured as needed by the registered alarms and should always be clocked
 * as slow as possible to keep the interrupt load low. When no alarms are
 * registered, the timer clock is disabled.
 *
 * \note The timer module uses dynamic memory management (malloc()/free()) for the allocation
 * of the ALARM types. This is also done from within ISRs. Thus care must be taken when
 * calling malloc()/free() with interrupts enabled.
 *
 * \note Interrupts must be enabled for the timer to work.
 *
 * @{
 * \file timer.h
 * \version \$Rev: 7715 $
 */

/**
 * \brief ALARM type
 * This is type of a struct containing information about an alarm.
 */
typedef struct ALARM ALARM;

/**
 * \brief Type for alarm callback functions.
 *
 * Alarm callback functions are invoked on the interrupt
 * level whenever the associated alarm expires. The
 * programming model for callback functions is similar
 * to that of interrupt service routines.
 */
typedef void (*alarmcallback_t) (void);

/**
 * \brief Cancel an alarm.
 *
 * \param alrm identifier of the alarm that should be canceled
 * \retval  0  success
 * \retval -1  an error occurred
 * \sa sb_timer_setAlarm
 * \note alarms must not be canceled twice
 */
int8_t sb_timer_cancelAlarm(ALARM *alrm);

/**
 * \brief Create a new alarm.
 *
 * This function can be used to set single shot, as well as repeating timers.
 * 
 * - <b>Single shot:</b> Set cycle to 0. This alarm <b>must not</b> be canceled after being fired.
 * - <b>Repetitive:</b> The first shot can be adjusted be setting alarmtime > 0. Otherwise cycle is used.
 *
 * \note The callback function is called from within the ISR-context.
 *
 * \param callback  callback function that will be invoked whenever the alarm expires
 * \param alarmtime time in ms relative to the current time when the alarm shall expire the first time.
 *                    If set to 0 cycle time will be used.
 * \param cycle     time in ms for alarms that periodically expire after the first regular expiry.
 *                     Set to 0 for single shot timers.
 * \return the identifier of the alarm, or NULL if creating the alarm failed.
 *
 * \warning  Canceling a timer twice or canceling a single shot timer after its expiry may
 *         cause unexpected results.
 *
 * \sa  sb_timer_cancelAlarm
 */
ALARM *sb_timer_setAlarm(alarmcallback_t callback, uint16_t alarmtime, uint16_t cycle);

/**
 *
 *  \brief waits for a specific number of ms
 *
 * This function must not be invoked with interrupts disabled, i.e. from an interrupt
 * handler (or generally, from the ISR level) or a critical section of the application.
 *
 * The CPU is set in sleep mode while waiting.
 *
 * \param waittime wait time in ms 
 * \retval  0  success
 * \retval -1  alarm could not be activated
 * \retval -2  sb_timer_delay invoked while interrupts disabled
 * \sa sb_timer_delay_abort
 *
 */
int8_t sb_timer_delay(uint16_t waittime);

/**
 * \brief Aborts an active sb_timer_delay.
 *
 * This function must be invoked on the ISR level.
 *
 * \sa sb_timer_delay
 */
void sb_timer_delay_abort();

/** @}*/

#endif