/* * Copyright (C) 2014-2015 Freie Universität Berlin * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level * directory for more details. */ /** * @defgroup drivers_periph_timer Timer * @ingroup drivers_periph * @brief 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. * * @{ * @file * @brief Low-level timer peripheral driver interface definitions * * @author Hauke Petersen */ #ifndef PERIPH_TIMER_H #define PERIPH_TIMER_H #include #include #include "periph_cpu.h" /** @todo remove dev_enums.h include once all platforms are ported to the updated periph interface */ #include "periph/dev_enums.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Default timer definition macro * * Overwrite this in your CPUs periph_cpu.h file if needed */ #ifndef TIMER_DEV #define TIMER_DEV(x) (x) #endif /** * @brief Default value for timer not defined */ #ifndef TIMER_UNDEF #define TIMER_UNDEF (UINT_MAX) #endif /** * @brief Default timer type * * We chose the name of tim_t here to avoid naming clashes with other libraries * and vendor device header. */ #ifndef HAVE_TIMER_T typedef unsigned int tim_t; #endif /** * @brief Reset the timer when the set() function is called * * When set, calling the timer_set_periodic() function resets the timer count value. */ #ifndef TIM_FLAG_RESET_ON_SET #define TIM_FLAG_RESET_ON_SET (0x01) #endif /** * @brief 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. */ #ifndef TIM_FLAG_RESET_ON_MATCH #define TIM_FLAG_RESET_ON_MATCH (0x02) #endif /** * @brief Signature of event callback functions triggered from interrupts * * @param[in] arg optional context for the callback * @param[in] channel timer channel that triggered the interrupt */ typedef void (*timer_cb_t)(void *arg, int channel); /** * @brief Default interrupt context entry holding callback and argument */ #ifndef HAVE_TIMER_ISR_CTX_T typedef struct { timer_cb_t cb; /**< callback executed from timer interrupt */ void *arg; /**< optional argument given to that callback */ } timer_isr_ctx_t; #endif /** * @brief 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. * * @param[in] dev the timer to initialize * @param[in] freq requested number of ticks per second * @param[in] cb this callback is called in interrupt context, the * emitting channel is passed as argument * @param[in] arg argument to the callback * * @return 0 on success * @return -1 if speed not applicable or unknown device given */ int timer_init(tim_t dev, unsigned long freq, timer_cb_t cb, void *arg); /** * @brief 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 * * @param[in] dev the timer device to set * @param[in] channel the channel to set * @param[in] timeout timeout in ticks after that the registered callback * is executed * * @return 0 on success * @return -1 on error */ int timer_set(tim_t dev, int channel, unsigned int timeout); /** * @brief Set an absolute timeout value for the given channel of the given timer * * @param[in] dev the timer device to set * @param[in] channel the channel to set * @param[in] value the absolute compare value when the callback will be * triggered * * @return 0 on success * @return -1 on error */ int timer_set_absolute(tim_t dev, int channel, unsigned int value); /** * @brief 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. * * @param[in] dev the timer device to set * @param[in] channel the channel to set * @param[in] value the absolute compare value when the callback will be * triggered * @param[in] flags options * * @return 0 on success * @return -1 on error */ int timer_set_periodic(tim_t dev, int channel, unsigned int value, uint8_t flags); /** * @brief Clear the given channel of the given timer device * * @param[in] dev the timer device to clear * @param[in] channel the channel on the given device to clear * * @return 0 on success * @return -1 on error */ int timer_clear(tim_t dev, int channel); /** * @brief Read the current value of the given timer device * * @param[in] dev the timer to read the current value from * * @return the timers current value */ unsigned int timer_read(tim_t dev); /** * @brief Start the given timer * * This function is only needed if the timer was stopped manually before. * * @param[in] dev the timer device to start */ void timer_start(tim_t dev); /** * @brief 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. * * @param[in] dev the timer to stop */ void timer_stop(tim_t dev); #ifdef __cplusplus } #endif #endif /* PERIPH_TIMER_H */ /** @} */