Doxygen fix.
[bertos.git] / drv / kbd.c
1 /*!
2  * \file
3  * <!--
4  * Copyright 2003, 2004, 2005 Develer S.r.l. (http://www.develer.com/)
5  * Copyright 1999, 2003 Bernardo Innocenti
6  * This file is part of DevLib - See README.devlib for information.
7  * -->
8  *
9  * \version $Id$
10  *
11  * \author Bernardo Innocenti <bernie@develer.com>
12  * \author Stefano Fedrigo <aleph@develer.com>
13  * \author Francesco Sacchi <batt@develer.com>
14  *
15  * \brief Keyboard driver (implementation)
16  */
17
18 /*#*
19  *#* $Log$
20  *#* Revision 1.6  2006/03/20 17:50:17  bernie
21  *#* Add FreeRTOS and Observers support.
22  *#*
23  *#* Revision 1.5  2006/02/27 22:39:45  bernie
24  *#* Misc build and doc fixes from project_grl.
25  *#*
26  *#* Revision 1.4  2006/02/24 00:27:14  bernie
27  *#* Use new naming convention for list macros.
28  *#*
29  *#* Revision 1.3  2006/02/17 21:15:42  bernie
30  *#* Add MOD_CHECK() checks.
31  *#*
32  *#* Revision 1.2  2006/02/10 12:36:20  bernie
33  *#* Add preliminary FreeRTOS support; Enforce CONFIG_* definitions.
34  *#*
35  *#* Revision 1.1  2005/06/27 21:28:45  bernie
36  *#* Import generic keyboard driver.
37  *#*
38  *#*/
39
40 #include <hw_kbd.h>
41
42 #include <drv/timer.h>
43 #include <drv/kbd.h>
44
45 #include <cfg/debug.h>
46 #include <cfg/module.h>
47 #include <appconfig.h>
48
49 /* Configuration sanity checks */
50 #if !defined(CONFIG_KBD_POLL) || (CONFIG_KBD_POLL != KBD_POLL_SOFTINT && CONFIG_KBD_POLL != CONFIG_POLL_FREERTOS)
51         #error CONFIG_KBD_POLL must be defined to either KBD_POLL_SOFTINT or CONFIG_POLL_FREERTOS
52 #endif
53 #if !defined(CONFIG_KBD_BEEP) || (CONFIG_KBD_BEEP != 0 && CONFIG_KBD_BEEP != 1)
54         #error CONFIG_KBD_BEEP must be defined to either 0 or 1
55 #endif
56 #if !defined(CONFIG_KBD_OBSERVER) || (CONFIG_KBD_OBSERVER != 0 && CONFIG_KBD_OBSERVER != 1)
57         #error CONFIG_KBD_OBSERVER must be defined to either 0 or 1
58 #endif
59
60 #if CONFIG_KBD_BEEP
61         #include <drv/buzzer.h>
62 #endif
63
64 #define KBD_CHECK_INTERVAL  10  /*!< (ms) Timing for kbd softint */
65 #define KBD_DEBOUNCE_TIME   30  /*!< (ms) Debounce time */
66 #define KBD_BEEP_TIME        5  /*!< (ms) Duration of keybeep */
67
68 #define KBD_REPEAT_DELAY   400  /*!< (ms) Keyboard repeat delay for first character */
69 #define KBD_REPEAT_RATE    100  /*!< (ms) Initial interchar delay for keyboard repeat */
70 #define KBD_REPEAT_MAXRATE  20  /*!< (ms) Minimum delay for keyboard repeat */
71 #define KBD_REPEAT_ACCEL     5  /*!< (ms) Keyboard repeat speed increase */
72
73 #define KBD_LNG_DELAY     1000  /*!< (ms) Keyboard long pression keys delay */
74
75
76 /*! Status for keyboard repeat state machine */
77 static enum { KS_IDLE, KS_REPDELAY, KS_REPEAT } kbd_rptStatus;
78
79
80 static volatile keymask_t kbd_buf; /*!< Single entry keyboard buffer */
81 static volatile keymask_t kbd_cnt; /*!< Number of keypress events in \c kbd_buf */
82
83 #if CONFIG_KBD_POLL == KBD_POLL_SOFTINT
84 static Timer kbd_timer;            /*!< Keyboard softtimer */
85 #endif
86
87 static List kbd_rawHandlers;       /*!< Raw keyboard handlers */
88 static List kbd_handlers;          /*!< Cooked keyboard handlers */
89
90 static KbdHandler kbd_defHandler;  /*!< The default keyboard handler */
91 static KbdHandler kbd_debHandler;  /*!< The debounce keyboard handler */
92 static KbdHandler kbd_rptHandler;  /*!< Auto-repeat keyboard handler */
93 #ifdef  K_LNG_MASK
94 static KbdHandler kbd_lngHandler;  /*!< Long pression keys handler */
95 #endif
96
97 #if CONFIG_KBD_OBSERVER
98         #include <mware/observer.h>
99         Subject kbd_subject;
100 #endif
101
102
103 /*!
104  * Poll keyboard and dispatch keys to handlers.
105  *
106  * Read the key states and invoke all keyboard
107  * handlers to process the new state.
108  *
109  * Call this function periodically using a software
110  * timer, an interrupt or a process.
111  */
112 static void kbd_poll(void)
113 {
114         /*! Currently depressed key */
115         static keymask_t current_key;
116
117         struct KbdHandler *handler;
118         keymask_t key = kbd_readkeys();
119
120         /* Call raw input handlers */
121         FOREACH_NODE(handler, &kbd_rawHandlers)
122                 key = handler->hook(key);
123
124         /* If this key was not previously pressed */
125         if (key != current_key)
126         {
127                 /* Remember last key */
128                 current_key = key;
129
130                 /* Call cooked input handlers */
131                 FOREACH_NODE(handler, &kbd_handlers)
132                         key = handler->hook(key);
133         }
134 }
135
136 #if CONFIG_KBD_POLL == KBD_POLL_SOFTINT
137
138 /*!
139  * Keyboard soft-irq handler.
140  */
141 static void kbd_softint(UNUSED_ARG(iptr_t, arg))
142 {
143         kbd_poll();
144         timer_add(&kbd_timer);
145 }
146
147 #elif CONFIG_KBD_POLL == CONFIG_POLL_FREERTOS
148
149 #include "FreeRTOS.h"
150 #include "task.h"
151
152 static portTASK_FUNCTION(kbd_task, arg)
153 {
154         for (;;)
155         {
156                 kbd_poll();
157                 timer_delay(KBD_CHECK_INTERVAL);
158         }
159 }
160
161 #endif /* CONFIG_KBD_POLL */
162
163 /*!
164  * \brief Read a key from the keyboard buffer.
165  *
166  * When a key is kept depressed between calls of this function a value
167  * is returned only after the time specified with KBD_REPAT_DELAY to
168  * avoid too fast keyboard repeat.
169  *
170  * \note This function is \b not interrupt safe!
171  *
172  * \return The mask of depressed keys or 0 if no keys are depressed.
173  *
174  */
175 keymask_t kbd_peek(void)
176 {
177         keymask_t key = 0;
178
179 // FIXME
180         /* Let other tasks run for a while */
181         extern void schedule(void);
182         schedule();
183
184         /* Extract an event from the keyboard buffer */
185         IRQ_DISABLE;
186         if (kbd_cnt)
187         {
188                 --kbd_cnt;
189                 key = kbd_buf;
190         }
191         IRQ_ENABLE;
192
193         return key;
194 }
195
196 /*!
197  * Wait for a keypress and return the mask of depressed keys.
198  *
199  * \note This function is \b not interrupt safe!
200  */
201 keymask_t kbd_get(void)
202 {
203         keymask_t key;
204
205         while (!(key = kbd_peek())) {}
206
207         return key;
208 }
209
210
211 /*!
212  * Wait up to \c timeout ms for a keypress
213  * and return the mask of depressed keys, or K_TIMEOUT
214  * if the timeout was reacked.
215  */
216 keymask_t kbd_get_timeout(mtime_t timeout)
217 {
218         keymask_t key;
219
220         ticks_t start = timer_clock();
221         ticks_t stop  = ms_to_ticks(timeout);
222         do
223         {
224                 if ((key = kbd_peek()))
225                         return key;
226         }
227         while (timer_clock() - start < stop);
228
229         return K_TIMEOUT;
230 }
231
232
233 void kbd_addHandler(struct KbdHandler *handler)
234 {
235         KbdHandler *node;
236         List *list;
237
238         cpuflags_t flags;
239         IRQ_SAVE_DISABLE(flags);
240
241         /* Choose between raw and coocked handlers list */
242         list = (handler->flags & KHF_RAWKEYS) ?
243                 &kbd_rawHandlers : &kbd_handlers;
244
245         /*
246          * Search for the first node whose priority
247          * is lower than the timer we want to add.
248          */
249         FOREACH_NODE(node,list)
250                 if (node->pri < handler->pri)
251                         break;
252
253         /* Enqueue handler in the handlers chain */
254         INSERT_BEFORE(&handler->link, &node->link);
255
256         IRQ_RESTORE(flags);
257 }
258
259
260 void kbd_remHandler(struct KbdHandler *handler)
261 {
262         /* Remove the handler */
263         ATOMIC(REMOVE(&handler->link));
264 }
265
266
267 /*!
268  * This is the default key handler, called after
269  * all other handlers have had their chance to
270  * do their special processing. This handler
271  * pushes all input in the keyboard FIFO buffer.
272  */
273 static keymask_t kbd_defHandlerFunc(keymask_t key)
274 {
275         if (key)
276         {
277                 /* Force a single event in kbd buffer */
278                 kbd_buf = key;
279                 kbd_cnt = 1;
280
281                 #if CONFIG_KBD_OBSERVER
282                         observer_notify(&kbd_subject, KBD_EVENT_KEY, &key);
283                 #endif
284
285                 #if CONFIG_KBD_BEEP
286                         if (!(key & K_REPEAT))
287                                 buz_beep(KBD_BEEP_TIME);
288                 #endif
289         }
290
291         /* Eat all input */
292         return 0;
293 }
294
295 /*!
296  * Handle keyboard debounce
297  */
298 static keymask_t kbd_debHandlerFunc(keymask_t key)
299 {
300         /*! Buffer for debounce */
301         static keymask_t debounce_key;
302
303         /*! Timer for keyboard debounce */
304         static ticks_t debounce_time;
305
306         /*! Key aquired after debounce */
307         static keymask_t new_key;
308
309
310         ticks_t now = timer_clock();
311
312         if (key != debounce_key)
313         {
314                 /* Reset debounce timer */
315                 debounce_key = key;
316                 debounce_time = now;
317         }
318         else if ((new_key != debounce_key)
319                 && (now - debounce_time > ms_to_ticks(KBD_DEBOUNCE_TIME)))
320         {
321                 new_key = debounce_key;
322                 debounce_time = now;
323         }
324
325         return new_key;
326 }
327
328 #ifdef  K_LNG_MASK
329 /*!
330  * Handle long pression keys
331  */
332 static keymask_t kbd_lngHandlerFunc(keymask_t key)
333 {
334         static ticks_t stop;
335         ticks_t now = timer_clock();
336
337         if (key & K_LNG_MASK)
338         {
339                 if (now - stop > 0)
340                         key &= K_LNG_MASK;
341                 else
342                         key &= ~K_LNG_MASK;
343         }
344         else
345                 stop = now + ms_to_ticks(KBD_LNG_DELAY);
346         return key;
347 }
348 #endif
349
350 /*!
351  * Handle keyboard repeat
352  */
353 static keymask_t kbd_rptHandlerFunc(keymask_t key)
354 {
355         /* Timer for keyboard repeat events. */
356         static ticks_t repeat_time;
357
358         /* Current repeat rate (for acceleration). */
359         static ticks_t repeat_rate; /*! Current repeat rate (for acceleration) */
360
361         ticks_t now = timer_clock();
362
363         switch (kbd_rptStatus)
364         {
365                 case KS_IDLE:
366                         if (key & K_RPT_MASK)
367                         {
368                                 repeat_time = now;
369                                 kbd_rptStatus = KS_REPDELAY;
370                         }
371                         break;
372
373                 case KS_REPDELAY:
374                         if (key & K_RPT_MASK)
375                         {
376                                 if (now - repeat_time > ms_to_ticks(KBD_REPEAT_DELAY))
377                                 {
378                                         key = (key & K_RPT_MASK) | K_REPEAT;
379                                         repeat_time = now;
380                                         repeat_rate = ms_to_ticks(KBD_REPEAT_RATE);
381                                         kbd_rptStatus = KS_REPEAT;
382                                 }
383                                 else
384                                         key = 0;
385                         }
386                         else
387                                 kbd_rptStatus = KS_IDLE;
388                         break;
389
390                 case KS_REPEAT:
391                         if (key & K_RPT_MASK)
392                         {
393                                 if (now - repeat_time > repeat_rate)
394                                 {
395                                         /* Enqueue a new event in the buffer */
396                                         key = (key & K_RPT_MASK) | K_REPEAT;
397                                         repeat_time = now;
398
399                                         /* Repeat rate acceleration */
400                                         if (repeat_rate > ms_to_ticks(KBD_REPEAT_MAXRATE))
401                                                 repeat_rate -= ms_to_ticks(KBD_REPEAT_ACCEL);
402                                 }
403                                 else
404                                         key = 0;
405                         }
406                         else
407                                 kbd_rptStatus = KS_IDLE;
408
409                         break;
410         }
411
412         return key;
413 }
414
415
416 MOD_DEFINE(kbd)
417
418 /*!
419  * Initialize keyboard ports and softtimer
420  */
421 void kbd_init(void)
422 {
423 #if CONFIG_KBD_BEEP
424         MOD_CHECK(buzzer);
425 #endif
426
427         KBD_HW_INIT;
428
429         /* Init handlers lists */
430         LIST_INIT(&kbd_handlers);
431         LIST_INIT(&kbd_rawHandlers);
432
433         /* Add debounce keyboard handler */
434         kbd_debHandler.hook = kbd_debHandlerFunc;
435         kbd_debHandler.pri = 100; /* high priority */
436         kbd_debHandler.flags = KHF_RAWKEYS;
437         kbd_addHandler(&kbd_debHandler);
438
439         #ifdef  K_LNG_MASK
440         /* Add long pression keyboard handler */
441         kbd_lngHandler.hook = kbd_lngHandlerFunc;
442         kbd_lngHandler.pri = 90; /* high priority */
443         kbd_lngHandler.flags = KHF_RAWKEYS;
444         kbd_addHandler(&kbd_lngHandler);
445         #endif
446
447         /* Add repeat keyboard handler */
448         kbd_rptHandler.hook = kbd_rptHandlerFunc;
449         kbd_rptHandler.pri = 80; /* high priority */
450         kbd_rptHandler.flags = KHF_RAWKEYS;
451         kbd_addHandler(&kbd_rptHandler);
452
453         /* Add default keyboard handler */
454         kbd_defHandler.hook = kbd_defHandlerFunc;
455         kbd_defHandler.pri = -128; /* lowest priority */
456         kbd_addHandler(&kbd_defHandler);
457
458 #if CONFIG_KBD_OBSERVER
459         observer_InitSubject(&kbd_subject);
460 #endif
461
462 #if CONFIG_KBD_POLL == KBD_POLL_SOFTINT
463
464         MOD_CHECK(timer);
465
466         /* Add kbd handler to soft timers list */
467         event_initSoftInt(&kbd_timer.expire, kbd_softint, 0);
468         timer_setDelay(&kbd_timer, ms_to_ticks(KBD_CHECK_INTERVAL));
469         timer_add(&kbd_timer);
470
471 #elif CONFIG_KBD_POLL == CONFIG_POLL_FREERTOS
472
473         /* Create a timer specific thread */
474         xTaskCreate(kbd_task, "kbd", CONFIG_STACK_KBD,
475                         NULL, CONFIG_PRI_KBD, NULL);
476
477 #else
478         #error "Define keyboard poll method"
479 #endif
480
481         MOD_INIT(kbd);
482 }