version 2.8
gtimer.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gtimer/gtimer.h
10  *
11  * @addtogroup GTIMER
12  *
13  * @brief Module which provides software based timers for user-space applications
14  *
15  * @details The reason why uGFX has it's own timer abstraction is because
16  * virtual timers provided by ChibiOS/RT are interrupt context only.
17  * While great for what they are designed for, they make coding of the input
18  * drivers much more complex.
19  * For non-performance critical drivers like these input drivers, it would also
20  * hog an in-ordinate amount of critical (interrupt locked) system time.
21  * This contrary to the goals of a real-time operating system. So a user-land
22  * (thread based) timer mechanism is also required.
23  *
24  * @pre GFX_USE_GTIMER must be set to TRUE in your gfxconf.h
25  *
26  * @{
27  */
28 
29 #ifndef _GTIMER_H
30 #define _GTIMER_H
31 
32 #include "../../gfx.h"
33 
34 #if GFX_USE_GTIMER || defined(__DOXYGEN__)
35 
36 /*===========================================================================*/
37 /* Type definitions */
38 /*===========================================================================*/
39 
40 /* Data part of a static GTimer initialiser */
41 #define _GTIMER_DATA() {0,0,0,0,0,0,0}
42 
43 /* Static GTimer initialiser */
44 #define GTIMER_DECL(name) GTimer name = _GTIMER_DATA()
45 
46 /* A callback function (executed in a thread context) */
47 typedef void (*GTimerFunction)(void *param);
48 
49 /**
50  * @brief A GTimer structure
51  */
52 typedef struct GTimer_t {
53  GTimerFunction fn;
54  void *param;
55  systemticks_t when;
56  systemticks_t period;
57  uint16_t flags;
58  struct GTimer_t *next;
59  struct GTimer_t *prev;
60 } GTimer;
61 
62 /*===========================================================================*/
63 /* External declarations. */
64 /*===========================================================================*/
65 
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69 
70 /**
71  * @brief Initialise a timer
72  *
73  * @param[in] pt Pointer to a GTimer structure
74  *
75  * @api
76  */
77 void gtimerInit(GTimer* pt);
78 
79 /**
80  * @brief Deinitialise a timer
81  *
82  * @param[in] pt Pointer to a GTimer structure
83  *
84  * @api
85  */
86 void gtimerDeinit(GTimer* pt);
87 
88 /**
89  * @brief Set a timer going or alter its properties if it is already going.
90  *
91  * @param[in] pt Pointer to a GTimer structure
92  * @param[in] fn The callback function
93  * @param[in] param The parameter to pass to the callback function
94  * @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer.
95  * @param[in] millisec The timer period. The following special values are allowed:
96  * TIME_IMMEDIATE causes the callback function to be called asap.
97  * A periodic timer with this value will fire once only.
98  * TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
99  *
100  * @note If the timer is already active its properties are updated with the new parameters.
101  * The current period will be immediately canceled (without the callback function being
102  * called) and the timer will be restart with the new timer properties.
103  * @note The callback function should be careful not to over-run the thread stack.
104  * Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
105  * change the default size.
106  * @note The callback function should return as quickly as possible as all
107  * timer callbacks are performed by a single thread. If a callback function
108  * takes too long it could affect the timer response for other timers.
109  * @note A timer callback function is not a replacement for a dedicated thread if the
110  * function wants to perform computationally expensive stuff.
111  * @note As the callback function is called on GTIMER's thread, the function must make sure it uses
112  * appropriate synchronisation controls such as semaphores or mutexes around any data
113  * structures it shares with other threads such as the main application thread.
114  *
115  * @api
116  */
117 void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, delaytime_t millisec);
118 
119 /**
120  * @brief Stop a timer (periodic or otherwise)
121  *
122  * @param[in] pt Pointer to a GTimer structure
123  *
124  * @note If the timer is not active this does nothing.
125  *
126  * @api
127  */
128 void gtimerStop(GTimer *pt);
129 
130 /**
131  * @brief Test if a timer is currently active
132  *
133  * @param[in] pt Pointer to a GTimer structure
134  *
135  * @return TRUE if active, FALSE otherwise
136  *
137  * @api
138  */
139 bool_t gtimerIsActive(GTimer *pt);
140 
141 /**
142  * @brief Jab a timer causing the current period to immediate expire
143  * @details The callback function will be called as soon as possible.
144  *
145  * @pre Use from a normal thread context.
146  *
147  * @param[in] pt Pointer to a GTimer structure
148  *
149  * @note If the timer is not active this does nothing.
150  * @note Repeated Jabs before the callback function actually happens are ignored.
151  *
152  * @api
153  */
154 void gtimerJab(GTimer *pt);
155 
156 /**
157  * @brief Jab a timer causing the current period to immediate expire
158  * @details The callback function will be called as soon as possible.
159  *
160  * @pre Use from an interrupt routine context.
161  *
162  * @param[in] pt Pointer to a GTimer structure
163  *
164  * @note If the timer is not active this does nothing.
165  * @note Repeated Jabs before the callback function actually happens are ignored.
166  *
167  * @iclass
168  * @api
169  */
170 void gtimerJabI(GTimer *pt);
171 
172 #ifdef __cplusplus
173 }
174 #endif
175 
176 #endif /* GFX_USE_GTIMER */
177 
178 #endif /* _GTIMER_H */
179 /** @} */
180 
void gtimerJabI(GTimer *pt)
Jab a timer causing the current period to immediate expire.
Definition: gtimer.c:223
void gtimerDeinit(GTimer *pt)
Deinitialise a timer.
Definition: gtimer.c:134
void gtimerInit(GTimer *pt)
Initialise a timer.
Definition: gtimer.c:129
A GTimer structure.
Definition: gtimer.h:52
bool_t gtimerIsActive(GTimer *pt)
Test if a timer is currently active.
Definition: gtimer.c:208
void gtimerStop(GTimer *pt)
Stop a timer (periodic or otherwise)
Definition: gtimer.c:190
struct GTimer_t GTimer
A GTimer structure.
void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, delaytime_t millisec)
Set a timer going or alter its properties if it is already going.
Definition: gtimer.c:139
void gtimerJab(GTimer *pt)
Jab a timer causing the current period to immediate expire.
Definition: gtimer.c:212