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