From 93647306d7279316b6edeca1b2bbe43566a0d107 Mon Sep 17 00:00:00 2001
From: Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
Date: Tue, 8 Apr 2014 18:33:16 +0200
Subject: [PATCH] core/doc: complete hwtimer.h and hwtimer_arch.h
---
core/include/hwtimer.h | 67 ++++++++++++++++++++-----------------
core/include/hwtimer_arch.h | 29 +++++++++++-----
2 files changed, 57 insertions(+), 39 deletions(-)
diff --git a/core/include/hwtimer.h b/core/include/hwtimer.h
index 8b588e5525..0a92b14d34 100644
--- a/core/include/hwtimer.h
+++ b/core/include/hwtimer.h
@@ -17,8 +17,8 @@
* interrupt context and must use the shortest possible execution time (e.g.
* set a flag and trigger a worker thread).
*
- * <b>The hardware timer must not be used within applications</b>, use \ref vtimer
- * instead.
+ * <b>The hardware timer should not be used (until you know what
+ * you're doing)<b>, use \ref sys_vtimer instead.
*
* @{
*
@@ -38,15 +38,15 @@
#include "hwtimer_cpu.h"
/**
- * @def HWTIMER_SPEED
- * @brief Number of kernel timer ticks per second
+ * @brief Number of kernel timer ticks per second
+ * @def HWTIMER_SPEED
*/
#ifndef HWTIMER_SPEED
#warning "HWTIMER_SPEED undefined. Set HWTIMER_SPEED to number of ticks per second for the current architecture."
#endif
/**
- * @brief Convert microseconds to kernel timer ticks
+ * @brief Convert microseconds to kernel timer ticks
* @param[in] us number of microseconds
* @return kernel timer ticks
*/
@@ -60,22 +60,24 @@
#define HWTIMER_TICKS_TO_US(ticks) ((ticks) * (1000000L/HWTIMER_SPEED))
/**
- * @def HWTIMER_MAXTICKS
- * @brief Maximum hwtimer tick count (before overflow)
+ * @brief Maximum hwtimer tick count (before overflow)
+ * @def HWTIMER_MAXTICKS
*/
#ifndef HWTIMER_MAXTICKS
#warning "HWTIMER_MAXTICKS undefined. Set HWTIMER_MAXTICKS to maximum number of ticks countable on the current architecture."
#endif
/**
- * @brief microseconds before hwtimer overflow
+ * @brief microseconds before hwtimer overflow
*/
#define HWTIMER_OVERFLOW_MICROS() (1000000L / HWTIMER_SPEED * HWTIMER_MAXTICKS)
-typedef uint32_t timer_tick_t;
+typedef uint32_t timer_tick_t; /**< data type for hwtimer ticks */
+/**
+ * @brief initialize the hwtimer module
+ */
void hwtimer_init(void);
-void hwtimer_init_comp(uint32_t fcpu);
/**
* @brief Get the hardware time
@@ -85,51 +87,54 @@ unsigned long hwtimer_now(void);
/**
* @brief Set a kernel timer
- * @param[in] offset Offset until callback invocation in timer ticks
- * @param[in] callback Callback function
- * @param[in] ptr Argument to callback function
- * @return timer id
+ * @param[in] offset Offset until callback invocation in timer ticks
+ * @param[in] callback Callback function
+ * @param[in] ptr Argument to callback function
+ * @return timer id
*/
int hwtimer_set(unsigned long offset, void (*callback)(void*), void *ptr);
/**
* @brief Set a kernel timer
- * @param[in] absolute Absolute timer counter value for invocation of handler
- * @param[in] callback Callback function
- * @param[in] ptr Argument to callback function
- * @return timer id
+ * @param[in] absolute Absolute timer counter value for invocation of handler
+ * @param[in] callback Callback function
+ * @param[in] ptr Argument to callback function
+ * @return timer id
*/
int hwtimer_set_absolute(unsigned long absolute, void (*callback)(void*), void *ptr);
/**
* @brief Remove a kernel timer
- * @param[in] t Id of timer to remove
- * @retval 1 on success
+ * @param[in] t Id of timer to remove
+ * @return 1 on success
*/
int hwtimer_remove(int t);
/**
- * @brief Delay current thread
- * @param[in] ticks Number of kernel ticks to delay
+ * @brief Delay current thread
+ * @param[in] ticks Number of kernel ticks to delay
*/
void hwtimer_wait(unsigned long ticks);
/**
- * @brief Delay current thread, spinning. Use only in interrupts for VERY short delays!
- * @param[in] ticks Number of kernel ticks to delay
+ * @brief determine if the hwtimer module is initialized
+ * @return 1 if the hwtimer module is initialized
*/
-void hwtimer_spin(unsigned long ticks);
-
int hwtimer_active(void);
-/** @} */
+/**
+ * @brief initialize hwtimer module data structures and hardware
+ *
+ * @param[in] fcpu cpu frequency
+ */
+void hwtimer_init_comp(uint32_t fcpu);
-/* internal */
/**
- * @brief TODO
- * @internal
+ * @brief Delay current thread, spinning. Use only in interrupts for VERY short delays!
+ *
+ * @param[in] ticks Number of kernel ticks to delay
*/
-void hwtimer_cpu_init(void (*handler)(int), uint32_t fcpu);
+void hwtimer_spin(unsigned long ticks);
/** @} */
#endif /* __HWTIMER_H */
diff --git a/core/include/hwtimer_arch.h b/core/include/hwtimer_arch.h
index 3167e586ea..e533134fc4 100644
--- a/core/include/hwtimer_arch.h
+++ b/core/include/hwtimer_arch.h
@@ -17,6 +17,7 @@
* @author Thomas Hillebrandt <hillebra@inf.fu-berlin.de>
* @author Heiko Will <hwill@inf.fu-berlin.de>
* @author Kaspar Schleiser <kaspar@schleiser.de>
+ * @}
*/
#ifndef HWTIMER_ARCH_H_
@@ -25,40 +26,52 @@
#include <stdint.h>
/**
- * Initialize architecture dependent kernel timer support.
+ * @brief Initialize architecture dependent kernel timer support.
+ *
+ * @param[in] handler callback function for the interrupt handler
+ * @param[in] fcpu cpu frequency
*/
void hwtimer_arch_init(void (*handler)(int), uint32_t fcpu);
/**
- * Enable interrupts of hardware timers.
+ * @brief Enable interrupts of hardware timers.
*/
void hwtimer_arch_enable_interrupt(void);
/**
- * Disable interrupts of hardware timers.
+ * @brief Disable interrupts of hardware timers.
*/
void hwtimer_arch_disable_interrupt(void);
/**
- * Set a kernel timer to raise an interrupt after ::offset kernel timer ticks
- * from now.
+ * @brief Set a kernel timer to raise an interrupt after `offset` kernel timer
+ * ticks from now.
+ *
+ * @param[in] offset number of ticks
+ * @param[in] timer hardware timer identifier
*/
void hwtimer_arch_set(unsigned long offset, short timer);
/**
- * Set a kernel timer to raise an interrupt at specified system time.
+ * @brief Set a kernel timer to raise an interrupt at specified system time.
+ *
+ * @param[in] value system time
+ * @param[in] timer hardware timer identifier
*/
void hwtimer_arch_set_absolute(unsigned long value, short timer);
/**
- * Unset the kernel timer with the given timer ID.
+ * @brief Unset the kernel timer with the given timer ID.
+ *
+ * @param[in] timer hardware timer identifier
*/
void hwtimer_arch_unset(short timer);
/**
* Get the current tick count of the default hardware timer.
+ *
+ * @return The current tick count of the hardware timer
*/
unsigned long hwtimer_arch_now(void);
-/** @} */
#endif /* HWTIMER_ARCH_H_ */
--
GitLab