drv/timer.h

   1 /**
   2  * \file
   3  * <!--
   4  * Copyright 2003, 2004, 2005 Develer S.r.l. (http://www.develer.com/)
   5  * Copyright 2000 Bernardo Innocenti <bernie@develer.com>
   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  *
  13  * \brief Hardware independent timer driver (interface)
  14  */
  15
  16 /*#*
  17  *#* $Log$
  18  *#* Revision 1.33  2007/06/07 14:35:12  batt
  19  *#* Merge from project_ks.
  20  *#*
  21  *#* Revision 1.32  2007/01/09 08:57:19  bernie
  22  *#* Remove excess parentheses.
  23  *#*
  24  *#* Revision 1.31  2006/07/19 12:56:26  bernie
  25  *#* Convert to new Doxygen style.
  26  *#*
  27  *#* Revision 1.30  2006/02/24 00:26:49  bernie
  28  *#* Fixes for CONFIG_KERNEL.
  29  *#*
  30  *#* Revision 1.29  2006/02/21 21:28:02  bernie
  31  *#* New time handling based on TIMER_TICKS_PER_SEC to support slow timers with ticks longer than 1ms.
  32  *#*
  33  *#* Revision 1.28  2006/02/17 22:24:21  bernie
  34  *#* Update POSIX timer emulator.
  35  *#*
  36  *#* Revision 1.27  2005/11/27 03:04:19  bernie
  37  *#* Move test code to timer_test.c; Add OS_HOSTED support.
  38  *#*
  39  *#* Revision 1.26  2005/11/04 16:20:02  bernie
  40  *#* Fix reference to README.devlib in header.
  41  *#*
  42  *#* Revision 1.25  2005/07/19 07:26:37  bernie
  43  *#* Refactor to decouple timer ticks from milliseconds.
  44  *#*
  45  *#* Revision 1.24  2005/04/11 19:10:28  bernie
  46  *#* Include top-level headers from cfg/ subdir.
  47  *#*
  48  *#* Revision 1.23  2005/03/01 23:25:46  bernie
  49  *#* Move event.h to mware/.
  50  *#*
  51  *#* Revision 1.22  2004/12/13 12:07:06  bernie
  52  *#* DISABLE_IRQSAVE/ENABLE_IRQRESTORE: Convert to IRQ_SAVE_DISABLE/IRQ_RESTORE.
  53  *#*
  54  *#* Revision 1.21  2004/12/09 08:35:21  bernie
  55  *#* Replace IPTR with iptr_t.
  56  *#*
  57  *#* Revision 1.20  2004/12/08 08:56:41  bernie
  58  *#* Rename sigset_t to sigmask_t; Reformat.
  59  *#*
  60  *#* Revision 1.19  2004/12/08 08:30:37  bernie
  61  *#* Convert to mtime_t; timer_minutes(): Remove.
  62  *#*
  63  *#* Revision 1.18  2004/11/16 23:09:52  bernie
  64  *#* Disable timer_minutes() for targets with 16bit time_t.
  65  *#*
  66  *#* Revision 1.17  2004/11/16 22:37:14  bernie
  67  *#* Replace IPTR with iptr_t.
  68  *#*
  69  *#* Revision 1.16  2004/08/25 14:12:08  rasky
  70  *#* Aggiornato il comment block dei log RCS
  71  *#*
  72  *#* Revision 1.15  2004/08/10 06:59:09  bernie
  73  *#* timer_gettick(): Rename to timer_ticks() and add backwards compatibility inline.
  74  *#*
  75  *#* Revision 1.12  2004/07/30 14:34:10  rasky
  76  *#* Vari fix per documentazione e commenti
  77  *#* Aggiunte PP_CATn e STATIC_ASSERT
  78  *#*
  79  *#* Revision 1.11  2004/07/29 22:40:12  bernie
  80  *#* Spelling fix.
  81  *#*
  82  *#* Revision 1.10  2004/07/21 00:13:57  bernie
  83  *#* Put timer driver on diet.
  84  *#*
  85  *#* Revision 1.9  2004/07/20 23:45:01  bernie
  86  *#* Finally remove redundant protos.
  87  *#*
  88  *#* Revision 1.8  2004/07/18 21:57:32  bernie
  89  *#* timer_gettick(): Rename to timer_tick() and document better.
  90  *#*
  91  *#* Revision 1.7  2004/06/27 15:26:17  aleph
  92  *#* Declaration fix for build with GCC 3.4
  93  *#*
  94  *#* Revision 1.6  2004/06/07 18:10:06  aleph
  95  *#* Remove free pool of timers; use user-provided Timer structure instead
  96  *#*
  97  *#* Revision 1.5  2004/06/07 15:57:12  aleph
  98  *#* Add function prototypes
  99  *#*
 100  *#* Revision 1.4  2004/06/06 18:25:44  bernie
 101  *#* Rename event macros to look like regular functions.
 102  *#*
 103  *#* Revision 1.3  2004/06/06 16:57:18  bernie
 104  *#* Mark some functions INLINE instead of 'extern inline'.
 105  *#*
 106  *#* Revision 1.2  2004/06/03 11:27:09  bernie
 107  *#* Add dual-license information.
 108  *#*
 109  *#* Revision 1.1  2004/05/23 18:23:30  bernie
 110  *#* Import drv/timer module.
 111  *#*
 112  *#*/
 113 #ifndef DRV_TIMER_H
 114 #define DRV_TIMER_H
 115
 116 #include <cfg/os.h>
 117 #include <cfg/cpu.h>
 118
 119 /*
 120  * Include platform-specific binding header if we're hosted.
 121  * Try the CPU specific one for bare-metal environments.
 122  */
 123 #if OS_HOSTED
 124         #include OS_HEADER(timer)
 125 #else
 126         #include CPU_HEADER(timer)
 127 #endif
 128
 129 #include <mware/list.h>
 130 #include <cfg/debug.h>
 131 #include <cfg/compiler.h>
 132 #include <appconfig.h>
 133
 134
 135 extern volatile ticks_t _clock;
 136
 137 /**
 138  * \brief Return the system tick counter (expressed in ticks)
 139  *
 140  * The result is guaranteed to increment monotonically,
 141  * but client code must be tolerant with respect to overflows.
 142  *
 143  * The following code is safe:
 144  *
 145  * \code
 146  *   ticks_t tea_start_time = timer_clock();
 147  *
 148  *   boil_water();
 149  *
 150  *   if (timer_clock() - tea_start_time > TEAPOT_DELAY)
 151  *       printf("Your tea, Sir.\n");
 152  * \endcode
 153  *
 154  * \note This function must disable interrupts on 8/16bit CPUs because the
 155  * clock variable is larger than the processor word size and can't
 156  * be copied atomically.
 157  */
 158 INLINE ticks_t timer_clock(void)
 159 {
 160         ticks_t result;
 161
 162         ATOMIC(result = _clock);
 163
 164         return result;
 165 }
 166
 167 /**
 168  * Faster version of timer_clock(), to be called only when the timer
 169  * interrupt is disabled (DISABLE_INTS) or overridden by a
 170  * higher-priority or non-nesting interrupt.
 171  *
 172  * \sa timer_clock
 173  */
 174 INLINE ticks_t timer_clock_unlocked(void)
 175 {
 176         return _clock;
 177 }
 178
 179 /** Convert \a ms [ms] to ticks. */
 180 INLINE ticks_t ms_to_ticks(mtime_t ms)
 181 {
 182 #if TIMER_TICKS_PER_SEC < 1000
 183         /* Slow timer: avoid rounding down too much. */
 184         return (ms * TIMER_TICKS_PER_SEC) / 1000;
 185 #else
 186         /* Fast timer: don't overflow ticks_t. */
 187         return ms * ((TIMER_TICKS_PER_SEC + 500) / 1000);
 188 #endif
 189 }
 190
 191 /** Convert \a us [us] to ticks. */
 192 INLINE ticks_t us_to_ticks(utime_t us)
 193 {
 194 #if TIMER_TICKS_PER_SEC < 1000
 195         /* Slow timer: avoid rounding down too much. */
 196         return ((us / 1000) * TIMER_TICKS_PER_SEC) / 1000;
 197 #else
 198         /* Fast timer: don't overflow ticks_t. */
 199         return (us * ((TIMER_TICKS_PER_SEC + 500) / 1000)) / 1000;
 200 #endif
 201 }
 202
 203 /** Convert \a ticks [ticks] to ms. */
 204 INLINE mtime_t ticks_to_ms(ticks_t ticks)
 205 {
 206 #if TIMER_TICKS_PER_SEC < 1000
 207         /* Slow timer: avoid rounding down too much. */
 208         return (ticks * 1000) / TIMER_TICKS_PER_SEC;
 209 #else
 210         /* Fast timer: avoid overflowing ticks_t. */
 211         return ticks / (TIMER_TICKS_PER_SEC / 1000);
 212 #endif
 213 }
 214
 215 /** Convert \a ticks [ticks] to us. */
 216 INLINE utime_t ticks_to_us(ticks_t ticks)
 217 {
 218 #if TIMER_TICKS_PER_SEC < 1000
 219         /* Slow timer: avoid rounding down too much. */
 220         return ((ticks * 1000) / TIMER_TICKS_PER_SEC) * 1000;
 221 #else
 222         /* Fast timer: avoid overflowing ticks_t. */
 223         return (ticks / (TIMER_TICKS_PER_SEC / 1000)) * 1000;
 224 #endif
 225 }
 226
 227 /** Convert \a us [us] to hpticks */
 228 INLINE hptime_t us_to_hptime(utime_t us)
 229 {
 230 #if TIMER_HW_HPTICKS_PER_SEC > 10000000UL
 231         return us * ((TIMER_HW_HPTICKS_PER_SEC + 500000UL) / 1000000UL);
 232 #else
 233         return (us * TIMER_HW_HPTICKS_PER_SEC + 500000UL) / 1000000UL;
 234 #endif
 235 }
 236
 237 /** Convert \a hpticks [hptime] to usec */
 238 INLINE utime_t hptime_to_us(hptime_t hpticks)
 239 {
 240 #if TIMER_HW_HPTICKS_PER_SEC < 100000UL
 241         return hpticks * (1000000UL / TIMER_HW_HPTICKS_PER_SEC);
 242 #else
 243         return (hpticks * 1000000UL) / TIMER_HW_HPTICKS_PER_SEC;
 244 #endif /* TIMER_HW_HPTICKS_PER_SEC < 100000UL */
 245 }
 246
 247
 248 void timer_init(void);
 249 void timer_delayTicks(ticks_t delay);
 250 INLINE void timer_delay(mtime_t delay)
 251 {
 252         timer_delayTicks(ms_to_ticks(delay));
 253 }
 254
 255 #if !defined(CONFIG_TIMER_DISABLE_UDELAY)
 256 void timer_busyWait(hptime_t delay);
 257 void timer_delayHp(hptime_t delay);
 258 INLINE void timer_udelay(utime_t delay)
 259 {
 260         timer_delayHp(us_to_hptime(delay));
 261 }
 262 #endif
 263
 264 #ifndef CONFIG_TIMER_DISABLE_EVENTS
 265
 266 #include <mware/event.h>
 267
 268 /**
 269  * The timer driver supports multiple synchronous timers
 270  * that can trigger an event when they expire.
 271  *
 272  * \sa timer_add()
 273  * \sa timer_abort()
 274  */
 275 typedef struct Timer
 276 {
 277         Node    link;     /**< Link into timers queue */
 278         ticks_t _delay;   /**< Timer delay in ms */
 279         ticks_t tick;     /**< Timer will expire at this tick */
 280         Event   expire;   /**< Event to execute when the timer expires */
 281         DB(uint16_t magic;)
 282 } Timer;
 283
 284 /** Timer is active when Timer.magic contains this value (for debugging purposes). */
 285 #define TIMER_MAGIC_ACTIVE    0xABBA
 286 #define TIMER_MAGIC_INACTIVE  0xBAAB
 287
 288 extern void timer_add(Timer *timer);
 289 extern Timer *timer_abort(Timer *timer);
 290
 291 /** Set the timer so that it calls an user hook when it expires */
 292 INLINE void timer_set_event_softint(Timer *timer, Hook func, iptr_t user_data)
 293 {
 294         event_initSoftInt(&timer->expire, func, user_data);
 295 }
 296
 297 /** Set the timer delay (the time before the event will be triggered) */
 298 INLINE void timer_setDelay(Timer *timer, ticks_t delay)
 299 {
 300         timer->_delay = delay;
 301 }
 302
 303 #endif /* CONFIG_TIMER_DISABLE_EVENTS */
 304
 305 #if defined(CONFIG_KERN_SIGNALS) && CONFIG_KERN_SIGNALS
 306
 307 /** Set the timer so that it sends a signal when it expires */
 308 INLINE void timer_set_event_signal(Timer *timer, struct Process *proc, sigmask_t sigs)
 309 {
 310         event_initSignal(&timer->expire, proc, sigs);
 311 }
 312
 313 #endif /* CONFIG_KERN_SIGNALS */
 314
 315
 316 #endif /* DRV_TIMER_H */