tmr.h : Polled software timers
[/general : General utility files & modules]

Non-blocking software timers that have to be polled to determine if they have expired. More...

Data Structures
struct	tmr_t
	Structure to track state of a timer. More...
Defines
#define	TMR_TICKS_PER_SEC   SYSTMR_TICKS_PER_SEC
	The number of timer ticks per second.
#define	TMR_MS_TO_TICKS(delay_in_ms)   DIV_ROUND((delay_in_ms)*TMR_TICKS_PER_SEC,1000ul)
	Macro used to convert a timeout in milliseconds to timer ticks.
Typedefs
typedef systmr_ticks_t	tmr_ticks_t
	Size definition of the tick counter.
Enumerations
enum	tmr_state_t
	Timer state.
Functions
void	tmr_start (tmr_t *tmr, const tmr_ticks_t delay_in_ticks)
	Start a timer.
bool_t	tmr_has_expired (tmr_t *tmr)
	See if a timer has expired.
void	tmr_stop (tmr_t *tmr)
	Stop a running timer.
void	tmr_restart (tmr_t *tmr)
	Restart a timer with the delay set with tmr_start().
void	tmr_reset (tmr_t *tmr)
	Reset a timer with the delay set with tmr_start().
void	tmr_wait (const tmr_ticks_t delay_in_ticks)
	Blocking wait for specified number of ticks.
tmr_ticks_t	tmr_ticks_elapsed (tmr_t *tmr)
	Return the number of ticks that have elapsed sinced the timer has been started.

---

Detailed Description

Files: tmr.h & tmr.c

These timers are suitable for applications that are not timing critical. A counter is incremented with each timer tick and this value is polled to determine when a timer has expired. Provision is made for counter roll-over.

This module depends on a system timer module, e.g. systmr.h : System Timer using a TMR peripheral to return a counter that is incremented with every system tick. The number of ticks per second (Hz) is defined in TMR_TICKS_PER_SEC.

Example:

#include <avr/interrupt.h>

#include "systmr.h"
#include "tmr.h"

void tmr_test(void)
{
    // Create a timer object
    tmr_t tmr;

    // Initialise PIO
    BIT_SET_HI(PORT_LED_O, BIT_LED_O);
    BIT_SET_HI(DDR_LED_O,  BIT_LED_O);
 
    // Initialise module
    systmr_init();

    // Enable global interrupts
    sei();
  
    // Start timer with a 250 ms timeout
    tmr_start(&tmr, TMR_MS_TO_TICKS(250));
    
    for(;;)
    {
        // Wait until timer has expired
        while(!tmr_has_expired(&tmr))
        {
            ;
        }

        // Restart timer
        tmr_restart(&tmr);
        
        // Toggle LED
        LED_TOGGLE();
    }
}

---

Define Documentation

#define TMR_MS_TO_TICKS

(

delay_in_ms

)

DIV_ROUND((delay_in_ms)*TMR_TICKS_PER_SEC,1000ul)

Parameters:

[in]

delay_in_ms

Delay in milliseconds

Returns:

Delay in timer ticks

Definition at line 184 of file tmr.h.

Referenced by xmodem_rx_file().

---

Function Documentation

void tmr_start	(	tmr_t *	tmr,
		const tmr_ticks_t	delay_in_ticks
	)

Parameters:

[in,out]	tmr	Pointer to a timer object
[in]	delay_in_ticks	Delay in timer ticks

Definition at line 48 of file tmr.c.

References tmr_t::delay_in_ticks, tmr_t::start_tick, tmr_t::state, and systmr_get_counter().

Referenced by tmr_wait(), and xmodem_rx_file().

{
    // Save delay in case timer is restarted
    tmr->delay_in_ticks = delay_in_ticks;

    // Store start tick
    tmr->start_tick = systmr_get_counter();

    // Set state to indicate that timer has started
    tmr->state = TMR_STARTED;
}

bool_t tmr_has_expired

(

tmr_t *

tmr

)

Parameters:

[in,out]

tmr

Pointer to a timer object

Return values:

	TRUE	timer expired
	FALSE	timer not expired or timer stopped

Definition at line 60 of file tmr.c.

References tmr_t::delay_in_ticks, tmr_t::start_tick, tmr_t::state, and systmr_get_counter().

Referenced by tmr_wait(), and xmodem_rx_file().

{
    tmr_ticks_t tick;

    // See if timer has been stopped
    if (tmr->state == TMR_STOPPED) return FALSE;

    // See if timer has already expired
    if (tmr->state == TMR_EXPIRED) return TRUE;

    // Fetch current time
    tick = systmr_get_counter();

    // Timer expire test
    if( (tick - tmr->start_tick) < tmr->delay_in_ticks )
    {
        return FALSE;
    }

    // Set state to indicate that timer has expired
    tmr->state = TMR_EXPIRED;

    return TRUE;
}

void tmr_stop

(

tmr_t *

tmr

)

Parameters:

[in,out]

tmr

Pointer to a timer object

Definition at line 85 of file tmr.c.

References tmr_t::state.

{
    // Stop timer
    tmr->state = TMR_STOPPED;
}

void tmr_restart

(

tmr_t *

tmr

)

The timer will expire from the current timer tick + tmr->delay_in_ticks.

Parameters:

[in,out]

tmr

Pointer to a timer object

Definition at line 91 of file tmr.c.

References tmr_t::start_tick, tmr_t::state, and systmr_get_counter().

{
    // Store start tick
    tmr->start_tick = systmr_get_counter();

    // Set state to indicate that timer has started
    tmr->state = TMR_STARTED;
}

void tmr_reset

(

tmr_t *

tmr

)

The timer will expire on tmr->start_tick + tmr->delay_in_ticks.

Use this function instead of tmr_restart() for periodic timers, because the frequency will not drift over time. An error may accumulate if there is a delay between tmr_has_expired() and tmr_restart(). Thus the prefered usage for a periodic timer is:

  for(;;)
  {
      // Wait until timer has expired
      while(tmr_has_expired(&tmr) == FALSE)
      {
          ;
      }
      // Reset periodic timer
      tmr_reset(&tmr);
      // Do something...
  }

Parameters:

[in,out]

tmr

Pointer to a timer object

Definition at line 100 of file tmr.c.

References tmr_t::delay_in_ticks, tmr_t::start_tick, and tmr_t::state.

{
    // Calculate and store new start tick
    tmr->start_tick += tmr->delay_in_ticks;

    // Set state to indicate that timer has started
    tmr->state = TMR_STARTED;
}

void tmr_wait

(

const tmr_ticks_t

delay_in_ticks

)

Parameters:

[in]

delay_in_ticks

Delay in timer ticks

Definition at line 109 of file tmr.c.

References tmr_has_expired(), and tmr_start().

{
    tmr_t tmr;

    tmr_start(&tmr, delay_in_ticks);

    while (!tmr_has_expired(&tmr))
    {
        ;
    }
}

tmr_ticks_t tmr_ticks_elapsed

(

tmr_t *

tmr

)

Parameters:

[in,out]

tmr

Pointer to a timer object

Returns:

tmr_ticks_t Number of ticks elapsed

Definition at line 120 of file tmr.c.

References tmr_t::start_tick, and systmr_get_counter().

{
    // Fetch current time
    tmr_ticks_t tick = systmr_get_counter();

    return (tick - tmr->start_tick);
}