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, unsigned long 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 The timeout will be called periodically for each iteration. 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 90 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 79 of file timer.h.

◆ TIMER_DEV

#define TIMER_DEV (   x)    (x)

Default timer definition macro.

Todo:
remove dev_enums.h include once all platforms are ported to the updated periph interface

Overwrite this in your CPUs periph_cpu.h file if needed

Definition at line 53 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 70 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 99 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,
unsigned long  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_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.

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.

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