Ideal Hardware Timer Setup Routine

Question

Imagine you were trying to write a C routine for an 8bit microcontroller that converted a desired timespan (be it seconds, milliseconds, hertz, etc). to the corresponding hardware timer preload value (taking into account the clock source and frequency of the timer). The goal is to make the function as easy as possible to use, with as few arguments as possible. What would this function look like?

Would you pass in a uint32_t representing the desired hertz of the timer (0 = 0Hz, 1000 = 1kHz, etc.):

void set_timer(uint32_t hz);

Would you prefer using a uint16_t representing kHz instead (0 = 0Hz, 1 = 1KHz, 10 = 10Khz)?

void set_timer(uint16_t khz);

Or would a 32bit fixed point argument be more desirable (to be able to represent fraction of hertz)?

void set_timer(q15_16_t hz);

Or would this fixed point value represent seconds instead of Hz?

void set_timer(q15_16_t sec);

Or would you use a 16bit fixed point instead of a 32bit fixed point.

Or would you even dare want to use a floating point? Or what about a half-precision float?

What do you think?

Answer 1

First I would suggest using time instead of frequency, since the latter implies that the timer is of a continuous kind. The user is often interested in a certain "one-shot" delay, when waiting for some sort of hardware to become available.

Second, uint32_t is a big NO on 8-bit microcontrollers. As soon as you use 32-bit numbers, every 8-bitter on the market will create a flood of inefficient machine code, likely with internal subroutine calls. 16 bit numbers are bad enough. Though of course, there are cases where you need high resolution accuracy and then you might have to reluctantly use large integer types.

In this case, I very much doubt that your 8-bit MCU has a 32-bit timer peripheral. De facto standard for 8-bitters is to have 16-bit hardware timers. There is no point of specifying a resolution that doesn't correspond with the hardware.

Using floating point is even worse: if you ever find yourself needing floating point accuracy on a 8-bit MCU, you most likely picked the wrong MCU for your project to begin with. (The cost argument of 8-bit vs 32-bit has been obsolete forever.)

Based on the above argument, I would suggest something like:

void set_timer (uint16_t ms);

where ms is the time in miliseconds.

The ideal case is however to calculate the needed timing in the pre-processor, then show that into a constant, which is then directly read into the timer hardware registers.

Answer 2

Generally, I use hardware timers one of two ways:

1. I set the timer to trigger an event (interrupt) at a particular frequency, and then just leave it running at that frequency; if I want to do things at various rates, I'll perform some tasks every third interrupt, some every eigth, etc. This is my most common approach for handling timing when the system is "awake".
2. For low-speed timers which need to run while the CPU is asleep, I prefer to use a free-running counter which wraps at some interval, and then set a compare register with the absolute time when the next wake-up event should occur.

On some occasions, I may use a timer to generate a "beep" frequency; in most such cases, I'll attach the timer to a hardware PWM. When generating a "beep", it's possible that I might want to specify a frequency, though more commonly I would specify a period or else an index into a table of useful frequencies held by the routine which sets things up for the beep.

For the first style of usage, the API isn't particularly relevant, since it's "set up and forget". For the beeper application, the timer API isn't relevant, since a "beep" API will often combine the timer setup with the code necessary to enable or disable the PWM. Only with the second usage is an API particularly relevant. For that, the most useful style of API would probably be "set next wakeup to occur no later than the indicated absolute time, if it isn't already scheduled sooner", with a 32-bit parameter that represents a continuous (wrapping) time, and combined with a routine which reports the current time on the same 32-bit scale. If the hardware is e.g. only a 16-bit counter, the routines should act suitably (e.g. the "read time" routine, if called at least once every 65535 ticks, should return a continuously-increasing 32-bit value; if the "set alarm" routine is used to set an alarm more than 32768 ticks in the future, it should set the alarm 32768 ticks in the future (if the requested time was e.g. 65,538 ticks in the future, the routine should notice the time is more than 65,536 ticks in the future, rather than just using the low 16 bits of the time and regarding it as two ticks in the future).

Answer 3

I personally use:

// Returns actual timer rate in Hz
uint32_t set_timer(uint32_t hz);

But in the world of constrained systems, you'll never give everybody exactly what they want. So make a routine that's simple for simple cases, and don't bother trying to make a routine that covers every potential use case -- one can just directly access the hardware for that.