[riot-devel] Clarification request: periph_timer behaviour

Joakim NohlgÄrd joakim.nohlgard at eistec.se
Thu Feb 1 13:25:00 CET 2018

Hi developers,
I have some questions about the details of the expected behaviour of
the periph_timer interface with regards to stopped timers:

timer_init: Should an already initialized and started timer be reset
to zero and timer targets cleared when this is called?

timer_set, timer_set_absolute, timer_clear: should these functions
start the underlying timer if it is stopped when they are called?

timer_read: Is this function expected to show the correct count when
the underlying timer is stopped (that is, the count that the timer was
on when it was stopped)?

timer_stop: Should this function clear the currently set target time
or should the timer continue counting towards the target where it left
off when timer_start is called again?

timer_start: Should the count towards a target time continue where it
was before the timer was stopped or do we start over from the start?
e.g. timer_set(3000), when the count is at 2000 we call timer_stop(),
then timer_start, do we need to wait 3000 ticks until the target is
hit or do we wait 1000 ticks?

Can the count returned by timer_read ever be reset to zero (or
otherwise modified) from the API, without calling timer_init?

in the documentation for timer_init it says:
"The timer will be started automatically after initialization *with
interrupts enabled.*" (emphasis mine)
What interrupts are expected to occur when there is no target time set
yet? Should the callback be called when the timer overflows?
My interpretation of this sentence is that the "with interrupts
enabled" is a leftover from an older iteration of the API when we had
the timer_enable_irq/disable_irq functions, and I don't think the
application will expect the callback to be called whenever the timer
overflows, because that would make it more difficult to handle the
callbacks in the application.

I can make a PR with some doc improvements once we reach a consensus
regarding the above questions.

Best regards,

More information about the devel mailing list