Loading...
Searching...
No Matches

Low-level timer peripheral driver. More...

Detailed Description

Low-level timer peripheral driver.

(Low-) Power Implications

After calling timer_init(), the underlying hardware timer should be powered on and running. When a timer is explicitly stopped by calling timer_stop(), the timer should be stopped and powered down (e.g. by peripheral clock gating). Once the timer is started again (by calling timer_start()), it should transparently continue its previously configured operation.

While the timer is active, the implementation might need to block certain power modes on specific CPU implementation.

Files

file  timer_arch.h
 CPU specific part of the timer API.
 
file  timer.h
 Low-level timer peripheral driver interface definitions.
 

Data Structures

struct  timer_isr_ctx_t
 Default interrupt context entry holding callback and argument. More...
 

Macros

#define TIMER_DEV(x)   (x)
 Default timer definition macro.
 
#define TIMER_UNDEF   (UINT_FAST8_MAX)
 Default value for timer not defined.
 
#define TIM_FLAG_RESET_ON_SET   (0x01)
 Reset the timer when the set() function is called.
 
#define TIM_FLAG_RESET_ON_MATCH   (0x02)
 Reset the timer on match.
 
#define TIM_FLAG_SET_STOPPED   (0x04)
 Keep the timer stopped after setting alarm.
 

Typedefs

typedef uint_fast8_t tim_t
 Default timer type.
 
typedef void(* timer_cb_t) (void *arg, int channel)
 Signature of event callback functions triggered from interrupts.
 

Functions

int timer_init (tim_t dev, uint32_t freq, timer_cb_t cb, void *arg)
 Initialize the given timer.
 
int timer_set (tim_t dev, int channel, unsigned int timeout)
 Set a given timer channel for the given timer device.
 
int timer_set_absolute (tim_t dev, int channel, unsigned int value)
 Set an absolute timeout value for the given channel of the given timer.
 
int timer_set_periodic (tim_t dev, int channel, unsigned int value, uint8_t flags)
 Set an absolute timeout value for the given channel of the given timer.
 
int timer_clear (tim_t dev, int channel)
 Clear the given channel of the given timer device.
 
unsigned int timer_read (tim_t dev)
 Read the current value of the given timer device.
 
void timer_start (tim_t dev)
 Start the given timer.
 
void timer_stop (tim_t dev)
 Stop the given timer.
 
uword_t timer_query_freqs_numof (tim_t dev)
 Get the number of different frequencies supported by the given timer.
 
uword_t timer_query_channel_numof (tim_t dev)
 Get the number of timer channels for the given timer.
 
uint32_t timer_query_freqs (tim_t dev, uword_t index)
 Iterate over supported frequencies.
 
bool timer_poll_channel (tim_t dev, int channel)
 Check whether a compare channel has matched.
 

Macro Definition Documentation

◆ TIM_FLAG_RESET_ON_MATCH

#define TIM_FLAG_RESET_ON_MATCH   (0x02)

Reset the timer on match.

When set, a match on this channel will reset the timer count value. When set on multiple channels, only the channel with the lowest match value will be reached.

Definition at line 91 of file timer.h.

◆ TIM_FLAG_RESET_ON_SET

#define TIM_FLAG_RESET_ON_SET   (0x01)

Reset the timer when the set() function is called.

When set, calling the timer_set_periodic() function resets the timer count value.

Definition at line 80 of file timer.h.

◆ TIM_FLAG_SET_STOPPED

#define TIM_FLAG_SET_STOPPED   (0x04)

Keep the timer stopped after setting alarm.

When set, the timer will remained stopped after a timer_set_periodic() and can be started manually with timer_start().

Definition at line 101 of file timer.h.

◆ TIMER_DEV

#define TIMER_DEV (   x)    (x)

Default timer definition macro.

Overwrite this in your CPUs periph_cpu.h file if needed

Definition at line 54 of file timer.h.

◆ TIMER_UNDEF

#define TIMER_UNDEF   (UINT_FAST8_MAX)

Default value for timer not defined.

Definition at line 61 of file timer.h.

Typedef Documentation

◆ tim_t

typedef uint_fast8_t tim_t

Default timer type.

We chose the name of tim_t here to avoid naming clashes with other libraries and vendor device header.

Definition at line 71 of file timer.h.

◆ timer_cb_t

typedef void(* timer_cb_t) (void *arg, int channel)

Signature of event callback functions triggered from interrupts.

Parameters
[in]argoptional context for the callback
[in]channeltimer channel that triggered the interrupt

Definition at line 110 of file timer.h.

Function Documentation

◆ timer_clear()

int timer_clear ( tim_t  dev,
int  channel 
)

Clear the given channel of the given timer device.

Parameters
[in]devthe timer device to clear
[in]channelthe channel on the given device to clear
Returns
0 on success
-1 on error

◆ timer_init()

int timer_init ( tim_t  dev,
uint32_t  freq,
timer_cb_t  cb,
void *  arg 
)

Initialize the given timer.

Each timer device is running with the given speed. Each can contain one or more channels as defined in periph_conf.h. The timer is configured in up-counting mode and will count until TIMER_x_MAX_VALUE as defined in used board's periph_conf.h until overflowing.

The timer will be started automatically after initialization with interrupts enabled.

Parameters
[in]devthe timer to initialize
[in]freqrequested number of ticks per second
[in]cbthis callback is called in interrupt context, the emitting channel is passed as argument
[in]argargument to the callback
Returns
0 on success
-1 if speed not applicable or unknown device given

◆ timer_poll_channel()

bool timer_poll_channel ( tim_t  dev,
int  channel 
)

Check whether a compare channel has matched.

Returns
true once after the channel has matched.

It is currently not defined whether this keeps returning true after a channel has been polled until that channel is set, or whether later calls return false.

This is typically used in spin loops that wait for a timer's completion:

while (!timer_poll_channel(tim, chan)) {};
bool timer_poll_channel(tim_t dev, int channel)
Check whether a compare channel has matched.

This function is only available on platforms that implement the periph_timer_poll peripheral in addition to periph_timer.

◆ timer_query_channel_numof()

uword_t timer_query_channel_numof ( tim_t  dev)

Get the number of timer channels for the given timer.

This function is marked with attribute pure to tell the compiler that this function has no side affects and will return the same value when called with the same timer as parameter.

There is a weak default implementation that returns the value of TIMER_CHANNEL_NUMOF. For some MCUs the number of supported channels depends on dev - those are expected to provide there own implementation of this function.

◆ timer_query_freqs()

uint32_t timer_query_freqs ( tim_t  dev,
uword_t  index 
)

Iterate over supported frequencies.

Parameters
devTimer to get the next supported frequency of
indexIndex of the frequency to get
Returns
The index highest frequency supported by the timer
Return values
0index is too high
Note
Add FEATURES_REQUIRED += periph_timer_query_freqs to your Makefile.

When called with a value of 0 for index, the highest supported frequency is returned. For a value 1 the second highest is returned, and so on. For values out of range, 0 is returned. A program hence can iterate over all supported frequencies using:

uint32_t freq:
for (uword_t i; (freq = timer_query_freqs(dev, i)); i++) {
work_with_frequency(freq);
}
uint32_t timer_query_freqs(tim_t dev, uword_t index)
Iterate over supported frequencies.
uint< NUM > _t uword_t
Word sized unsigned integer.

Or alternatively:

for (uword_t i; i < timer_query_freqs_numof(dev); i++) {
work_with_frequency(timer_query_freqs(dev, i));
}
uword_t timer_query_freqs_numof(tim_t dev)
Get the number of different frequencies supported by the given timer.

◆ timer_query_freqs_numof()

uword_t timer_query_freqs_numof ( tim_t  dev)

Get the number of different frequencies supported by the given timer.

If calling timer_query_freqs_numof for the same timer with an index smaller this number, it hence MUST return a frequency (and not zero).

This function is marked with attribute pure to tell the compiler that this function has no side affects and will return the same value when called with the same parameter. (E.g. to not call this function in every loop iteration when iterating over all supported frequencies.)

◆ timer_read()

unsigned int timer_read ( tim_t  dev)

Read the current value of the given timer device.

Parameters
[in]devthe timer to read the current value from
Returns
the timers current value

◆ timer_set()

int timer_set ( tim_t  dev,
int  channel,
unsigned int  timeout 
)

Set a given timer channel for the given timer device.

The callback given during initialization is called when timeout ticks have passed after calling this function

Parameters
[in]devthe timer device to set
[in]channelthe channel to set
[in]timeouttimeout in ticks after that the registered callback is executed
Returns
0 on success
-1 on error

◆ timer_set_absolute()

int timer_set_absolute ( tim_t  dev,
int  channel,
unsigned int  value 
)

Set an absolute timeout value for the given channel of the given timer.

Timers that are less wide than unsigned int accept and truncate overflown values.

Parameters
[in]devthe timer device to set
[in]channelthe channel to set
[in]valuethe absolute compare value when the callback will be triggered
Returns
0 on success
-1 on error

◆ timer_set_periodic()

int timer_set_periodic ( tim_t  dev,
int  channel,
unsigned int  value,
uint8_t  flags 
)

Set an absolute timeout value for the given channel of the given timer.

The timeout will be called periodically for each iteration.

Note
Only one channel with TIM_FLAG_RESET_ON_MATCH can be active. Some platforms (Atmel) only allow to use the first channel as TOP value.
Needs to be enabled with FEATURES_REQUIRED += periph_timer_periodic.
Parameters
[in]devthe timer device to set
[in]channelthe channel to set
[in]valuethe absolute compare value when the callback will be triggered
[in]flagsoptions
Returns
0 on success
-1 on error

◆ timer_start()

void timer_start ( tim_t  dev)

Start the given timer.

This function is only needed if the timer was stopped manually before.

Parameters
[in]devthe timer device to start

◆ timer_stop()

void timer_stop ( tim_t  dev)

Stop the given timer.

This will effect all of the timer's channels.

When the timer is stopped, the underlying timer peripheral should be completely powered off.

Parameters
[in]devthe timer to stop