HardwareTimer.h

00001 /* HardwareTimer.h
00002  * Tested with mbed board: FRDM-KL46Z
00003  * Author: Mark Gottscho
00004  * mgottscho@ucla.edu
00005  */
00006 
00007 #ifndef HARDWARETIMER_H
00008 #define HARDWARETIMER_H
00009 
00010 #include "mbed.h"
00011 #include "PreciseTime.h"
00012 
00013 /**
00014  * This provides a base class from which actual hardware timers should derive their implementations.
00015  * This allows for a nice software interface regardless of the particular timer used.
00016  */
00017 class HardwareTimer {
00018     public:
00019         typedef enum {
00020             ns,
00021             us,
00022             ms,
00023             s,
00024             m,
00025             h    
00026         } tick_units_t;
00027         
00028         /**
00029          * Constructs a new HardwareTimer.
00030          * @param valid if false, none of the timer functions can be used. This is intended to enforce only one object
00031          * managing a unique hardware timer.
00032          * @param maxRolloverTick maximum number of ticks in the hardware unit before it rolls over.
00033          * @param tickValue the amount of time corresponding to each timer tick, in units given by tickUnits.
00034          * @param tickUnits units for tickValue
00035          */
00036         HardwareTimer(uint32_t maxRolloverTick, float tickValue , tick_units_t tickUnits );
00037         
00038         /**
00039          * Destructs the HardwareTimer.
00040          */
00041         virtual ~HardwareTimer();
00042         
00043         /**
00044          * @returns true if this timer is valid. If false, the timer cannot be used.
00045          */
00046         bool valid ();
00047         
00048         /**
00049          * @returns true if the timer is ready to start.
00050          */
00051         bool enabled (); 
00052         
00053         /**
00054          * @returns true if the timer is running.
00055          */
00056         bool running ();   
00057         
00058         /**
00059          * @returns the amount of time corresponding to each timer tick in units given by tickUnits().
00060          */
00061         float tickValue ();
00062         
00063         /**
00064          * @returns time in seconds corresponding to each tick
00065          */
00066         float tickUnits ();
00067         
00068         /**
00069          * Enables the timer with a user-specified callback function that is called each time the timer expires.
00070          * @param fptr the user callback function
00071          */
00072         void enable(void (*fptr)(void));
00073         
00074         /**
00075          * Enables the timer with a user-specified callback function that is called each time the timer expires.
00076          * @param tptr the object 
00077          * @param mptr method to call on the object
00078          */
00079         template<typename T> void enable(T *tptr, void (T::*mptr)(void));
00080         
00081         /**
00082          * Stops and disables the timer. No user function callbacks will be made, and the tick value stops increasing.
00083          */
00084         void disable();
00085         
00086         /**
00087          * Starts the timer. If valid() or enabled() are false, then this method does nothing. Otherwise, the timer
00088          * begins ticking. The user callback function specified in enableTimer() is called each time the timer rolls over.
00089          * @param callback_tick_count the modulo tick value for when the timer calls the user callback function.
00090          * Note that the timer counts up. Note that some timers may not support the full 32-bit range. Use getMaxCallbackTickCount()
00091          * To check the maximum allowed value. If callback_tick_count is greater than that value, this method will have no effect.
00092          * @param periodic if true, the timer will call the user function every time the internal tick modulo callback_tick_count is reached.
00093          * If false, the user callback function is only called the first num_callbacks times.
00094          * @param num_callbacks if periodic is set to false, this many callbacks will be made. Before the timer stops.
00095          */
00096         void start(uint32_t callback_tick_count, bool periodic, uint32_t num_callbacks);
00097         
00098         /**
00099          * @returns the maximum value of the user-settable callback tick count (via startTimer()).
00100          * Some timers may support full 32-bit tick counts, while others may be less.
00101          */
00102         uint32_t getMaxCallbackTickCount ();
00103         
00104         /**
00105          * Gets the timer value in a nice form.
00106          * Note that in general, the timer may overflow, leading to saturated values obtained from getTime().
00107          * To maximize resolution, accuracy, performance, and range, it is recommended to use
00108          * getTick() for most purposes. getTime() is mostly for convenience.
00109          * @returns the current tick converted into a PreciseTime representation.
00110          */
00111         PreciseTime getTime();
00112         
00113         /**
00114          * @returns the current tick number. Convert to seconds by multiplying the return value with tickValue().
00115          * Note that getTick() * tickValue() can easily overflow on faster timers due to the 32-bit upper bound
00116          * on arithmetic.
00117          */
00118         virtual uint32_t getTick () = 0;
00119         
00120         /**
00121          * Interrupt service routine for the timer. This should do timer hardware-specific chores before calling the user
00122          * callback function.
00123          */
00124         virtual void __timer_isr() = 0;
00125         
00126     protected:        
00127         /**
00128          * Initializes the particular hardware timer.
00129          */
00130         virtual void __init_timer() = 0;
00131         
00132         /**
00133          * Starts the particular hardware timer.
00134          */
00135         virtual void __start_timer() = 0;
00136         
00137         /**
00138          * Stop and disable the particular hardware timer.
00139          */
00140         virtual void __stop_timer() = 0;
00141         
00142         bool __valid; //timer can be used
00143         volatile uint32_t __count; //number of rollovers
00144         uint32_t __rolloverValue; //ticks per rollover
00145         bool __periodic; //periodic callbacks
00146         volatile uint32_t __num_callbacks;
00147         
00148         FunctionPointer *__user_fptr; //User callback function
00149 
00150     private:   
00151         bool __enabled; //timer is configured
00152         bool __running; //timer is running     
00153         uint32_t __maxRolloverTick; //maximum number of ticks before timer hardware rolls over
00154         float __tickValue; //how many units per tick
00155         tick_units_t __tickUnits; //tick units
00156 };
00157 
00158 #endif