Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# timerx8.h

Go to the documentation of this file.

    00001 /*! \file timerx8.h \brief Timer function library for ATmegaXX8 Processors. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'timerx8.h'
    00005 // Title        : Timer function library for ATmegaXX8 Processors
    00006 // Author       : Pascal Stang - Copyright (C) 2000-2005
    00007 // Created      : 11/22/2000
    00008 // Revised      : 06/15/2005
    00009 // Version      : 1.0
    00010 // Target MCU   : Atmel AVR Series
    00011 // Editor Tabs  : 4
    00012 //
    00013 // This code is distributed under the GNU Public License
    00014 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00015 //
    00016 /// \ingroup driver_avr
    00017 /// \defgroup timerx8 Timer Function Library for ATmegaXX8 (timerx8.c)
    00018 /// \code #include "timerx8.h" \endcode
    00019 /// \par Overview
    00020 ///     This library provides functions for use with the timers internal
    00021 ///     to the AVR processors.  Functions include initialization, set prescaler,
    00022 ///     calibrated pause function (in milliseconds), attaching and detaching of
    00023 ///     user functions to interrupts, overflow counters, PWM. Arbitrary
    00024 ///     frequency generation has been moved to the Pulse Library.
    00025 ///
    00026 /// \par About Timers
    00027 ///     The Atmel AVR-series processors each contain at least one
    00028 ///     hardware timer/counter.  Many of the processors contain 2 or 3
    00029 ///     timers.  Generally speaking, a timer is a hardware counter inside
    00030 ///     the processor which counts at a rate related to the main CPU clock
    00031 ///     frequency.  Because the counter value increasing (counting up) at
    00032 ///     a precise rate, we can use it as a timer to create or measure
    00033 ///     precise delays, schedule events, or generate signals of a certain
    00034 ///     frequency or pulse-width.
    00035 /// \par
    00036 ///     As an example, the ATmega163 processor has 3 timer/counters.
    00037 ///     Timer0, Timer1, and Timer2 are 8, 16, and 8 bits wide respectively.
    00038 ///     This means that they overflow, or roll over back to zero, at a
    00039 ///     count value of 256 for 8bits or 65536 for 16bits.  A prescaler is
    00040 ///     avaiable for each timer, and the prescaler allows you to pre-divide
    00041 ///     the main CPU clock rate down to a slower speed before feeding it to
    00042 ///     the counting input of a timer.  For example, if the CPU clock
    00043 ///     frequency is 3.69MHz, and Timer0's prescaler is set to divide-by-8,
    00044 ///     then Timer0 will "tic" at 3690000/8 = 461250Hz.  Because Timer0 is
    00045 ///     an 8bit timer, it will count to 256 in just 256/461250Hz = 0.555ms.
    00046 ///     In fact, when it hits 255, it will overflow and start again at
    00047 ///     zero.  In this case, Timer0 will overflow 461250/256 = 1801.76
    00048 ///     times per second.
    00049 /// \par
    00050 ///     Timer0 can be used a number of ways simultaneously.  First, the
    00051 ///     value of the timer can be read by accessing the CPU register \c TCNT0.
    00052 ///     We could, for example, figure out how long it takes to execute a
    00053 ///     C command by recording the value of \c TCNT0 before and after
    00054 ///     execution, then subtract (after-before) = time elapsed.  Or we can
    00055 ///     enable the overflow interrupt which goes off every time T0
    00056 ///     overflows and count out longer delays (multiple overflows), or
    00057 ///     execute a special periodic function at every overflow.
    00058 /// \par
    00059 ///     The other timers (Timer1 and Timer2) offer all the abilities of
    00060 ///     Timer0 and many more features.  Both T1 and T2 can operate as
    00061 ///     general-purpose timers, but T1 has special hardware allowing it to
    00062 ///     generate PWM signals, while T2 is specially designed to help count
    00063 ///     out real time (like hours, minutes, seconds).  See the
    00064 ///     Timer/Counter section of the processor datasheet for more info.
    00065 ///
    00066 //*****************************************************************************
    00067 //@{
    00068
    00069 #ifndef TIMER_H
    00070 #define TIMER_H
    00071
    00072 #include "global.h"
    00073
    00074 // constants/macros/typdefs
    00075
    00076 // processor compatibility fixes
    00077 #ifdef __AVR_ATmega323__
    00078     // redefinition for the Mega323
    00079     #define CTC1    CTC10
    00080 #endif
    00081 #ifndef PWM10
    00082     // mega128 PWM bits
    00083     #define PWM10   WGM10
    00084     #define PWM11   WGM11
    00085 #endif
    00086
    00087
    00088 // Timer/clock prescaler values and timer overflow rates
    00089 // tics = rate at which the timer counts up
    00090 // 8bitoverflow = rate at which the timer overflows 8bits (or reaches 256)
    00091 // 16bit [overflow] = rate at which the timer overflows 16bits (65536)
    00092 //
    00093 // overflows can be used to generate periodic interrupts
    00094 //
    00095 // for 8MHz crystal
    00096 // 0 = STOP (Timer not counting)
    00097 // 1 = CLOCK        tics= 8MHz          8bitoverflow= 31250Hz       16bit= 122.070Hz
    00098 // 2 = CLOCK/8      tics= 1MHz          8bitoverflow= 3906.25Hz     16bit=  15.259Hz
    00099 // 3 = CLOCK/64     tics= 125kHz        8bitoverflow=  488.28Hz     16bit=   1.907Hz
    00100 // 4 = CLOCK/256    tics= 31250Hz       8bitoverflow=  122.07Hz     16bit=  0.477Hz
    00101 // 5 = CLOCK/1024   tics= 7812.5Hz      8bitoverflow=   30.52Hz     16bit=   0.119Hz
    00102 // 6 = External Clock on T(x) pin (falling edge)
    00103 // 7 = External Clock on T(x) pin (rising edge)
    00104
    00105 // for 4MHz crystal
    00106 // 0 = STOP (Timer not counting)
    00107 // 1 = CLOCK        tics= 4MHz          8bitoverflow= 15625Hz       16bit=  61.035Hz
    00108 // 2 = CLOCK/8      tics= 500kHz        8bitoverflow= 1953.125Hz    16bit=   7.629Hz
    00109 // 3 = CLOCK/64     tics= 62500Hz       8bitoverflow=  244.141Hz    16bit=   0.954Hz
    00110 // 4 = CLOCK/256    tics= 15625Hz       8bitoverflow=   61.035Hz    16bit=   0.238Hz
    00111 // 5 = CLOCK/1024   tics= 3906.25Hz     8bitoverflow=   15.259Hz    16bit=   0.060Hz
    00112 // 6 = External Clock on T(x) pin (falling edge)
    00113 // 7 = External Clock on T(x) pin (rising edge)
    00114
    00115 // for 3.69MHz crystal
    00116 // 0 = STOP (Timer not counting)
    00117 // 1 = CLOCK        tics= 3.69MHz       8bitoverflow= 14414Hz       16bit=  56.304Hz
    00118 // 2 = CLOCK/8      tics= 461250Hz      8bitoverflow= 1801.758Hz    16bit=   7.038Hz
    00119 // 3 = CLOCK/64     tics= 57625.25Hz    8bitoverflow=  225.220Hz    16bit=   0.880Hz
    00120 // 4 = CLOCK/256    tics= 14414.063Hz   8bitoverflow=   56.305Hz    16bit=   0.220Hz
    00121 // 5 = CLOCK/1024   tics=  3603.516Hz   8bitoverflow=   14.076Hz    16bit=   0.055Hz
    00122 // 6 = External Clock on T(x) pin (falling edge)
    00123 // 7 = External Clock on T(x) pin (rising edge)
    00124
    00125 // for 32.768KHz crystal on timer 2 (use for real-time clock)
    00126 // 0 = STOP
    00127 // 1 = CLOCK        tics= 32.768kHz     8bitoverflow= 128Hz
    00128 // 2 = CLOCK/8      tics= 4096kHz       8bitoverflow=  16Hz
    00129 // 3 = CLOCK/32     tics= 1024kHz       8bitoverflow=   4Hz
    00130 // 4 = CLOCK/64     tics= 512Hz         8bitoverflow=   2Hz
    00131 // 5 = CLOCK/128    tics= 256Hz         8bitoverflow=   1Hz
    00132 // 6 = CLOCK/256    tics= 128Hz         8bitoverflow=   0.5Hz
    00133 // 7 = CLOCK/1024   tics= 32Hz          8bitoverflow=   0.125Hz
    00134
    00135 #define TIMER_CLK_STOP          0x00    ///< Timer Stopped
    00136 #define TIMER_CLK_DIV1          0x01    ///< Timer clocked at F_CPU
    00137 #define TIMER_CLK_DIV8          0x02    ///< Timer clocked at F_CPU/8
    00138 #define TIMER_CLK_DIV64         0x03    ///< Timer clocked at F_CPU/64
    00139 #define TIMER_CLK_DIV256        0x04    ///< Timer clocked at F_CPU/256
    00140 #define TIMER_CLK_DIV1024       0x05    ///< Timer clocked at F_CPU/1024
    00141 #define TIMER_CLK_T_FALL        0x06    ///< Timer clocked at T falling edge
    00142 #define TIMER_CLK_T_RISE        0x07    ///< Timer clocked at T rising edge
    00143 #define TIMER_PRESCALE_MASK     0x07    ///< Timer Prescaler Bit-Mask
    00144
    00145 #define TIMERRTC_CLK_STOP       0x00    ///< RTC Timer Stopped
    00146 #define TIMERRTC_CLK_DIV1       0x01    ///< RTC Timer clocked at F_CPU
    00147 #define TIMERRTC_CLK_DIV8       0x02    ///< RTC Timer clocked at F_CPU/8
    00148 #define TIMERRTC_CLK_DIV32      0x03    ///< RTC Timer clocked at F_CPU/32
    00149 #define TIMERRTC_CLK_DIV64      0x04    ///< RTC Timer clocked at F_CPU/64
    00150 #define TIMERRTC_CLK_DIV128     0x05    ///< RTC Timer clocked at F_CPU/128
    00151 #define TIMERRTC_CLK_DIV256     0x06    ///< RTC Timer clocked at F_CPU/256
    00152 #define TIMERRTC_CLK_DIV1024    0x07    ///< RTC Timer clocked at F_CPU/1024
    00153 #define TIMERRTC_PRESCALE_MASK  0x07    ///< RTC Timer Prescaler Bit-Mask
    00154
    00155 // default prescale settings for the timers
    00156 // these settings are applied when you call
    00157 // timerInit or any of the timer<x>Init
    00158 #define TIMER0PRESCALE      TIMER_CLK_DIV8      ///< timer 0 prescaler default
    00159 #define TIMER1PRESCALE      TIMER_CLK_DIV64     ///< timer 1 prescaler default
    00160 #define TIMER2PRESCALE      TIMERRTC_CLK_DIV64  ///< timer 2 prescaler default
    00161
    00162 // interrupt macros for attaching user functions to timer interrupts
    00163 // use these with timerAttach( intNum, function )
    00164 #define TIMER0OVERFLOW_INT          0
    00165 #define TIMER1OVERFLOW_INT          1
    00166 #define TIMER1OUTCOMPAREA_INT       2
    00167 #define TIMER1OUTCOMPAREB_INT       3
    00168 #define TIMER1INPUTCAPTURE_INT      4
    00169 #define TIMER2OVERFLOW_INT          5
    00170 #define TIMER2OUTCOMPARE_INT        6
    00171 #ifdef OCR0 // for processors that support output compare on Timer0
    00172 #define TIMER0OUTCOMPARE_INT        7
    00173 #define TIMER_NUM_INTERRUPTS        8
    00174 #else
    00175 #define TIMER_NUM_INTERRUPTS        7
    00176 #endif
    00177
    00178 // default type of interrupt handler to use for timers
    00179 // *do not change unless you know what you're doing
    00180 // Value may be SIGNAL or INTERRUPT
    00181 #ifndef TIMER_INTERRUPT_HANDLER
    00182 #define TIMER_INTERRUPT_HANDLER     SIGNAL
    00183 #endif
    00184
    00185 // functions
    00186 #define delay       delay_us
    00187 #define delay_ms    timerPause
    00188 void delay_us(unsigned short time_us);
    00189
    00190 //! initializes timing system (all timers)
    00191 // runs all timer init functions
    00192 // sets all timers to default prescale values #defined in systimer.c
    00193 void timerInit(void);
    00194
    00195 // default initialization routines for each timer
    00196 void timer0Init(void);      ///< initialize timer0
    00197 void timer1Init(void);      ///< initialize timer1
    00198 #ifdef TCNT2    // support timer2 only if it exists
    00199 void timer2Init(void);      ///< initialize timer2
    00200 #endif
    00201
    00202 // Clock prescaler set/get commands for each timer/counter
    00203 // For setting the prescaler, you should use one of the #defines
    00204 // above like TIMER_CLK_DIVx, where [x] is the division rate
    00205 // you want.
    00206 // When getting the current prescaler setting, the return value
    00207 // will be the [x] division value currently set.
    00208 void timer0SetPrescaler(u08 prescale);      ///< set timer0 prescaler
    00209 u16  timer0GetPrescaler(void);              ///< get timer0 prescaler
    00210 void timer1SetPrescaler(u08 prescale);      ///< set timer1 prescaler
    00211 u16  timer1GetPrescaler(void);              ///< get timer0 prescaler
    00212 #ifdef TCNT2    // support timer2 only if it exists
    00213 void timer2SetPrescaler(u08 prescale);      ///< set timer2 prescaler
    00214 u16  timer2GetPrescaler(void);              ///< get timer2 prescaler
    00215 #endif
    00216
    00217
    00218 // TimerAttach and Detach commands
    00219 //      These functions allow the attachment (or detachment) of any user function
    00220 //      to a timer interrupt.  "Attaching" one of your own functions to a timer
    00221 //      interrupt means that it will be called whenever that interrupt happens.
    00222 //      Using attach is better than rewriting the actual INTERRUPT() function
    00223 //      because your code will still work and be compatible if the timer library
    00224 //      is updated.  Also, using Attach allows your code and any predefined timer
    00225 //      code to work together and at the same time.  (ie. "attaching" your own
    00226 //      function to the timer0 overflow doesn't prevent timerPause from working,
    00227 //      but rather allows you to share the interrupt.)
    00228 //
    00229 //      timerAttach(TIMER1OVERFLOW_INT, myOverflowFunction);
    00230 //      timerDetach(TIMER1OVERFLOW_INT)
    00231 //
    00232 //      timerAttach causes the myOverflowFunction() to be attached, and therefore
    00233 //      execute, whenever an overflow on timer1 occurs.  timerDetach removes the
    00234 //      association and executes no user function when the interrupt occurs.
    00235 //      myOverflowFunction must be defined with no return value and no arguments:
    00236 //
    00237 //      void myOverflowFunction(void) { ... }
    00238
    00239 //! Attach a user function to a timer interrupt
    00240 void timerAttach(u08 interruptNum, void (*userFunc)(void) );
    00241 //! Detach a user function from a timer interrupt
    00242 void timerDetach(u08 interruptNum);
    00243
    00244
    00245 // timing commands
    00246 /// A timer-based delay/pause function
    00247 /// @param pause_ms Number of integer milliseconds to wait.
    00248 void timerPause(unsigned short pause_ms);
    00249
    00250 // overflow counters
    00251 void timer0ClearOverflowCount(void);    ///< Clear timer0's overflow counter.
    00252 long timer0GetOverflowCount(void);      ///< read timer0's overflow counter
    00253 #ifdef TCNT2    // support timer2 only if it exists
    00254 void timer2ClearOverflowCount(void);    ///< clear timer2's overflow counter
    00255 long timer2GetOverflowCount(void);      ///< read timer0's overflow counter
    00256 #endif
    00257
    00258 /// @defgroup timerpwm Timer PWM Commands
    00259 /// @ingroup timer
    00260 /// These commands control PWM functionality on timer1
    00261 // PWM initialization and set commands for timer1
    00262 // timer1PWMInit()
    00263 //      configures the timer1 hardware for PWM mode on pins OC1A and OC1B.
    00264 //      bitRes should be 8,9,or 10 for 8,9,or 10bit PWM resolution
    00265 //
    00266 // timer1PWMOff()
    00267 //      turns off all timer1 PWM output and set timer mode to normal state
    00268 //
    00269 // timer1PWMAOn() and timer1PWMBOn()
    00270 //      turn on output of PWM signals to OC1A or OC1B pins
    00271 //      NOTE: Until you define the OC1A and OC1B pins as outputs, and run
    00272 //      this "on" command, no PWM output will be output
    00273 //
    00274 // timer1PWMAOff() and timer1PWMBOff()
    00275 //      turn off output of PWM signals to OC1A or OC1B pins
    00276 //
    00277 // timer1PWMASet() and timer1PWMBSet()
    00278 //      sets the PWM duty cycle for each channel
    00279 //  NOTE:   <pwmDuty> should be in the range 0-255 for 8bit PWM
    00280 //          <pwmDuty> should be in the range 0-511 for 9bit PWM
    00281 //          <pwmDuty> should be in the range 0-1023 for 10bit PWM
    00282 // NOTE: the PWM frequency can be controlled in increments by setting the
    00283 //          prescaler for timer1
    00284 //@{
    00285
    00286
    00287 /// Enter standard PWM Mode on timer1.
    00288 /// \param bitRes   indicates the period/resolution to use for PWM output in timer bits.
    00289 ///                     Must be either 8, 9, or 10 bits corresponding to PWM periods of 256, 512, or 1024 timer tics.
    00290 void timer1PWMInit(u08 bitRes);
    00291
    00292 /// Enter PWM Mode on timer1 with a specific top-count value.
    00293 /// \param topcount indicates the desired PWM period in timer tics.
    00294 ///                     Can be a number between 1 and 65535 (16-bit).
    00295 void timer1PWMInitICR(u16 topcount);
    00296
    00297 /// Turn off all timer1 PWM output and set timer mode to normal.
    00298 void timer1PWMOff(void);
    00299
    00300 /// Turn on/off Timer1 PWM outputs.
    00301 void timer1PWMAOn(void);            ///< Turn on timer1 Channel A (OC1A) PWM output.
    00302 void timer1PWMBOn(void);            ///< Turn on timer1 Channel B (OC1B) PWM output.
    00303 void timer1PWMAOff(void);           ///< turn off timer1 Channel A (OC1A) PWM output
    00304 void timer1PWMBOff(void);           ///< turn off timer1 Channel B (OC1B) PWM output
    00305
    00306 void timer1PWMASet(u16 pwmDuty);    ///< set duty of timer1 Channel A (OC1A) PWM output
    00307 void timer1PWMBSet(u16 pwmDuty);    ///< set duty of timer1 Channel B (OC1B) PWM output
    00308
    00309 //@}
    00310 //@}
    00311
    00312 // Pulse generation commands have been moved to the pulse.c library
    00313
    00314 #endif