From 25a2122f8390e5ec06c6491cd9e2df6a1d5107c8 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Mon, 7 Apr 2014 11:16:32 +0200 Subject: [PATCH 1/7] core: documentation: updated, improved, and completed doxygen comments --- core/include/atomic.h | 16 ++++++++------ core/include/attributes.h | 18 +++++++++++++++- core/include/bitarithm.h | 44 ++++++++++++++++++++++++++++++++++++--- core/include/sched.h | 25 ++++++++++++++++++---- core/sched.c | 6 +++--- core/thread.c | 1 - 6 files changed, 92 insertions(+), 18 deletions(-) diff --git a/core/include/atomic.h b/core/include/atomic.h index f8943b0bbf..46fd4f136d 100644 --- a/core/include/atomic.h +++ b/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 @@ -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 */ +/** @} */ diff --git a/core/include/attributes.h b/core/include/attributes.h index 4138477f42..0f4bdf87d5 100644 --- a/core/include/attributes.h +++ b/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_ */ +/** @} */ diff --git a/core/include/bitarithm.h b/core/include/bitarithm.h index 0098957fb6..63941e8868 100644 --- a/core/include/bitarithm.h +++ b/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_ */ +/** @} */ diff --git a/core/include/sched.h b/core/include/sched.h index 8332a1a9be..217e88a7bd 100644 --- a/core/include/sched.h +++ b/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 +/** @} */ diff --git a/core/sched.c b/core/sched.c index 9d98728c32..db35c825d7 100644 --- a/core/sched.c +++ b/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 diff --git a/core/thread.c b/core/thread.c index 3140874098..832564d86c 100644 --- a/core/thread.c +++ b/core/thread.c @@ -39,7 +39,6 @@ inline int thread_getpid() int thread_getlastpid() { - extern int last_pid; return last_pid; } From 2d338feac4314c6fcdb363e11556e5eb0ca5f1a3 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Tue, 8 Apr 2014 21:27:57 +0200 Subject: [PATCH 2/7] core: documentation: fixed bitarithm documentation --- core/include/bitarithm.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/core/include/bitarithm.h b/core/include/bitarithm.h index 63941e8868..3c77b9862c 100644 --- a/core/include/bitarithm.h +++ b/core/include/bitarithm.h @@ -44,10 +44,10 @@ /** * @def SETBIT - * @brief Sets a single bit in a bitfield + * @brief Sets a bitbitmask for a bitfield * * @param[in] val The bitfield - * @param[in] bit Specifies the bit to be set + * @param[in] bit Specifies the bits to be set * * @return The modified bitfield */ @@ -55,10 +55,10 @@ /** * @def CLRBIT - * @brief Clears a single bit in a bitfield + * @brief Clears bitmask for a bitfield * * @param[in] val The bitfield - * @param[in] bit Specifies the bit to be cleared + * @param[in] bit Specifies the bits to be cleared * * @return The modified bitfield */ From 50c9d2da9002482c9fc9120edec0a3149c513643 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Tue, 8 Apr 2014 21:32:21 +0200 Subject: [PATCH 3/7] core: documentation: replaced task w/ thread --- core/include/sched.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/include/sched.h b/core/include/sched.h index 217e88a7bd..253fb2c053 100644 --- a/core/include/sched.h +++ b/core/include/sched.h @@ -39,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); @@ -63,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); From 5a63f3ab1c8d9bd96623e6c009969200b3be24b8 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Wed, 9 Apr 2014 12:10:27 +0200 Subject: [PATCH 4/7] core: documentation: fixed typo in license header --- core/include/sched.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/include/sched.h b/core/include/sched.h index 253fb2c053..f99f9a79cd 100644 --- a/core/include/sched.h +++ b/core/include/sched.h @@ -1,7 +1,7 @@ /* * 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. */ From 81fe4b6afc25ebb56e6ad1991af5dfb7baea5ac7 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Wed, 30 Apr 2014 19:16:20 +0200 Subject: [PATCH 5/7] documentation: extend description for CONST attribute --- core/include/attributes.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/core/include/attributes.h b/core/include/attributes.h index 0f4bdf87d5..e0ae7fbd7a 100644 --- a/core/include/attributes.h +++ b/core/include/attributes.h @@ -33,7 +33,9 @@ /** * @def CONST - * @brief A function declared as *CONST* is not allowed to read global memory + * @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)) From 6e27e1cdbb847634c22b14894d89387f533272e4 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Wed, 30 Apr 2014 19:16:47 +0200 Subject: [PATCH 6/7] bitarithm: remove unused macros --- core/include/bitarithm.h | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/core/include/bitarithm.h b/core/include/bitarithm.h index 3c77b9862c..673e5dff86 100644 --- a/core/include/bitarithm.h +++ b/core/include/bitarithm.h @@ -21,27 +21,6 @@ #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 bitbitmask for a bitfield From 13c615ac173aa44f515bb4db486c079788fd96a0 Mon Sep 17 00:00:00 2001 From: Oleg Hahm Date: Wed, 30 Apr 2014 19:17:05 +0200 Subject: [PATCH 7/7] documentation: fixed doxygen for schedstats --- core/include/sched.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/core/include/sched.h b/core/include/sched.h index f99f9a79cd..5fde47dc2f 100644 --- a/core/include/sched.h +++ b/core/include/sched.h @@ -108,10 +108,10 @@ extern clist_node_t *runqueues[SCHED_PRIO_LEVELS]; * 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; /**