Merge pull request #983 from OlegHahm/core_doxygen_update

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,42 @@
 #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 #PURE and also not allowed to
+ *        examine global memory. I.e. a *CONST* function cannot even
+ *        dereference a pointer parameter.
+ */
 #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,26 @@
 #ifndef BITARITHM_H_
 #define BITARITHM_H_
 
-#define BS(val, bit)        ((val) & (bit))
-#define BS_COND(condition, target, mask)        (target) ^= ( (-(condition) ^ (target)) & (mask) )
+/**
+ * @def SETBIT
+ * @brief Sets a bitbitmask for a bitfield
+ *
+ * @param[in] val   The bitfield
+ * @param[in] bit   Specifies the bits to be set
+ *
+ * @return The modified bitfield
+ */
 #define SETBIT(val, bit)    val |= (bit)
+
+/**
+ * @def CLRBIT
+ * @brief Clears bitmask for a bitfield
+ *
+ * @param[in] val   The bitfield
+ * @param[in] bit   Specifies the bits to be cleared
+ *
+ * @return The modified bitfield
+ */
 #define CLRBIT(val, bit)    val &= (~(bit))
 
 /**
@@ -68,7 +85,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 +115,5 @@ unsigned number_of_lowest_bit(register unsigned v);
  */
 unsigned number_of_bits_set(unsigned v);
 
-/** @} */
 #endif /* BITARITHM_H_ */
+/** @} */

core/include/sched.h

@@ -1,7 +1,7 @@
 /*
- * 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
+ * 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
  * details.
  */
@@ -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
@@ -35,7 +39,7 @@
 #endif
 
 /**
- * @brief   Triggers the scheduler to schedule the next task
+ * @brief   Triggers the scheduler to schedule the next thread 
  */
 void sched_run(void);
 
@@ -59,7 +63,7 @@ void sched_set_status(tcb_t *process, unsigned int status);
 void sched_switch(uint16_t current_prio, uint16_t other_prio);
 
 /**
- * @brief   Call context switching at task exit
+ * @brief   Call context switching at thread exit
  */
 void cpu_switch_context_exit(void);
 
@@ -89,15 +93,25 @@ 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
  */
 typedef struct {
-    unsigned int laststart; /*< Time stamp of the last time this thread was
-                                scheduled to run */
-    unsigned int schedules; /*< How often the thread was scheduled to run */
-    unsigned long runtime_ticks;   /*< The total runtime of this thread in ticks */
+    unsigned int laststart;         /**< Time stamp of the last time this thread was
+                                         scheduled to run */
+    unsigned int schedules;         /**< How often the thread was scheduled to run */
+    unsigned long runtime_ticks;    /**< The total runtime of this thread in ticks */
 } schedstat;
 
 /**
@@ -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;
 }