pass handler id to userspace
[pulsecounter.git] / Hal / Hal.h
1 /**
2  * Hal.h -- HAL Interface Definitions
3  *
4  * This example HAL is intentionally simple.  The implementation is limited to:
5  *
6  * BUTTON -- a single button that when pressed will cause an interrupt.
7  * DEBUG -- two debug GPIOs that are available as outputs from the EAP and under user control.
8  * DELAY -- a delay routine that can delay by n milliseconds.
9  * INIT -- set the hardware up to its initial state
10  * LED -- a user LED that is available for application control.
11  * TICK -- a timer that can be set to interrupt every n milliseconds
12  * IDLE LOOP -- an event driven idle loop for controlling the EAP
13  *
14  * For information on Hal implementations for specific target hardware platforms,
15  * visit the http://wiki.em-hub.com/display/ED.
16  *
17  **/
18
19 #ifndef Hal__H
20 #define Hal__H
21
22 #include <stdint.h>
23 #include <stdbool.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 typedef void (*Hal_Handler)(uint8_t id);
30
31 /**
32  * --------- Hal_buttonEnable ---------
33  *
34  * Enable the button interrupt and connect it to the user's buttonHandler
35  *
36  * When the button is pressed, it will cause an interrupt that will cause BUTTON event
37  * to be entered into the event list.  Once dispatched by the idle loop, the user's
38  * buttonHandler will be called.
39  *
40  * Inputs:
41  *   buttonHandler - pointer to the user's handler to be called after interrupt
42  *
43  * Returns:
44  *   None
45  *
46  * Side effects:
47  *   BUTTON interrupt enabled
48  *
49  **/
50 extern void Hal_buttonEnable(Hal_Handler handler);
51 /**
52  * --------- Hal_connected ---------
53  *
54  * Called whenever the MCM peripheral connects to a central.
55  *
56  * Could do other things associated with connection to the central.
57  *
58  * Inputs:
59  *   None
60  *
61  * Returns:
62  *   None
63  *
64  **/
65 extern void Hal_connected(void);
66 /**
67  * --------- Hal_debugOff ---------
68  *
69  * Turns the selected DEBUG line off.
70  *
71  * The two DEBUG lines are output GPIOs that are available to the user for
72  * debug purposes.
73  *
74  * Inputs:
75  *   line - the index value of the debug line to turn off
76  *
77  * Returns:
78  *   None
79  *
80  * Side Effects:
81  *   DEBUG line off.
82  *
83  **/
84 extern void Hal_debugOff(uint8_t line);
85 /**
86  * --------- Hal_debugOn ---------
87  *
88  * Turns the selected DEBUG line on.
89  *
90  * The two DEBUG lines are output GPIOs that are available to the user for
91  * debug purposes.
92  *
93  * Inputs:
94  *   line - the index value of the debug line to turn on
95  *
96  * Returns:
97  *   None
98  *
99  * Side Effects:
100  *   DEBUG line on.
101  *
102  **/
103 extern void Hal_debugOn(uint8_t line);
104 /**
105  * --------- Hal_debugPulse ---------
106  *
107  * Emits a pulse on the selected DEBUG line.
108  *
109  * The two DEBUG lines are output GPIOs that are available to the user for
110  * debug purposes.
111  *
112  * Inputs:
113  *   line - the index value of the debug line to emit a pulse
114  *
115  * Returns:
116  *   None
117  *
118  * Side Effects:
119  *   DEBUG line turns on then off.
120  *
121  **/
122 extern void Hal_debugPulse(uint8_t line);
123 /**
124  * --------- Hal_delay ---------
125  *
126  * Delays for the specified number of milliseconds.
127  *
128  * In this example, delay is done with CPU spinning for simplicity's sake.
129  * This could easily use a timer interrupt for more power savings.
130  *
131  * Inputs:
132  *   msecs - the number of milliseconds to delay
133  *
134  * Returns:
135  *   None
136  *
137  * Side Effects:
138  *   None
139  *
140  **/
141 extern void Hal_delay(uint16_t msecs);
142 /**
143  * --------- Hal_disconnected ---------
144  *
145  * Called whenever the MCM peripheral disconnects from a central.
146  *
147  * Could do other things associated with connection to the central.
148  *
149  * Inputs:
150  *   None
151  *
152  * Returns:
153  *   None
154  *
155  **/
156 extern void Hal_disconnected(void);
157 /**
158  * --------- Hal_idleLoop ---------
159  *
160  * The idle loop that controls EAP operations.
161  *
162  * The hal implements an event driven "idle loop" scheduler.
163  * When there are no events pending, the idle loop sleeps.
164  * When an event happens, the idle loop wakes up, and dispatches
165  * to the appropriate event handler.
166  *
167  * The dispatching is done through a handlerTab that has one entry for each type of event.
168  * Each handlerTab entry should be a handler of type hal_handler *.
169  * There are currently three types of events, i.e. entries in the handlerTab:
170  *   BUTTON_HANDLER_ID:    handler to call upon a button press
171  *   TICK_HANDLER_ID:      handler to call upon a timer interrupt
172  *   DISPATCH_HANDLER_ID:  handler to call upon a received message from the MCM
173  *
174  * Inputs:
175  *   None
176  *
177  * Returns:
178  *   None
179  *
180  * Side Effects:
181  *   dispatches events as they come in
182  *
183  **/
184 extern void Hal_idleLoop(void);
185 /**
186  * --------- Hal_init ---------
187  *
188  * Initialize the hardware
189  *
190  * Initializes the EAP and MCM into their reset state.  Should be called first.
191  * Sets up the clock, ports, watchdog timer, etc.
192  *
193  *
194  * Inputs:
195  *   None
196  *
197  * Returns:
198  *   None
199  *
200  * Side Effects:
201  *   EAP and MCM in their initial state.
202  *
203  **/
204 extern void Hal_init(void);
205 /**
206  * --------- Hal_ledOff ---------
207  *
208  * Turns the user LED off.
209  *
210  * Inputs:
211  *   None
212  *
213  * Returns:
214  *   None
215  *
216  * Side Effects:
217  *   User LED off.
218  *
219  **/
220 extern void Hal_greenLedOff(void);
221 extern void Hal_redLedOff(void);
222 /**
223  * --------- Hal_ledOn ---------
224  *
225  * Turns the user LED on.
226  *
227  * Inputs:
228  *   None
229  *
230  * Returns:
231  *   None
232  *
233  * Side Effects:
234  *   User LED on.
235  *
236  **/
237 extern void Hal_greenLedOn(void);
238 extern void Hal_redLedOn(void);
239 /**
240  * --------- Hal_ledRead ---------
241  *
242  * Returns the user LED state.
243  *
244  * Inputs:
245  *   None
246  *
247  * Returns:
248  *   Bool -  (true = user LED is on, false = user LED is off)
249  *
250  * Side Effects:
251  *   None
252  *
253  **/
254 extern bool Hal_greenLedRead(void);
255 extern bool Hal_redLedRead(void);
256 /**
257  * --------- Hal_ledToggle ---------
258  *
259  * Toggles the user LED.
260  *
261  * Inputs:
262  *   None
263  *
264  * Returns:
265  *   None
266  *
267  * Side Effects:
268  *   User LED toggles state.
269  *
270  **/
271 extern void Hal_greenLedToggle(void);
272 extern void Hal_redLedToggle(void);
273 /**
274  * --------- Hal_tickStart ---------
275  *
276  * Sets up the timer to interrupt every msecs milliseconds and the user's tickHandler
277  * that will be called upon interrupt.
278  *
279  * Enable a timer interrupt every msecs ms.  The interrupt will cause a TICK event
280  * to be entered into the event list.  Once dispatched by the idle loop, the user's
281  * tickHandler will be called.
282  *
283  * Inputs:
284  *   msecs - the number of milliseconds between tick interrupts
285  *   tickHandler - the address of the user's tick handler that will be called
286  *
287  * Returns:
288  *   None
289  *
290  * Side Effects:
291  *   tickhandler called by the idle loop
292  *
293  **/
294 extern void Hal_tickStart(uint16_t msecs, Hal_Handler Handler);
295 extern void Hal_tickStop(void);
296
297 #ifdef __cplusplus
298 }
299 #endif
300
301 #endif /* Hal__H */