diff --git a/core/include/crash.h b/core/include/crash.h
index 2d5f5112b9faee53e49f3a46fc2c5779d9b77fad..06755e147c4efc02fbabf099f360874bb47fdaf2 100644
--- a/core/include/crash.h
+++ b/core/include/crash.h
@@ -14,7 +14,7 @@
* @brief Crash handling header
*
* Define a core_panic() function that allows to stop/reboot the system
- * when an unrecoverable problem has occured.
+ * when an unrecoverable problem has occurred.
*
* @author Kévin Roussel <Kevin.Roussel@inria.fr>
*/
@@ -24,18 +24,27 @@
#include "kernel.h"
-/** Handle an unrecoverable error by halting or rebooting the system.
- A numeric code indicating the failure reason can be given
- as the ::crash_code parameter.
- Detailing the failure is possible using the ::message parameter.
- This function should serve a similar purpose as the panic()
- function of Unix/Linux kernels.
-
- If the DEVELHELP macro is defined, the system will be halted;
- the system will be rebooted otherwise.
-
- WARNING: this function NEVER returns! */
+/**
+ * @brief Handle an unrecoverable error by halting or rebooting the system
+ *
+ * A numeric code indicating the failure reason can be given
+ * as the *crash_code* parameter.
+ *
+ * Detailing the failure is possible using the *message* parameter.
+ * This function should serve a similar purpose as the panic()
+ * function of Unix/Linux kernels.
+ *
+ * If the DEVELHELP macro is defined, the system will be halted;
+ * the system will be rebooted otherwise.
+ *
+ * @warning this function NEVER returns!
+ *
+ * @param[in] crash_code a unique code for identifying the crash reason
+ * @param[in] message a human readable reason for the crash
+ *
+ * @return this function never returns
+ * */
NORETURN void core_panic(int crash_code, const char *message);
-/** @} */
#endif /* __CRASH_H */
+/** @} */
diff --git a/core/include/debug.h b/core/include/debug.h
index 2619524a39449a8aee85914c604f768ca0254341..4fcf4f3103ef77f181c2191263f9483fbe8f2325 100644
--- a/core/include/debug.h
+++ b/core/include/debug.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
*
* This file is subject to the terms and conditions of the GNU Lesser General
* Public License. See the file LICENSE in the top level directory for more
@@ -25,6 +25,16 @@
#include <stdio.h>
#include "sched.h"
+/**
+ * @name Print debug information if the calling thread stack is large enough
+ *
+ * Use this macro the same as printf. When DEVHELP is defined inside an
+ * implementation file, all usages of *DEBUG_PRINTF* will print the given
+ * information to std-out. If DEVHELP is not set, all occurrences of
+ * *DEBUG_PRINTF* will be ignored.
+ *
+ * @{
+ */
#if DEVELHELP
#include "cpu-conf.h"
#define DEBUG_PRINT(...) \
@@ -39,7 +49,21 @@
#else
#define DEBUG_PRINT(...) printf(__VA_ARGS__)
#endif
+/** @} */
+/**
+ * @brief Print debug information to std-out
+ *
+ * If *ENABLE_DEBUG* is defined inside an implementation file, all calls to
+ * *DEBUG* and *DEBUGF* will work the same as *printf* and output the given
+ * information to stdout. If *ENABLE_DEBUG* is not defined, all calls to
+ * *DEBUG* and *DEBUGF* will be ignored.
+ *
+ * In addition to just printing the given information *DEBUGF* will further
+ * print extended debug information about the current thread and function.
+ *
+ * @{
+ */
#if ENABLE_DEBUG
#include "tcb.h"
#define DEBUG(...) DEBUG_PRINT(__VA_ARGS__)
@@ -55,6 +79,7 @@
#define DEBUG(...)
#define DEBUGF(...)
#endif
-
/** @} */
+
#endif /* __DEBUG_H */
+/** @} */
diff --git a/core/include/flags.h b/core/include/flags.h
index e8715e8f6ee373bb4b3f9e8e6605aebf1f98a857..115820343bc01742bb20d98264cb75c263ba6683 100644
--- a/core/include/flags.h
+++ b/core/include/flags.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
*
* This file is subject to the terms and conditions of the GNU Lesser General
* Public License. See the file LICENSE in the top level directory for more
@@ -19,10 +19,16 @@
#ifndef _FLAGS_H
#define _FLAGS_H
-#define CREATE_SLEEPING (1)
-#define AUTO_FREE (2)
-#define CREATE_WOUT_YIELD (4)
-#define CREATE_STACKTEST (8)
+/**
+ * @name Optional flags for controlling a threads initial state.
+ * @{
+ */
+#define CREATE_SLEEPING (1) /**< set the new thread to sleeping */
+#define AUTO_FREE (2) /**< currently not implemented */
+#define CREATE_WOUT_YIELD (4) /**< do not automatically call thread_yield() after creation */
+#define CREATE_STACKTEST (8) /**< write markers into the thread's stack to measure stack
+ usage (for debugging) */
+/** @} */
+#endif /* _FLAGS_H */
/** @} */
-#endif // _FLAGS_H
diff --git a/core/include/thread.h b/core/include/thread.h
index 065f17218ab3b99ff7c65dfe0de2223b3b044f16..8f9663e35773a99acc8730ca7103362e6b811f22 100644
--- a/core/include/thread.h
+++ b/core/include/thread.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
@@ -29,77 +29,122 @@
#define STATUS_NOT_FOUND (-1)
-/** Minimum stack size */
+/**
+ * @name Minimum stack size
+ */
#ifndef MINIMUM_STACK_SIZE
#define MINIMUM_STACK_SIZE (sizeof(tcb_t))
#endif
/**
- * @brief Creates a new thread.
+ * @brief Creates a new thread
+ *
+ * Creating a new thread is done in two steps:
+ * 1. the new thread's stack is initialized depending on the platform
+ * 2. the new thread is added to the scheduler to be run
+ *
+ * As RIOT is using a fixed priority scheduling algorithm, threads
+ * are scheduled base on their priority. The priority is fixed for every thread
+ * and specified during the threads creation by the *priority* parameter.
+ *
+ * A low value for *priority* number means the thread having a high priority
+ * with 0 being the highest possible priority.
*
- * @param stack Lowest address of preallocated stack space
- * @param stacksize
- * @param flags Options:
- * YIELD: force context switch.
- * CREATE_SLEEPING: set new thread to sleeping state, thread must be woken up manually.
- * CREATE_STACKTEST: initialize stack with values needed for stack overflow testing.
+ * The lowest possible priority is *PRIORITY_IDLE - 1*. The value is depending
+ * on the platforms architecture, e.g. 30 in 32-bit systems, 14 in 16-bit systems.
*
- * @param priority Priority of newly created thread. Lower number means higher
- * priority. 0 means highest possible priority. Lowest priority is
- * PRIORITY_IDLE-1, usually 30.
*
- * @return returns <0 on error, pid of newly created task else.
+ * In addition to the priority, the *flags* argument can be used to alter the
+ * newly created threads behavior after creation. The following flags are available:
+ * - CREATE_SLEEPING the newly created thread will be put to sleeping state and
+ * must be waken up manually
+ * - CREATE_WOUT_YIELD the newly created thread will not run immediately after creation
+ * - CREATE_STACKTEST write markers into the thread's stack to measure the stack's memory
+ * usage (for debugging and profiling purposes)
+ *
+ * @param[out] stack start address of the preallocated stack memory
+ * @param[in] stacksize the size of the thread's stack in bytes
+ * @param[in] priority priority of the new thread, lower mean higher priority
+ * @param[in] flags optional flags for the creation of the new thread
+ * @param[in] function pointer to the code that is executed in the new thread
+ * @param[in] name a human readable descriptor for the thread
+ *
+ * @return value ``<0`` on error
+ * @return pid of newly created task, otherwise
*/
-int thread_create(char *stack, int stacksize, char priority, int flags, void (*function) (void), const char *name);
+int thread_create(char *stack,
+ int stacksize,
+ char priority,
+ int flags,
+ void (*function) (void),
+ const char *name);
/**
- * @brief returns the status of a process.
- * @return STATUS_NOT_FOUND if pid is unknown
+ * @brief Returns the status of a process
+ *
+ * @param[in] pid the PID of the thread to get the status from
+ *
+ * @return status of the thread
+ * @return `STATUS_NOT_FOUND` if pid is unknown
*/
int thread_getstatus(int pid);
/**
- * @brief returns the name of a process.
- * @return NULL if pid is unknown
+ * @brief Returns the name of a process
+ *
+ * @param[in] pid the PID of the thread to get the name from
+ *
+ * @return the threads name
+ * @return `NULL` if pid is unknown
*/
const char *thread_getname(int pid);
/**
- * @brief Puts the current thread into sleep mode. Has to be woken up externally.
+ * @brief Puts the current thread into sleep mode. Has to be woken up externally.
*/
void thread_sleep(void);
/**
- * @brief The current thread yields and let the scheduler run.
+ * @brief The current thread yields and let the scheduler run
+ *
+ * The current thread will resume operation immediately if there is no other thread with the same
+ * or a higher priority.
*/
void thread_yield(void);
/**
- * @brief Wakes up a sleeping thread.
- * @param pid The PID of the thread to be woken up
- * @return STATUS_NOT_FOUND if pid is unknown or not sleeping
+ * @brief Wakes up a sleeping thread.
+ *
+ * @param[in] pid the PID of the thread to be woken up
+ *
+ * @return `1` on success
+ * @return `STATUS_NOT_FOUND` if pid is unknown or not sleeping
*/
int thread_wakeup(int pid);
/**
- * @brief Returns the process ID of the currently running thread.
- * @return Obviously you are not a golfer.
+ * @brief Returns the process ID of the currently running thread
+ *
+ * @return obviously you are not a golfer.
*/
int thread_getpid(void);
/**
- * @brief Returns the process ID of the thread running before the current one.
- * @return Obviously you are not a golfer.
+ * @brief Returns the process ID of the thread running before the current one
+ *
+ * @return obviously you are not a golfer.
*/
int thread_getlastpid(void);
/**
- * @brief Measures the stack usage of a stack.
+ * @brief Measures the stack usage of a stack
+ *
* Only works if the thread was created with the flag CREATE_STACKTEST.
*
- * @param stack The stack you want to measure. try active_thread->stack_start.
- * @return The amount of unused space of the thread's stack
+ * @param[in] stack the stack you want to measure. try `active_thread->stack_start`
+ *
+ * @return the amount of unused space of the thread's stack
*/
int thread_measure_stack_free(char *stack);