SPiCboard

timer.h
Go to the documentation of this file.
1#ifndef TIMER_H
2#define TIMER_H
3
4#include <stdint.h>
5#include "check.h"
6
7/**
8 * \addtogroup Timer Timer module
9 *
10 * \brief The timer module provides an event interface to the hardware timers
11 *
12 * The module uses the 16-bit <b>timer 1</b> of the ATmega32. The timer is dynamically
13 * configured as needed by the registered alarms and should always be clocked
14 * as slow as possible to keep the interrupt load low. When no alarms are
15 * registered, the timer clock is disabled.
16 *
17 * \note The timer module uses dynamic memory management (malloc()/free()) for the allocation
18 * of the ALARM types. This is also done from within ISRs. Thus care must be taken when
19 * calling malloc()/free() with interrupts enabled.
20 *
21 * \note Interrupts must be enabled for the timer to work.
22 *
23 * @{
24 * \file timer.h
25 * \version \$Rev: 7715 $
26 */
27
28/**
29 * \brief ALARM type
30 *
31 * This is type of a struct containing information about an alarm.
32 */
33typedef struct ALARM ALARM;
34
35/**
36 * \brief Type for alarm callback functions
37 *
38 * Alarm callback functions are invoked on the interrupt
39 * level whenever the associated alarm expires. The
40 * programming model for callback functions is similar
41 * to that of interrupt service routines.
42 */
43typedef void (*ALARMCALLBACK) (void);
44
45/**
46 * \brief Cancel an alarm
47 *
48 * \param alrm identifier of the alarm that should be canceled
49 *
50 * \retval 0 success
51 * \retval -1 an error occurred
52 *
53 * \sa sb_timer_setAlarm
54 *
55 * \note Alarms must not be canceled twice
56 */
57int8_t sb_timer_cancelAlarm(ALARM *alrm);
58
59/**
60 * \brief Create a new alarm
61 *
62 * This function can be used to set single shot, as well as repeating timers.
63 *
64 * - <b>Single shot:</b> Set cycle to 0. This alarm <b>must not</b> be canceled after being fired.
65 * - <b>Repetitive:</b> The first shot can be adjusted be setting alarmtime > 0. Otherwise cycle is used.
66 *
67 * \note The callback function is called from within the ISR-context.
68 *
69 * \param callback callback function that will be invoked whenever the alarm expires
70 * \param alarmtime time in ms relative to the current time when the alarm shall expire the first time.
71 * If set to 0 cycle time will be used.
72 * \param cycle time in ms for alarms that periodically expire after the first regular expiry.
73 * Set to 0 for single shot timers.
74 *
75 * \return the identifier of the alarm, or NULL if creating the alarm failed.
76 *
77 * \warning Canceling a timer twice or canceling a single shot timer after its expiry may
78 * cause unexpected results.
79 *
80 * \sa sb_timer_cancelAlarm
81 */
82ALARM *sb_timer_setAlarm(ALARMCALLBACK callback, uint16_t alarmtime, uint16_t cycle);
83
84/**
85 * \brief Waits for a specific number of ms
86 *
87 * This function must not be invoked with interrupts disabled, i.e. from an interrupt
88 * handler (or generally, from the ISR level) or a critical section of the application.
89 *
90 * The CPU is set in sleep mode while waiting.
91 *
92 * \param waittime wait time in ms
93 *
94 * \retval 0 success
95 * \retval -1 alarm could not be activated
96 * \retval -2 sb_timer_delay invoked while interrupts disabled
97 *
98 * \sa sb_timer_abortDelay
99 */
100int8_t sb_timer_delay(uint16_t waittime);
101
102/**
103 * \brief Aborts an active sb_timer_delay
104 *
105 * This function must be invoked on the ISR level.
106 *
107 * \sa sb_timer_delay
108 */
109void sb_timer_abortDelay();
110
111/** @}*/
112
113#endif
114
sb_timer_abortDelay
void sb_timer_abortDelay()
Aborts an active sb_timer_delay.
ALARMCALLBACK
void(* ALARMCALLBACK)(void)
Type for alarm callback functions.
Definition: timer.h:43
sb_timer_cancelAlarm
int8_t sb_timer_cancelAlarm(ALARM *alrm)
Cancel an alarm.
ALARM
struct ALARM ALARM
ALARM type.
Definition: timer.h:33
sb_timer_setAlarm
ALARM * sb_timer_setAlarm(ALARMCALLBACK callback, uint16_t alarmtime, uint16_t cycle)
Create a new alarm.
sb_timer_delay
int8_t sb_timer_delay(uint16_t waittime)
Waits for a specific number of ms.