diff options
author | Daniel Georgiev <daniel.georgiev95@gmail.com> | 2012-12-01 09:53:45 -0500 |
---|---|---|
committer | Gedare Bloom <gedare@rtems.org> | 2012-12-01 09:53:45 -0500 |
commit | 5a58b1e4988eb1a0fb6311b25fd12c91bb7237d7 (patch) | |
tree | 842558afb925e4f9fe5a0ac74a7f25a7d6b181be | |
parent | score misc: Score misc: Clean up Doxygen #10 (GCI 2012) (diff) | |
download | rtems-5a58b1e4988eb1a0fb6311b25fd12c91bb7237d7.tar.bz2 |
score misc: Score misc: Clean up Doxygen #11 (GCI 2012)
This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.
http://www.google-melange.com/gci/task/view/google/gci2012/8013204
28 files changed, 144 insertions, 207 deletions
diff --git a/cpukit/score/include/rtems/score/corebarrier.h b/cpukit/score/include/rtems/score/corebarrier.h index 7f9c5d8be5..8072ec1e39 100644 --- a/cpukit/score/include/rtems/score/corebarrier.h +++ b/cpukit/score/include/rtems/score/corebarrier.h @@ -134,6 +134,7 @@ void _CORE_barrier_Initialize( ); /** + * @brief Wait For The Barrier * This routine wait for the barrier to be released. If the barrier * is set to automatic and this is the appropriate thread, then it returns * immediately. Otherwise, the calling thread is blocked until the barrier diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index 8076a376b0..9c0fce34cc 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -296,6 +296,7 @@ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body( #if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__) /** + * @brief Trylock CORE Mutex Seize Interrupt * When doing test coverage analysis or trying to minimize the code * space for RTEMS, it is often helpful to not inline this method * multiple times. It is fairly large and has a high branch complexity diff --git a/cpukit/score/include/rtems/score/corerwlock.h b/cpukit/score/include/rtems/score/corerwlock.h index 6d97ab1f23..3b70d80701 100644 --- a/cpukit/score/include/rtems/score/corerwlock.h +++ b/cpukit/score/include/rtems/score/corerwlock.h @@ -138,6 +138,7 @@ void _CORE_RWLock_Initialize( ); /** + * @brief Obtain RWLock for reading * This routine attempts to obtain the RWLock for read access. * * @param[in] the_rwlock is the RWLock to wait for @@ -150,6 +151,7 @@ void _CORE_RWLock_Initialize( * * @note Status is returned via the thread control block. */ + void _CORE_RWLock_Obtain_for_reading( CORE_RWLock_Control *the_rwlock, Objects_Id id, diff --git a/cpukit/score/include/rtems/score/corespinlock.h b/cpukit/score/include/rtems/score/corespinlock.h index 9a4d7af25d..dfa62ccb8f 100644 --- a/cpukit/score/include/rtems/score/corespinlock.h +++ b/cpukit/score/include/rtems/score/corespinlock.h @@ -123,6 +123,7 @@ void _CORE_spinlock_Initialize( ); /** + * @brief Wait for Spinlock * This routine wait for the spinlock to be released. If the spinlock * is set to automatic and this is the appropriate thread, then it returns * immediately. Otherwise, the calling thread is blocked until the spinlock diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 274347bb0b..f2f4469368 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -583,6 +583,7 @@ typedef enum { #define OBJECTS_NAME_ERRORS_LAST OBJECTS_INVALID_NODE /** + * @brief Object Name To Id * This method converts an object name to an Id. It performs a look up * using the object information block for this object class. * @@ -627,6 +628,7 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_string( #endif /** + * @brief Object Id To Name * This function implements the common portion of the object Id * to name directives. This function returns the name * associated with object id. @@ -647,6 +649,7 @@ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( ); /** + * @brief Get Object * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h index f959c0e174..3432937062 100644 --- a/cpukit/score/include/rtems/score/schedulerpriority.h +++ b/cpukit/score/include/rtems/score/schedulerpriority.h @@ -64,6 +64,7 @@ typedef struct { } Scheduler_priority_Per_thread; /** + * @brief Initialize Scheduler Priority * This routine initializes the priority scheduler. */ void _Scheduler_priority_Initialize(void); diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h index 6716383205..66b4018b50 100644 --- a/cpukit/score/include/rtems/score/schedulersimple.h +++ b/cpukit/score/include/rtems/score/schedulersimple.h @@ -93,6 +93,7 @@ void _Scheduler_simple_Block( ); /** + * @brief Scheduler Simple Handler / Unblock * This routine adds @a the_thread to the scheduling decision, * that is, adds it to the ready queue and * updates any appropriate scheduling variables, for example the heir thread. diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index 845b6e0723..623b56251f 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -578,6 +578,7 @@ void _Thread_Stack_Free( ); /** + * @brief Initialize Thread * This routine initializes the specified the thread. It allocates * all memory associated with this thread. It completes by adding * the thread to the local object table so operations on this @@ -745,11 +746,24 @@ void _Thread_Load_environment( ); /** + * @brief Thread Handler * This routine is the wrapper function for all threads. It is * the starting point for all threads. The user provided thread * entry point is invoked by this routine. Operations * which must be performed immediately before and after the user's * thread executes are found here. + * + * NOTE: + * + * On entry, it is assumed all interrupts are blocked and that this + * routine needs to set the initial isr level. This may or may not + * actually be needed by the context switch routine and as a result + * interrupts may already be at there proper level. Either way, + * setting the initial isr level properly here is safe. + * + * Input parameters: NONE + * + * Output parameters: NONE */ void _Thread_Handler( void ); @@ -826,6 +840,7 @@ void *_Thread_Idle_body( typedef void (*rtems_per_thread_routine)( Thread_Control * ); /** + * @brief Iterates Over All Threads * This routine iterates over all threads regardless of API and * invokes the specified routine. */ diff --git a/cpukit/score/src/corebarrierwait.c b/cpukit/score/src/corebarrierwait.c index 0a2a1b7267..e8ab6292ee 100644 --- a/cpukit/score/src/corebarrierwait.c +++ b/cpukit/score/src/corebarrierwait.c @@ -1,10 +1,11 @@ -/* - * SuperCore Barrier Handler - * - * DESCRIPTION: - * - * This package is part of the implementation of the SuperCore Barrier Handler. +/** + * @file * + * @brief Wait For The Barrier + * @ingroup ScoreBarrier + */ + +/* * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * @@ -24,23 +25,6 @@ #include <rtems/score/thread.h> #include <rtems/score/threadq.h> -/* - * _CORE_barrier_Wait - * - * Input parameters: - * the_barrier - pointer to barrier control block - * id - id of object to wait on - * wait - true if wait is allowed, false otherwise - * timeout - number of ticks to wait (0 means forever) - * api_barrier_mp_support - api dependent MP support actions - * - * Output parameters: NONE - * - * INTERRUPT LATENCY: - * available - * wait - */ - void _CORE_barrier_Wait( CORE_barrier_Control *the_barrier, Objects_Id id, diff --git a/cpukit/score/src/coremutex.c b/cpukit/score/src/coremutex.c index 596fa3f256..951bec63cd 100644 --- a/cpukit/score/src/coremutex.c +++ b/cpukit/score/src/coremutex.c @@ -1,11 +1,11 @@ -/* - * Mutex Handler - * - * DESCRIPTION: - * - * This package is the implementation of the Mutex Handler. - * This handler provides synchronization and mutual exclusion capabilities. +/** + * @file * + * @brief Initialize a Core Mutex + * @ingroup ScoreMutex + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * @@ -25,20 +25,6 @@ #include <rtems/score/thread.h> #include <rtems/score/threadq.h> -/* - * _CORE_mutex_Initialize - * - * This routine initializes a mutex at create time and set the control - * structure according to the values passed. - * - * Input parameters: - * the_mutex - the mutex control block to initialize - * the_mutex_attributes - the mutex attributes specified at create time - * initial_lock - mutex initial lock or unlocked status - * - * Output parameters: NONE - */ - CORE_mutex_Status _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, CORE_mutex_Attributes *the_mutex_attributes, diff --git a/cpukit/score/src/coremutexflush.c b/cpukit/score/src/coremutexflush.c index 0c41aea8b8..d05dd54d30 100644 --- a/cpukit/score/src/coremutexflush.c +++ b/cpukit/score/src/coremutexflush.c @@ -1,11 +1,11 @@ -/* - * Mutex Handler - * - * DESCRIPTION: - * - * This package is the implementation of the Mutex Handler. - * This handler provides synchronization and mutual exclusion capabilities. +/** + * @file * + * @brief Flush all waiting threads + * @ingroup ScoreMutex + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * @@ -25,19 +25,6 @@ #include <rtems/score/thread.h> #include <rtems/score/threadq.h> -/* - * _CORE_mutex_Flush - * - * This function a flushes the mutex's task wait queue. - * - * Input parameters: - * the_mutex - the mutex to be flushed - * remote_extract_callout - function to invoke remotely - * status - status to pass to thread - * - * Output parameters: NONE - */ - void _CORE_mutex_Flush( CORE_mutex_Control *the_mutex, Thread_queue_Flush_callout remote_extract_callout, diff --git a/cpukit/score/src/coremutexseizeintr.c b/cpukit/score/src/coremutexseizeintr.c index ee4f18f15b..128e8c0de3 100644 --- a/cpukit/score/src/coremutexseizeintr.c +++ b/cpukit/score/src/coremutexseizeintr.c @@ -1,6 +1,11 @@ -/* - * Mutex Handler -- Seize interrupt disable version +/** + * @file * + * @brief Trylock CORE Mutex Seize Interrupt + * @ingroup ScoreMutex + */ + +/* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/corerwlockobtainread.c b/cpukit/score/src/corerwlockobtainread.c index a8ea78ba1e..18df39d296 100644 --- a/cpukit/score/src/corerwlockobtainread.c +++ b/cpukit/score/src/corerwlockobtainread.c @@ -1,6 +1,11 @@ +/** + * @file + * + * @brief Obtain RWLock for reading + * @ingroup ScoreRWLock + */ + /* - * SuperCore RWLock Handler -- Obtain RWLock for reading - * * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * @@ -19,20 +24,6 @@ #include <rtems/score/thread.h> #include <rtems/score/watchdog.h> -/* - * _CORE_rwlock_Obtain_for_reading - * - * This function waits for the rwlock to become available. Optionally, - * a limit may be placed on the duration of the spin. - * - * Input parameters: - * the_rwlock - the rwlock control block to initialize - * timeout_allowed - true if timeout allowed - * timeout - the maximum number of ticks to spin - * - * Output parameters: NONE - */ - void _CORE_RWLock_Obtain_for_reading( CORE_RWLock_Control *the_rwlock, Objects_Id id, diff --git a/cpukit/score/src/corespinlockwait.c b/cpukit/score/src/corespinlockwait.c index eb1f1388a7..fa2fb11216 100644 --- a/cpukit/score/src/corespinlockwait.c +++ b/cpukit/score/src/corespinlockwait.c @@ -1,6 +1,11 @@ /* - * SuperCore Spinlock Handler -- Wait for Spinlock + * @file * + * @brief Wait for Spinlock + * @ingroup ScoreSpinlock + */ + +/* * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/iterateoverthreads.c b/cpukit/score/src/iterateoverthreads.c index 4cdb5ea2d9..78e769bb00 100644 --- a/cpukit/score/src/iterateoverthreads.c +++ b/cpukit/score/src/iterateoverthreads.c @@ -1,10 +1,11 @@ -/* - * rtems_iterate_over_all_threads - * - * This function operates by as follows: - * for all threads - * invoke specified function +/** + * @file * + * @brief Iterates Over All Threads + * @ingroup ScoreThread + */ + +/* * COPYRIGHT (c) 1989-2010. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/objectget.c b/cpukit/score/src/objectget.c index f2a549afec..eca8ea9925 100644 --- a/cpukit/score/src/objectget.c +++ b/cpukit/score/src/objectget.c @@ -1,7 +1,11 @@ /* - * Object Handler - * + * @file * + * @brief Get Object + * @ingroup Score + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * @@ -26,25 +30,6 @@ #include <rtems/score/sysstate.h> #include <rtems/score/isr.h> -/* - * _Objects_Get - * - * This routine sets the object pointer for the given - * object id based on the given object information structure. - * - * Input parameters: - * information - pointer to entry in table for this class - * id - object id to search for - * location - address of where to store the location - * - * Output parameters: - * returns - address of object if local - * location - one of the following: - * OBJECTS_ERROR - invalid object ID - * OBJECTS_REMOTE - remote object - * OBJECTS_LOCAL - local object - */ - Objects_Control *_Objects_Get( Objects_Information *information, Objects_Id id, diff --git a/cpukit/score/src/objectidtoname.c b/cpukit/score/src/objectidtoname.c index 2698c17c25..1c0d926838 100644 --- a/cpukit/score/src/objectidtoname.c +++ b/cpukit/score/src/objectidtoname.c @@ -1,7 +1,11 @@ /* - * Obtain Object Name Given ID - * + * @file * + * @brief Object id to name + * @ingroup Score + */ + +/* * COPYRIGHT (c) 1989-2003. * On-Line Applications Research Corporation (OAR). * @@ -18,19 +22,6 @@ #include <rtems/score/object.h> #include <rtems/score/thread.h> -/* - * _Objects_Id_to_name - * - * DESCRIPTION: - * - * This routine returns the name associated with the given ID. - * - * INPUT: - * - * id - id of object to lookup name - * name - pointer to location in which to store name - * - */ Objects_Name_or_id_lookup_errors _Objects_Id_to_name ( Objects_Id id, Objects_Name *name diff --git a/cpukit/score/src/objectnametoid.c b/cpukit/score/src/objectnametoid.c index 15700a0aff..7648f22cc4 100644 --- a/cpukit/score/src/objectnametoid.c +++ b/cpukit/score/src/objectnametoid.c @@ -1,6 +1,11 @@ -/* - * Object Handler +/** + * @file * + * @brief Object Name To Id + * @ingroup Score + */ + +/* * COPYRIGHT (c) 1989-2010. * On-Line Applications Research Corporation (OAR). * @@ -25,24 +30,6 @@ #include <rtems/score/sysstate.h> #include <rtems/score/isr.h> -/* - * _Objects_Name_to_id_u32 - * - * These kernel routines search the object table(s) for the given - * object name and returns the associated object id. - * - * Input parameters: - * information - object information - * name - user defined object name - * node - node indentifier (0 indicates any node) - * id - address of return ID - * - * Output parameters: - * id - object id - * OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL - if successful - * error code - if unsuccessful - */ - Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32( Objects_Information *information, uint32_t name, diff --git a/cpukit/score/src/rbtreeget.c b/cpukit/score/src/rbtreeget.c index 81e9161a37..1570d472c8 100644 --- a/cpukit/score/src/rbtreeget.c +++ b/cpukit/score/src/rbtreeget.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Obtain the min or max node of a rbtree + * @ingroup ScoreRBTree + */ + /* * Copyright (c) 2010 Gedare Bloom. * @@ -15,24 +22,6 @@ #include <rtems/score/rbtree.h> #include <rtems/score/isr.h> -/* - * _RBTree_Get - * - * This kernel routine returns a pointer to a node taken from the - * given rbtree. - * - * Input parameters: - * the_rbtree - pointer to rbtree header - * dir - specifies min (0) or max (1) - * - * Output parameters: - * return_node - pointer to node in rbtree allocated - * NULL - if no nodes available - * - * INTERRUPT LATENCY: - * only case - */ - RBTree_Node *_RBTree_Get( RBTree_Control *the_rbtree, RBTree_Direction dir diff --git a/cpukit/score/src/schedulercbsallocate.c b/cpukit/score/src/schedulercbsallocate.c index 226bc8ac44..cf348ee95e 100644 --- a/cpukit/score/src/schedulercbsallocate.c +++ b/cpukit/score/src/schedulercbsallocate.c @@ -1,4 +1,11 @@ /* + * @file + * + * @brief Scheduler CBS Allocate + * @ingroup ScoreScheduler + */ + +/* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/schedulerpriority.c b/cpukit/score/src/schedulerpriority.c index 127df9e515..e6176e8d05 100644 --- a/cpukit/score/src/schedulerpriority.c +++ b/cpukit/score/src/schedulerpriority.c @@ -1,6 +1,11 @@ /* - * Scheduler Handler + * @file * + * @brief Initialize Scheduler Priority + * @ingroup ScoreScheduler + */ + +/* * Copyright (C) 2010 Gedare Bloom. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/schedulersimpleunblock.c b/cpukit/score/src/schedulersimpleunblock.c index 5d8ea2881e..4c482bd752 100644 --- a/cpukit/score/src/schedulersimpleunblock.c +++ b/cpukit/score/src/schedulersimpleunblock.c @@ -1,6 +1,11 @@ +/** + * @file + * + * @brief Scheduler Simple Handler / Unblock + * @ingroup ScoreScheduler + */ + /* - * Scheduler Simple Handler / Unblock - * * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/threadhandler.c b/cpukit/score/src/threadhandler.c index 78671422f6..6367c451f4 100644 --- a/cpukit/score/src/threadhandler.c +++ b/cpukit/score/src/threadhandler.c @@ -1,7 +1,8 @@ /** * @file * - * Initialization Wrapper for all Threads. + * @brief Thread Handler + * @ingroup ScoreThread */ /* @@ -57,29 +58,6 @@ #define EXECUTE_GLOBAL_CONSTRUCTORS #endif -/* - * _Thread_Handler - * - * This routine is the "primal" entry point for all threads. - * _Context_Initialize() dummies up the thread's initial context - * to cause the first Context_Switch() to jump to _Thread_Handler(). - * - * This routine is the default thread exitted error handler. It is - * returned to when a thread exits. The configured fatal error handler - * is invoked to process the exit. - * - * NOTE: - * - * On entry, it is assumed all interrupts are blocked and that this - * routine needs to set the initial isr level. This may or may not - * actually be needed by the context switch routine and as a result - * interrupts may already be at there proper level. Either way, - * setting the initial isr level properly here is safe. - * - * Input parameters: NONE - * - * Output parameters: NONE - */ void _Thread_Handler( void ) { ISR_Level level; diff --git a/cpukit/score/src/threadinitialize.c b/cpukit/score/src/threadinitialize.c index 7fb650768b..fb22578c3d 100644 --- a/cpukit/score/src/threadinitialize.c +++ b/cpukit/score/src/threadinitialize.c @@ -1,6 +1,10 @@ -/* - * Thread Handler / Thread Initialize +/** + * @file * + * @brief Initialize Thread + * @ingroup ScoreThread + */ +/* * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * @@ -29,15 +33,6 @@ #include <rtems/score/watchdog.h> #include <rtems/score/wkspace.h> -/* - * _Thread_Initialize - * - * This routine initializes the specified the thread. It allocates - * all memory associated with this thread. It completes by adding - * the thread to the local object table so operations on this - * thread id are allowed. - */ - bool _Thread_Initialize( Objects_Information *information, Thread_Control *the_thread, diff --git a/cpukit/score/src/timespecsubtract.c b/cpukit/score/src/timespecsubtract.c index f8f356e106..391cbc0a90 100644 --- a/cpukit/score/src/timespecsubtract.c +++ b/cpukit/score/src/timespecsubtract.c @@ -1,5 +1,8 @@ /** * @file score/src/timespecsubtract.c + * + * @brief Subtract Two Timespec + * @ingroup Timespec */ /* diff --git a/cpukit/score/src/ts64divide.c b/cpukit/score/src/ts64divide.c index 2f8161ae1b..df0b448ecb 100644 --- a/cpukit/score/src/ts64divide.c +++ b/cpukit/score/src/ts64divide.c @@ -1,5 +1,8 @@ /** - * @file score/src/ts64divide.c + * @file + * + * @brief Divide Timestamp + * @ingroup SuperCore */ /* diff --git a/cpukit/score/src/ts64equalto.c b/cpukit/score/src/ts64equalto.c index 8dd226772e..20792208fd 100644 --- a/cpukit/score/src/ts64equalto.c +++ b/cpukit/score/src/ts64equalto.c @@ -1,6 +1,9 @@ /** - * @file score/src/ts64equalto.c -*/ + * @file + * + * @brief Timestamp equal to Operator + * @ingroup SuperCore + */ /* * COPYRIGHT (c) 1989-2008. diff --git a/cpukit/score/src/watchdogadjusttochain.c b/cpukit/score/src/watchdogadjusttochain.c index f18d78d15c..3b8684a978 100644 --- a/cpukit/score/src/watchdogadjusttochain.c +++ b/cpukit/score/src/watchdogadjusttochain.c @@ -1,10 +1,12 @@ /** - * @file watchdogadjusttochain.c + * @file * - * This is used by the Timer Server task. + * @brief Watchdog Adjust to Chain + * @ingroup ScoreWatchdog */ -/* COPYRIGHT (c) 1989-2009. +/* + * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be |