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.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. More...

#define	TIMER_UNDEF (UINT_MAX)
	Default value for timer not defined.

#define	TIM_FLAG_RESET_ON_SET (0x01)
	Reset the timer when the set() function is called. More...

#define	TIM_FLAG_RESET_ON_MATCH (0x02)
	Reset the timer on match. More...

Typedefs
typedef unsigned int	tim_t
	Default timer type. More...

typedef void(*	timer_cb_t) (void *arg, int channel)
	Signature of event callback functions triggered from interrupts. More...

Functions
int	timer_init (tim_t dev, uint32_t freq, timer_cb_t cb, void *arg)
	Initialize the given timer. More...

int	timer_set (tim_t dev, int channel, unsigned int timeout)
	Set a given timer channel for the given timer device. More...

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. More...

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. More...

int	timer_clear (tim_t dev, int channel)
	Clear the given channel of the given timer device. More...

unsigned int	timer_read (tim_t dev)
	Read the current value of the given timer device. More...

void	timer_start (tim_t dev)
	Start the given timer. More...

void	timer_stop (tim_t dev)
	Stop the given timer. More...

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 89 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 78 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 52 of file timer.h.

Typedef Documentation

◆ tim_t

typedef unsigned int 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 69 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 98 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_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

Detailed Description

(Low-) Power Implications

Files

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ TIM_FLAG_RESET_ON_MATCH

◆ TIM_FLAG_RESET_ON_SET

◆ TIMER_DEV

Typedef Documentation

◆ tim_t

◆ timer_cb_t

Function Documentation

◆ timer_clear()

◆ timer_init()

◆ timer_read()

◆ timer_set()

◆ timer_set_absolute()

◆ timer_set_periodic()

◆ timer_start()

◆ timer_stop()