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).
*
- * The hardware timer must not be used within applications, use \ref vtimer
- * instead.
+ * The hardware timer should not be used (until you know what
+ * you're doing), 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
+ */
+int hwtimer_active(void);
+
+/**
+ * @brief initialize hwtimer module data structures and hardware
+ *
+ * @param[in] fcpu cpu frequency
+ */
+void hwtimer_init_comp(uint32_t fcpu);
+
+/**
+ * @brief Delay current thread, spinning. Use only in interrupts for VERY short delays!
+ *
+ * @param[in] ticks Number of kernel ticks to delay
*/
void hwtimer_spin(unsigned long ticks);
-int hwtimer_active(void);
-
-/** @} */
-
-/* internal */
-/**
- * @brief TODO
- * @internal
- */
-void hwtimer_cpu_init(void (*handler)(int), uint32_t fcpu);
-
/** @} */
#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
* @author Heiko Will
* @author Kaspar Schleiser
+ * @}
*/
#ifndef HWTIMER_ARCH_H_
@@ -25,40 +26,52 @@
#include
/**
- * 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_ */
diff --git a/core/include/io.h b/core/include/io.h
index dcc2d62bb0..97e0f39895 100644
--- a/core/include/io.h
+++ b/core/include/io.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
*
* This file subject to the terms and conditions of the GNU Lesser General
* Public License. See the file LICENSE in the top level directory for more
@@ -22,6 +22,12 @@
#ifndef IO_H
#define IO_H
+/**
+ * @brief Firmware putstring implementation
+ *
+ * @param[in] data charachters to be written
+ * @param[in] count number of charachters to be written
+ */
int fw_puts(char *data, int count);
/** @} */
diff --git a/core/include/queue.h b/core/include/queue.h
index 0760eae8d2..a0e6aadfcc 100644
--- a/core/include/queue.h
+++ b/core/include/queue.h
@@ -23,22 +23,79 @@
#include
#include
-// mspgcc bug : PRIxxx macros not defined before mid-2011 versions
+/* mspgcc bug : PRIxxx macros not defined before mid-2011 versions */
+/**
+ * @brief Macro for printing 32 bit format specifier
+ * @def PRIu32
+ */
#ifndef PRIu32
#define PRIu32 "lu"
#endif
+/**
+ * data type for queue nodes
+ */
typedef struct queue_node_t {
- struct queue_node_t *next;
- unsigned int data;
- uint32_t priority;
+ struct queue_node_t *next; /**< next queue node */
+ unsigned int data; /**< queue node data */
+ uint32_t priority; /**< queue node priority */
} queue_node_t;
+/**
+ * @brief attach `new_obj` to the tail of the queue (identified
+ * `root`)
+ *
+ * @param[in,out] root the queue's root
+ * @param[in] new_obj the object to append
+ */
void queue_add_tail(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief attach `new_obj` to `root` at the beginning
+ *
+ * @param[in,out] root the queue's root
+ * @param[in] new_obj the object to prepend
+ */
void queue_add_head(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief remove the queue's head
+ *
+ * @param[out] root the queue's root
+ *
+ * @return the old head
+ */
queue_node_t *queue_remove_head(queue_node_t *root);
+
+/**
+ * @brief insert `new_obj` into `root` based on its priority
+ *
+ * @details
+ * The new object will be appended after objects with the same priority.
+ *
+ * @param[in,out] root the queue's root
+ * @param[in] new_obj the object to prepend
+ */
void queue_priority_add(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief insert `new_obj` into `root` based on an arbitrary priority
+ *
+ * @details
+ * The new object will be appended after objects with the same priority.
+ *
+ * @param[in,out] root the queue's root
+ * @param[in] new_obj the object to prepend
+ * @param[in] cmp a comparator function used to determine the priority
+ */
void queue_priority_add_generic(queue_node_t *root, queue_node_t *new_obj, int(*cmp)(queue_node_t *, queue_node_t *)) ;
+
+/**
+ * @brief remove `node` from `root`
+ *
+ * @param[in,out] root the queue's root
+ * @param[in] node the node to remove
+ */
void queue_remove(queue_node_t *root, queue_node_t *node);
#if ENABLE_DEBUG