Timer

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]	arg	optional context for the callback
[in]	channel	timer 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]	dev	the timer device to clear
[in]	channel	the 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]	dev	the timer to initialize
[in]	freq	requested number of ticks per second
[in]	cb	this callback is called in interrupt context, the emitting channel is passed as argument
[in]	arg	argument 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)) {};

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

dev	Timer to get the next supported frequency of
index	Index of the frequency to get

Returns

The index highest frequency supported by the timer

Return values

0	index 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 = 0; (freq = timer_query_freqs(dev, i)); i++) {
    work_with_frequency(freq);
}

Or alternatively:

for (uword_t i = 0; i < timer_query_freqs_numof(dev); i++) {
    work_with_frequency(timer_query_freqs(dev, i));
}

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]

dev

the 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]	dev	the timer device to set
[in]	channel	the channel to set
[in]	timeout	timeout 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]	dev	the timer device to set
[in]	channel	the channel to set
[in]	value	the 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]	dev	the timer device to set
[in]	channel	the channel to set
[in]	value	the absolute compare value when the callback will be triggered
[in]	flags	options

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]

dev

the 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]

dev

the timer to stop