libspicboard-doc

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  */
33 typedef 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  */
43 typedef 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  */
57 int8_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  */
82 ALARM *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  */
100 int8_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  */
109 void sb_timer_abortDelay();
110 
111 /** @}*/
112 
113 #endif
114 
sb_timer_abortDelay
void sb_timer_abortDelay()
Aborts an active sb_timer_delay.
sb_timer_setAlarm
ALARM * sb_timer_setAlarm(ALARMCALLBACK callback, uint16_t alarmtime, uint16_t cycle)
Create a new alarm.
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_delay
int8_t sb_timer_delay(uint16_t waittime)
Waits for a specific number of ms.