drivers/periph: updated the timer interface a bit

- fixed some formatting to comments fit 80 char page width
- made tim_t overridable by the CPU
- defined TIMER_DEV() and TIMER_UNDEF macros

drivers/include/periph/dev_enums.h

@@ -29,6 +29,25 @@
 extern "C" {
 #endif
 
+/**
+ * @brief   Legacy definition of timers
+ */
+enum {
+#if TIMER_0_EN
+    TIMER_0,                /**< 1st timer */
+#endif
+#if TIMER_1_EN
+    TIMER_1,                /**< 2nd timer */
+#endif
+#if TIMER_2_EN
+    TIMER_2,                /**< 3rd timer */
+#endif
+#if TIMER_3_EN
+    TIMER_3,                /**< 4th timer */
+#endif
+    TIMER_UNDEFINED,        /**< deprecated legacy undefined values */
+};
+
 /**
  * @brief   Legacy definition of GPIO pins.
  */

drivers/include/periph/timer.h

@@ -1,9 +1,9 @@
 /*
- * Copyright (C) 2014 Freie Universität Berlin
+ * Copyright (C) 2014-2015 Freie Universität Berlin
  *
- * This file is subject to the terms and conditions of the GNU Lesser General
+ * This file is subject to the terms and conditions of the GNU Lesser
- * Public License v2.1. See the file LICENSE in the top level directory for more
+ * General Public License v2.1. See the file LICENSE in the top level
- * details.
+ * directory for more details.
  */
 
 /**
@@ -18,75 +18,101 @@
  * @author      Hauke Petersen <hauke.petersen@fu-berlin.de>
  */
 
-#ifndef TIMER_H
+#ifndef PERIPH_TIMER_H
-#define TIMER_H
+#define PERIPH_TIMER_H
 
-#include "periph_conf.h"
+#include "periph_cpu.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief Definition of available timers
+ * @brief   Default timer definition macro
  *
- * Each timer is based on a hardware timer, which can further have 1 or more channels.
+ * Overwrite this in your CPUs periph_cpu.h file if needed
- * To this point 4 timers are possible, might need to be expanded for some cases.
  */
-typedef enum {
+#ifndef TIMER_DEV
-#if TIMER_0_EN
+#define TIMER_DEV(x)        (x)
-    TIMER_0 = 0,            /**< 1st timer */
 #endif
-#if TIMER_1_EN
+/** @} */
-    TIMER_1,                /**< 2nd timer */
+
+/**
+ * @brief   Default value for timer not defined
+ */
+#ifndef TIMER_UNDEF
+#define TIMER_UNDEF         (-1)
 #endif
-#if TIMER_2_EN
+
-    TIMER_2,                /**< 3rd timer */
+/**
+ * @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
-#if TIMER_3_EN
+
-    TIMER_3,                /**< 4th timer */
+/**
+ * @brief   Default interrupt context entry holding callback and argument
+ * @{
+ */
+#ifndef HAVE_TIMER_ISR_CTX_T
+typedef struct {
+    void (*cb)(int);        /**< callback executed from timer interrupt */
+    void *arg;              /**< optional argument given to that callback */
+} timer_isr_ctx_t;
 #endif
-    TIMER_UNDEFINED         /**< fall-back if no timer is defined */
+/** @} */
-} tim_t; /* named tim instead of timer to avoid conflicts with vendor libraries */
 
 /**
  * @brief Initialize the given timer
  *
- * Each timer device is running with the given speed. Each can contain one or more channels
+ * Each timer device is running with the given speed. Each can contain one or
- * as defined in periph_conf.h. The timer is configured in up-counting mode and will count
+ * more channels as defined in periph_conf.h. The timer is configured in
- * until TIMER_x_MAX_VALUE as defined in used board's periph_conf.h until overflowing.
+ * 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.
+ * The timer will be started automatically after initialization with interrupts
+ * enabled.
  *
  * @param[in] dev           the timer to initialize
  * @param[in] us_per_tick   number of us passed for one timer tick
- * @param[in] callback      this callback is called in interrupt context, the emitting channel is
+ * @param[in] callback      this callback is called in interrupt context, the
- *                          passed as argument
+ *                          emitting channel is passed as argument
  *
- * @return                  returns 0 on success, -1 if speed not applicable of unknown device given
+ * @return                  0 on success
+ * @return                  -1 if speed not applicable or unknown device given
  */
 int timer_init(tim_t dev, unsigned int us_per_tick, void (*callback)(int));
 
 /**
- * @brief Set a given timer channel for the given timer device. The callback given during
+ * @brief Set a given timer channel for the given timer device
- * initialization is called when timeout ticks have passed after calling this function
+ *
+ * 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
+ * @param[in] timeout       timeout in ticks after that the registered callback
+ *                          is executed
  *
- * @return                  1 on success, -1 on error
+ * @return                  1 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 device
+ * @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
+ * @param[in] value         the absolute compare value when the callback will be
+ *                          triggered
  *
- * @return                  1 on success, -1 on error
+ * @return                  1 on success
+ * @return                  -1 on error
  */
 int timer_set_absolute(tim_t dev, int channel, unsigned int value);
 
@@ -96,7 +122,8 @@ int timer_set_absolute(tim_t dev, int channel, unsigned int value);
  * @param[in] dev           the timer device to clear
  * @param[in] channel       the channel on the given device to clear
  *
- * @return                  1 on success, -1 on error
+ * @return                  1 on success
+ * @return                  -1 on error
  */
 int timer_clear(tim_t dev, int channel);
 
@@ -110,14 +137,18 @@ int timer_clear(tim_t dev, int channel);
 unsigned int timer_read(tim_t dev);
 
 /**
- * @brief Start the given timer. This function is only needed if the timer was stopped manually before
+ * @brief Start the given timer
+ *
+ * This function is only needed if the timer was stopped manually before.
  *
  * @param[in] dev           the timer device to stop
  */
 void timer_start(tim_t dev);
 
 /**
- * @brief Stop the given timer - this will effect all of the timer's channels
+ * @brief Stop the given timer
+ *
+ * This will effect all of the timer's channels.
  *
  * @param[in] dev           the timer to stop
  */
@@ -140,8 +171,9 @@ void timer_irq_disable(tim_t dev);
 /**
  * @brief Reset the up-counting value to zero for the given timer
  *
- * Note that this function effects all currently set channels and it can lead to non-deterministic timeouts
+ * Note that this function effects all currently set channels and it can lead to
- * if any channel is active when this function is called.
+ * non-deterministic timeouts if any channel is active when this function is
+ * called.
  *
  * @param[in] dev           the timer to reset
  */
@@ -151,5 +183,5 @@ void timer_reset(tim_t dev);
 }
 #endif
 
-#endif /* TIMER_H */
+#endif /* PERIPH_TIMER_H */
 /** @} */