core: documentation: updated, improved, and completed doxygen comments

core/include/atomic.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
@@ -11,7 +11,7 @@
  * @{
  *
  * @file        atomic.h
- * @brief       Atomic function declarations
+ * @brief       Atomic getter and setter functions
  *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
@@ -21,10 +21,14 @@
 #define _ATOMIC_H
 
 /**
- * @brief sets "val" to "set", returns old "val", atomically
+ * @brief Sets a new and returns the old value of a variable atomically
+ *
+ * @param[in] val   The variable to be set
+ * @param[in] set   The value to be written
+ *
+ * @return The old value of *val*
  */
+unsigned int atomic_set_return(unsigned int *val, unsigned int set);
 
-extern unsigned int atomic_set_return(unsigned int *val, unsigned int set);
-
-/** @} */
 #endif /* _ATOMIC_H */
+/** @} */

core/include/attributes.h

@@ -20,24 +20,40 @@
 #ifndef ATTRIBUTES_H_
 #define ATTRIBUTES_H_
 
+/**
+ * @def NORETURN
+ * @brief The *NORETURN* keyword tells the compiler to assume that the function
+ *        cannot return.
+ */
 #ifdef __GNUC__
 #define NORETURN  __attribute__((noreturn))
 #else
 #define NORETURN
 #endif
 
+/**
+ * @def CONST
+ * @brief A function declared as *CONST* is not allowed to read global memory
+ */
 #ifdef __GNUC__
 #define CONST  __attribute__((const))
 #else
 #define CONST
 #endif
 
+/**
+ * @def PURE
+ * @brief The function has no effects except the return value and its return
+ *        value depends only on the parameters and/or global variables. Such a
+ *        function can be subject to common subexpression elimination and loop
+ *        optimization just as an arithmetic operator would be.
+ */
 #ifdef __GNUC__
 #define PURE  __attribute__((pure))
 #else
 #define PURE
 #endif
 
-/** @} */
 #endif /* ATTRIBUTES_H_ */
+/** @} */
 

core/include/bitarithm.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
@@ -21,9 +21,47 @@
 #ifndef BITARITHM_H_
 #define BITARITHM_H_
 
+/** @def BS
+ * @brief Sets a bitmask
+ * @param[in] val   The value to which the bitmask will be applied
+ * @param[in] bit   The bitmask to be set
+ *
+ * @return The applied bitmask
+ */
 #define BS(val, bit)        ((val) & (bit))
+
+/**
+ * @def BS_COND
+ * @brief Conditional setting of a bitmask
+ *
+ * @param[in] condition     The condition to be checked
+ * @param[in] target        The value to which the bitmask will be applied
+ * @param[in] mask          The bitmask to be set
+ *
+ * @return The applied bitmask if *condition* is true
+ */
 #define BS_COND(condition, target, mask)        (target) ^= ( (-(condition) ^ (target)) & (mask) )
+
+/**
+ * @def SETBIT
+ * @brief Sets a single bit in a bitfield
+ *
+ * @param[in] val   The bitfield
+ * @param[in] bit   Specifies the bit to be set
+ *
+ * @return The modified bitfield
+ */
 #define SETBIT(val, bit)    val |= (bit)
+
+/**
+ * @def CLRBIT
+ * @brief Clears a single bit in a bitfield
+ *
+ * @param[in] val   The bitfield
+ * @param[in] bit   Specifies the bit to be cleared
+ *
+ * @return The modified bitfield
+ */
 #define CLRBIT(val, bit)    val &= (~(bit))
 
 /**
@@ -68,7 +106,7 @@
 #endif
 /** @} */
 
-#define ARCH_32_BIT   (__INT_MAX__ == 2147483647)
+#define ARCH_32_BIT   (__INT_MAX__ == 2147483647) /**< 1 for 32 bit architectures, 0 otherwise */
 
 /**
  * @brief   Returns the number of the highest '1' bit in a value
@@ -98,5 +136,5 @@ unsigned number_of_lowest_bit(register unsigned v);
  */
 unsigned number_of_bits_set(unsigned v);
 
-/** @} */
 #endif /* BITARITHM_H_ */
+/** @} */

core/include/sched.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
@@ -26,8 +26,12 @@
 #include "bitarithm.h"
 #include "tcb.h"
 
-#define MAXTHREADS 32
+#define MAXTHREADS 32 /**< the maximum number of threads to be scheduled */
 
+/**
+ * @def SCHED_PRIO_LEVELS
+ * @brief The number of thread priority levels
+ */
 #if ARCH_32_BIT
 #define SCHED_PRIO_LEVELS 32
 #else
@@ -89,6 +93,16 @@ extern volatile int num_tasks;
  */
 extern volatile int thread_pid;
 
+/**
+ *  Process ID of the thread that was active before the current one
+ */
+extern volatile int last_pid;
+
+/**
+ * List of runqueues per priority level
+ */
+extern clist_node_t *runqueues[SCHED_PRIO_LEVELS];
+
 #if SCHEDSTATISTICS
 /**
  *  Scheduler statistics
@@ -106,10 +120,13 @@ typedef struct {
 extern schedstat pidlist[MAXTHREADS];
 
 /**
- *  Register a callback that will be called on every scheduler run
+ *  @brief  Register a callback that will be called on every scheduler run
+ *
+ *  @param[in] callback The callback functions the will be called
  */
 void sched_register_cb(void (*callback)(uint32_t, uint32_t));
+
 #endif
 
-/** @} */
 #endif // _SCHEDULER_H
+/** @} */

core/sched.c

@@ -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
@@ -7,10 +7,10 @@
  */
 
 /**
- * @ingroup     core_shed
+ * @ingroup     core_sched
  * @{
  *
- * @file        shed.c
+ * @file        sched.c
  * @brief       Scheduler implementation
  *
  * @author      Freie Universität Berlin, Computer Systems & Telematics

core/thread.c

@@ -39,7 +39,6 @@ inline int thread_getpid()
 
 int thread_getlastpid()
 {
-    extern int last_pid;
     return last_pid;
 }