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, Joakim