µGFX  2.9
version 2.9
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.io/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 GFXON 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  gTicks when;
56  gTicks period;
57  gU16 flags;
58  struct GTimer_t *next;
59  struct GTimer_t *prev;
61 
62 /*===========================================================================*/
63 /* External declarations. */
64 /*===========================================================================*/
65 
66 /**
67  * @brief Initialise a timer
68  *
69  * @param[in] pt Pointer to a GTimer structure
70  *
71  * @api
72  */
73 void gtimerInit(GTimer* pt);
74 
75 /**
76  * @brief Deinitialise a timer
77  *
78  * @param[in] pt Pointer to a GTimer structure
79  *
80  * @api
81  */
82 void gtimerDeinit(GTimer* pt);
83 
84 /**
85  * @brief Set a timer going or alter its properties if it is already going.
86  *
87  * @param[in] pt Pointer to a GTimer structure
88  * @param[in] fn The callback function
89  * @param[in] param The parameter to pass to the callback function
90  * @param[in] periodic Is the timer a periodic timer? gFalse is a once-only timer.
91  * @param[in] millisec The timer period. The following special values are allowed:
92  * gDelayNone causes the callback function to be called asap.
93  * A periodic timer with this value will fire once only.
94  * gDelayForever never timeout (unless triggered by gtimerJab or gtimerJabI)
95  *
96  * @note If the timer is already active its properties are updated with the new parameters.
97  * The current period will be immediately canceled (without the callback function being
98  * called) and the timer will be restart with the new timer properties.
99  * @note The callback function should be careful not to over-run the thread stack.
100  * Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
101  * change the default size.
102  * @note The callback function should return as quickly as possible as all
103  * timer callbacks are performed by a single thread. If a callback function
104  * takes too long it could affect the timer response for other timers.
105  * @note A timer callback function is not a replacement for a dedicated thread if the
106  * function wants to perform computationally expensive stuff.
107  * @note As the callback function is called on GTIMER's thread, the function must make sure it uses
108  * appropriate synchronisation controls such as semaphores or mutexes around any data
109  * structures it shares with other threads such as the main application thread.
110  *
111  * @api
112  */
113 void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, gBool periodic, gDelay millisec);
114 
115 /**
116  * @brief Stop a timer (periodic or otherwise)
117  *
118  * @param[in] pt Pointer to a GTimer structure
119  *
120  * @note If the timer is not active this does nothing.
121  *
122  * @api
123  */
124 void gtimerStop(GTimer *pt);
125 
126 /**
127  * @brief Test if a timer is currently active
128  *
129  * @param[in] pt Pointer to a GTimer structure
130  *
131  * @return gTrue if active, gFalse otherwise
132  *
133  * @api
134  */
135 gBool gtimerIsActive(GTimer *pt);
136 
137 /**
138  * @brief Jab a timer causing the current period to immediate expire
139  * @details The callback function will be called as soon as possible.
140  *
141  * @pre Use from a normal thread context.
142  *
143  * @param[in] pt Pointer to a GTimer structure
144  *
145  * @note If the timer is not active this does nothing.
146  * @note Repeated Jabs before the callback function actually happens are ignored.
147  *
148  * @api
149  */
150 void gtimerJab(GTimer *pt);
151 
152 /**
153  * @brief Jab a timer causing the current period to immediate expire
154  * @details The callback function will be called as soon as possible.
155  *
156  * @pre Use from an interrupt routine context.
157  *
158  * @param[in] pt Pointer to a GTimer structure
159  *
160  * @note If the timer is not active this does nothing.
161  * @note Repeated Jabs before the callback function actually happens are ignored.
162  *
163  * @iclass
164  * @api
165  */
166 void gtimerJabI(GTimer *pt);
167 
168 #endif /* GFX_USE_GTIMER */
169 
170 #endif /* _GTIMER_H */
171 /** @} */
172 
struct GTimer_t GTimer
A GTimer structure.
void gtimerJabI(GTimer *pt)
Jab a timer causing the current period to immediate expire.
Definition: gtimer.c:223
void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, gBool periodic, gDelay millisec)
Set a timer going or alter its properties if it is already going.
Definition: gtimer.c:139
void gtimerInit(GTimer *pt)
Initialise a timer.
Definition: gtimer.c:129
void gtimerDeinit(GTimer *pt)
Deinitialise a timer.
Definition: gtimer.c:134
gBool 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
void gtimerJab(GTimer *pt)
Jab a timer causing the current period to immediate expire.
Definition: gtimer.c:212
A GTimer structure.
Definition: gtimer.h:52