Examination of the Arduino millis() Function

Clock Cycles

First, some background information. The typical Arduino has a 16MHz oscillator. A 16MHz oscillator results in the microcontroller having a clock cycle once every 16-millionth of a second. A clock cycle is roughly the time it takes for one instruction cycle (there are exceptions). Therefore, on the Arduino, each clock cycle is 1/16,000,000 of a second, which is:

• 0.0000000625 seconds
• 0.0000625 milliseconds (ms)
• 0.0625 microseconds (µs)

Prescaler

The Atmel ATmega168/328 based Arduino has 3 timers, of which the millis function uses the microcontroller’s Timer #0. Before utilizing any timer, several registers must be set. If we examine how the Arduino sets up Timer #0, we find it sets a prescale factor of 64 (from the wiring.c file):

// this combination is for the standard 168/328/1280/2560
sbi(TCCR0B, CS01);
sbi(TCCR0B, CS00);

ATMEL ATMega328 Datasheet page 111 specifies the Timer #0 prescale bits:

While technically a prescaler divides the timer, I like to think of it as a multiplier. For example, with an Arduino clock cycle occurring every 1/16,000,000 of a second, applying a 64 prescale means Timer #0 is ticking at 64 times the base oscillator rate, or 64*1/16,000,000, which is every:

• 0.000004 seconds
• 0.004 ms
• 4 µs

Timer Counter

Timer #0 has an 8-bit counter register (TCNT0) which is incremented by 1 every 0.004 milliseconds. The maximum 8-bit value the timer can hold is 255 (hexadecimal 0xFF). Therefore, when the timer attempts to count to 256, it “rolls over” to 0. This “roll over” is called an “overflow” in microcontroller parlance. Take note the counter ticks off 256 times, not 255 times (because 0 + 255 = 256).

Overflow Interrupt

The Timer #0 overflow can trigger an interrupt. When an interrupt occurs, the Arduino halts execution of the running program and then calls the specific interrupt subroutine. This subroutine is typically called an “interrupt handler.” The interrupt handler that we are interested in is called the Timer #0 Overflow Interrupt. The Arduino code enables the Timer #0 overflow interrupt (again, found inside the wiring.c file):

// enable timer 0 overflow interrupt
sbi(TIMSK0, TOIE0);

ATMEL ATMega328 Datasheet page 112 specifies the Timer #0 interrupt enable bit:

Therefore a Timer #0 “overflow interrupt” occurs each time the timer’s counter (TCNT0) rolls over. Taking the above math into account, this occurs every 1/16,000,000(oscillator) * 64(prescale) * 256(roll over) = 0.001024 seconds, or every 1.024 ms. It’s important to realize the interrupt doesn’t occur exactly each millisecond.

Microcontrollers Don’t Like Fractions

Next we need to examine the Timer #0 interrupt handler, which is made slightly more complicated because of the decimal part of the 1.024ms roll-over period. But first, let’s do some math so we can substitute these numbers for the following MACROs (these macros are embedded inside several Arduino hardware files):

#define clockCyclesPerMicrosecond() ( F_CPU / 1000000L )
#define clockCyclesToMicroseconds (a) ( ((a) * 1000L) / (F_CPU / 1000L) )
#define MICROSECONDS_PER_TIMER0_OVERFLOW (clockCyclesToMicroseconds(64 * 256))
// the whole number of milliseconds per timer0 overflow
#define MILLIS_INC (MICROSECONDS_PER_TIMER0_OVERFLOW / 1000)
// the fractional number of milliseconds per timer0 overflow. we shift right
// by three to fit these numbers into a byte. (for the clock speeds we care
// about - 8 and 16 MHz - this doesn't lose precision.)
#define FRACT_INC ((MICROSECONDS_PER_TIMER0_OVERFLOW % 1000) >> 3)
#define FRACT_MAX (1000 >> 3)

F_CPU is the oscillator frequency, and is defined during sketch compilation. We already know this is 16MHz or 16,000,000, which makes:

clockCyclesPerMicrosecond = 16000000/1000000 = 16
MICROSECONDS_PER_TIMER0_OVERFLOW = ((64*256)*1000)/(16000000/1000) = 1024
MILLIS_INC = 1024/1000 = 1.024 = 1 (integer)
FRAC_INC = (1024%1000 >> 3) = (24 >> 3) = 3
FRAC_MAX = (1000 >> 3) = 125


Timer #0 Overflow Interrupt Handler

Here is the Timer #0 overflow interrupt handler with the above substitutions made and a little cleanup just to make the code easier to understand (the original code is listed at the bottom of the post):

SIGNAL(TIMER0_OVF_vect) {
  timer0_millis += 1;
  timer0_fract += 3;
  if (timer0_fract >= 125) {
    timer0_fract -= 125;
    timer0_millis += 1;
  }
  timer0_overflow_count++;
}

Therefore, this overflow handler increments the value of timer0_millis every 1.024ms and then adds another increment to timer0_millis (catches up, if you will) every time timer0_fract is greater than 125. Hence, timer0_millis accounts for the missing 0.024ms from every “timer overflow” at intervals of 125/3 = 41.67ms. Which means timer0_millis accumulates an error of 0.024ms each time it executes (every overflow), until the error approaches 1ms. At which time, timer0_millis jumps by 2 and corrects itself.

To assist in understanding how this works, the following table demonstrates the internal values of the overflow handler during each iteration:

millis()

Finally, the millis() function merely returns the value of timer0_millis (again, I cleaned up the function to make it easier to understand, the actual function is listed below):

unsigned long millis() {
  return timer0_millis;
}

The Full Arduino Functions:

SIGNAL(TIMER0_OVF_vect)
{
	// copy these to local variables so they can be stored in registers
	// (volatile variables must be read from memory on every access)
	unsigned long m = timer0_millis;
	unsigned char f = timer0_fract;

	m += MILLIS_INC;
	f += FRACT_INC;
	if (f >= FRACT_MAX) {
		f -= FRACT_MAX;
		m += 1;
	}

	timer0_fract = f;
	timer0_millis = m;
	timer0_overflow_count++;
}
   
unsigned long millis()
{
	unsigned long m;
	uint8_t oldSREG = SREG;

	// disable interrupts while we read timer0_millis or we might get an
	// inconsistent value (e.g. in the middle of a write to timer0_millis)
	cli();
	m = timer0_millis;
	SREG = oldSREG;

	return m;
}

Next we’ll look at the micros() function.

If you are concerned about millis overflow when using millis to time intervals, please see this.

Do you wish you could read and write inline assembly code for the Arduino? Check out the book with greatly expanded coverage!

[click on the image]