From 355ee7dbd52a1ea5fd7d8b32d31aeccd58ccb8c4 Mon Sep 17 00:00:00 2001 From: Alex Ivanov Date: Wed, 28 Nov 2012 13:57:31 -0600 Subject: score misc: Clean up Doxygen #3 (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/7982215 --- cpukit/score/include/rtems/score/coremsg.h | 9 +++++- cpukit/score/include/rtems/score/coresem.h | 8 ++++++ cpukit/score/include/rtems/score/object.h | 2 ++ .../score/include/rtems/score/schedulerpriority.h | 2 ++ cpukit/score/include/rtems/score/schedulersimple.h | 2 ++ cpukit/score/include/rtems/score/thread.h | 2 ++ cpukit/score/include/rtems/score/threadq.h | 10 +++++++ cpukit/score/src/coremsg.c | 33 +++++----------------- cpukit/score/src/coresem.c | 29 +++++-------------- cpukit/score/src/coretodget.c | 9 ++++-- cpukit/score/src/coretodtickspersec.c | 7 +++++ cpukit/score/src/objectgetnoprotection.c | 29 +++++-------------- cpukit/score/src/schedulercbscleanup.c | 7 +++++ cpukit/score/src/schedulercbscreateserver.c | 7 +++++ cpukit/score/src/schedulercbsgetapprovedbudget.c | 7 +++++ cpukit/score/src/schedulercbsgetremainingbudget.c | 7 +++++ .../score/src/schedulerpriorityprioritycompare.c | 7 +++++ cpukit/score/src/schedulerpriorityreleasejob.c | 7 +++++ cpukit/score/src/schedulerpriorityunblock.c | 7 +++++ cpukit/score/src/schedulersimpleenqueuefirst.c | 9 ++++-- cpukit/score/src/smplock.c | 13 +++++---- cpukit/score/src/threadqenqueuefifo.c | 25 +++++----------- cpukit/score/src/threadqrequeue.c | 25 +++++----------- cpukit/score/src/threadsetpriority.c | 9 ++++-- cpukit/score/src/ts64dividebyinteger.c | 7 +++-- cpukit/score/src/watchdogadjust.c | 24 +++++----------- 26 files changed, 165 insertions(+), 138 deletions(-) (limited to 'cpukit') diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index cb8ce98475..c864685689 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -257,8 +257,15 @@ typedef struct { /** * @brief Initialize a Message Queue + * + * DESCRIPTION: + * + * This package is the implementation of the CORE Message Queue Handler. + * This core object provides task synchronization and communication functions + * via messages passed to queue objects. * - * This routine initializes @a the_message_queue based on the parameters passed. + * This routine initializes @a the_message_queue + * based on the parameters passed. * * @param[in] the_message_queue points to the message queue to initialize * @param[in] the_message_queue_attributes points to the attributes that diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index fc4d0baa34..c8d7deb703 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -127,6 +127,14 @@ typedef struct { } CORE_semaphore_Control; /** + * @brief Core Semaphore Initialize + * + * DESCRIPTION: + * + * This package is the implementation of the CORE Semaphore Handler. + * This core object utilizes standard Dijkstra counting semaphores to provide + * synchronization and mutual exclusion capabilities. + * * This routine initializes the semaphore based on the parameters passed. * * @param[in] the_semaphore is the semaphore to initialize diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index e8ee057368..c9176e7e5b 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -697,6 +697,8 @@ Objects_Control *_Objects_Get_isr_disable( ); /** + * @brief Get No protection 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 21239683a9..63e36696cd 100644 --- a/cpukit/score/include/rtems/score/schedulerpriority.h +++ b/cpukit/score/include/rtems/score/schedulerpriority.h @@ -121,6 +121,8 @@ void _Scheduler_priority_Update( ); /** + * @brief Scheduler Priority 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/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h index 6237e5c4a1..97b571d6a6 100644 --- a/cpukit/score/include/rtems/score/schedulersimple.h +++ b/cpukit/score/include/rtems/score/schedulersimple.h @@ -119,6 +119,8 @@ void _Scheduler_simple_Enqueue( ); /** + * @brief Scheduler simple Enqueue first + * * This routine puts @a the_thread to the head of the ready queue. * The thread will be the first thread at its priority level. * diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index fdacd41564..fd49b8c340 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -708,6 +708,8 @@ void _Thread_Change_priority ( ); /** + * @brief Set Thread Priority + * * This routine updates the priority related fields in the_thread * control block to indicate the current priority is now new_priority. */ diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index db832f4860..1999ea14ff 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -109,6 +109,9 @@ void _Thread_queue_Enqueue_with_handler( * the_thread is removed from the_thread_queue and reinserted using * its new priority. This method has no impact on the state of the_thread * or of any timeouts associated with this blocking. + * + * @param[in] the_thread_queue pointer to a threadq header + * @param[in] the_thread pointer to a thread control block */ void _Thread_queue_Requeue( Thread_queue_Control *the_thread_queue, @@ -254,6 +257,13 @@ Thread_Control *_Thread_queue_Dequeue_fifo( * This routine enqueues the currently executing thread on * the_thread_queue with an optional timeout using the * FIFO discipline. + * + * @param[in] the_thread_queue pointer to threadq + * @param[in] the_thread pointer to the thread to block + * @param[in] level_p interrupt level in case the operation blocks actually + * + * - INTERRUPT LATENCY: + * + single case */ Thread_blocking_operation_States _Thread_queue_Enqueue_fifo ( Thread_queue_Control *the_thread_queue, diff --git a/cpukit/score/src/coremsg.c b/cpukit/score/src/coremsg.c index c55d2d5a82..e02989b81d 100644 --- a/cpukit/score/src/coremsg.c +++ b/cpukit/score/src/coremsg.c @@ -1,12 +1,11 @@ -/* - * CORE Message Queue Handler - * - * DESCRIPTION: - * - * This package is the implementation of the CORE Message Queue Handler. - * This core object provides task synchronization and communication functions - * via messages passed to queue objects. +/** + * @file * + * @brief Initialize a Message Queue + * @ingroup ScoreMessageQueue + */ + +/* * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). * @@ -49,24 +48,6 @@ static inline bool size_t_mult32_with_overflow( return true; } -/* - * _CORE_message_queue_Initialize - * - * This routine initializes a newly created message queue based on the - * specified data. - * - * Input parameters: - * the_message_queue - the message queue to initialize - * the_class - the API specific object class - * the_message_queue_attributes - the message queue's attributes - * maximum_pending_messages - maximum message and reserved buffer count - * maximum_message_size - maximum size of each message - * - * Output parameters: - * true - if the message queue is initialized - * false - if the message queue is NOT initialized - */ - bool _CORE_message_queue_Initialize( CORE_message_queue_Control *the_message_queue, CORE_message_queue_Attributes *the_message_queue_attributes, diff --git a/cpukit/score/src/coresem.c b/cpukit/score/src/coresem.c index f0fa9f40d4..03b9c5e6a8 100644 --- a/cpukit/score/src/coresem.c +++ b/cpukit/score/src/coresem.c @@ -1,12 +1,11 @@ -/* - * CORE Semaphore Handler - * - * DESCRIPTION: - * - * This package is the implementation of the CORE Semaphore Handler. - * This core object utilizes standard Dijkstra counting semaphores to provide - * synchronization and mutual exclusion capabilities. +/** + * @file * + * @brief Core Semaphore Initialize + * @ingroup ScoreSemaphore + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * @@ -26,20 +25,6 @@ #include #include -/* - * CORE_semaphore_Initialize - * - * This function initialize a semaphore and sets the initial value based - * on the given count. - * - * Input parameters: - * the_semaphore - the semaphore control block to initialize - * the_semaphore_attributes - the attributes specified at create time - * initial_value - semaphore's initial value - * - * Output parameters: NONE - */ - void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, CORE_semaphore_Attributes *the_semaphore_attributes, diff --git a/cpukit/score/src/coretodget.c b/cpukit/score/src/coretodget.c index 448bc7ba55..dbee757f25 100644 --- a/cpukit/score/src/coretodget.c +++ b/cpukit/score/src/coretodget.c @@ -1,6 +1,11 @@ -/* - * Time of Day (TOD) Handler - get TOD +/** + * @file * + * @brief Returns a Current TOD with Nanosecond Granularity + * @ingroup ScoreTODConstants + */ + +/* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/coretodtickspersec.c b/cpukit/score/src/coretodtickspersec.c index 21e7201253..3dc792a6d3 100644 --- a/cpukit/score/src/coretodtickspersec.c +++ b/cpukit/score/src/coretodtickspersec.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Convert Ticks To Seconds + * @ingroup ScoreTODConstants + */ + /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/objectgetnoprotection.c b/cpukit/score/src/objectgetnoprotection.c index 8d283abd59..30b61cc41d 100644 --- a/cpukit/score/src/objectgetnoprotection.c +++ b/cpukit/score/src/objectgetnoprotection.c @@ -1,7 +1,11 @@ -/* - * Object Handler -- Object Get - * +/** + * @file * + * @brief Get Object without Dispatching Protection + * @ingroup ScoreObject + */ + +/* * COPYRIGHT (c) 1989-2002. * On-Line Applications Research Corporation (OAR). * @@ -26,25 +30,6 @@ #include #include -/* - * _Objects_Get_no_protection - * - * 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_no_protection( Objects_Information *information, Objects_Id id, diff --git a/cpukit/score/src/schedulercbscleanup.c b/cpukit/score/src/schedulercbscleanup.c index 392c995ef5..abffeafdc6 100644 --- a/cpukit/score/src/schedulercbscleanup.c +++ b/cpukit/score/src/schedulercbscleanup.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler CBS Cleanup + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulercbscreateserver.c b/cpukit/score/src/schedulercbscreateserver.c index 2780a71f2d..9f69fba821 100644 --- a/cpukit/score/src/schedulercbscreateserver.c +++ b/cpukit/score/src/schedulercbscreateserver.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler CBS Create Server + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulercbsgetapprovedbudget.c b/cpukit/score/src/schedulercbsgetapprovedbudget.c index bf2877f90f..8558f87399 100644 --- a/cpukit/score/src/schedulercbsgetapprovedbudget.c +++ b/cpukit/score/src/schedulercbsgetapprovedbudget.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler CBS Get Approved Budget + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulercbsgetremainingbudget.c b/cpukit/score/src/schedulercbsgetremainingbudget.c index 4e32181f88..2d79995a46 100644 --- a/cpukit/score/src/schedulercbsgetremainingbudget.c +++ b/cpukit/score/src/schedulercbsgetremainingbudget.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler CBS Get Remaining Budget + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulerpriorityprioritycompare.c b/cpukit/score/src/schedulerpriorityprioritycompare.c index 962adc4868..7d37707986 100644 --- a/cpukit/score/src/schedulerpriorityprioritycompare.c +++ b/cpukit/score/src/schedulerpriorityprioritycompare.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler Priority Compare Two Priorities + * @ingroup ScoreScheduler + */ + /* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulerpriorityreleasejob.c b/cpukit/score/src/schedulerpriorityreleasejob.c index 9c2864dd00..a62a10a850 100644 --- a/cpukit/score/src/schedulerpriorityreleasejob.c +++ b/cpukit/score/src/schedulerpriorityreleasejob.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler Priority Release Job + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulerpriorityunblock.c b/cpukit/score/src/schedulerpriorityunblock.c index 4a45877520..f1d52e39dd 100644 --- a/cpukit/score/src/schedulerpriorityunblock.c +++ b/cpukit/score/src/schedulerpriorityunblock.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler Priority Unblock + * @ingroup ScoreScheduler + */ + /* * Scheduler Handler * diff --git a/cpukit/score/src/schedulersimpleenqueuefirst.c b/cpukit/score/src/schedulersimpleenqueuefirst.c index 4f562a4a95..354bbc72b7 100644 --- a/cpukit/score/src/schedulersimpleenqueuefirst.c +++ b/cpukit/score/src/schedulersimpleenqueuefirst.c @@ -1,6 +1,11 @@ -/* - * Schedule Simple Handler / Enqueue First +/** + * @file * + * @brief Scheduler Simple Enqueue First + * @ingroup ScoreScheduler + */ + +/* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/smplock.c b/cpukit/score/src/smplock.c index 9ef4e07042..89f8a866dd 100644 --- a/cpukit/score/src/smplock.c +++ b/cpukit/score/src/smplock.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief SMP Locking Support + * @ingroup RTEMS + */ + /* * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). @@ -67,9 +74,6 @@ #define debug_dump_log() #endif -/* - * SMP spinlock simple methods - */ void _SMP_lock_spinlock_simple_Initialize( SMP_lock_spinlock_simple_Control *lock ) @@ -105,9 +109,6 @@ void _SMP_lock_spinlock_simple_Release( _ISR_Enable_on_this_core( level ); } -/* - * SMP spinlock nested methods. - */ void _SMP_lock_spinlock_nested_Initialize( SMP_lock_spinlock_nested_Control *lock ) diff --git a/cpukit/score/src/threadqenqueuefifo.c b/cpukit/score/src/threadqenqueuefifo.c index b873ba060b..ab1404cf72 100644 --- a/cpukit/score/src/threadqenqueuefifo.c +++ b/cpukit/score/src/threadqenqueuefifo.c @@ -1,7 +1,11 @@ -/* - * Thread Queue Handler - * +/** + * @file * + * @brief Thread queue Enqueue FIFO + * @ingroup ScoreThreadQ + */ + +/* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * @@ -23,21 +27,6 @@ #include #include -/* - * _Thread_queue_Enqueue_fifo - * - * This routine places a blocked thread on a FIFO thread queue. - * - * Input parameters: - * the_thread_queue - pointer to threadq - * the_thread - pointer to the thread to block - * - * Output parameters: NONE - * - * INTERRUPT LATENCY: - * only case - */ - Thread_blocking_operation_States _Thread_queue_Enqueue_fifo ( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread, diff --git a/cpukit/score/src/threadqrequeue.c b/cpukit/score/src/threadqrequeue.c index 769f7090d7..15cf0119b4 100644 --- a/cpukit/score/src/threadqrequeue.c +++ b/cpukit/score/src/threadqrequeue.c @@ -1,7 +1,11 @@ -/* - * Thread Queue Handler - * +/** + * @file * + * @brief Thread Queue Requeue + * @ingroup ScoreThreadQ + */ + +/* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * @@ -23,21 +27,6 @@ #include #include -/* - * _Thread_queue_Requeue - * - * This routine is invoked when a thread changes priority and should be - * moved to a different position on the thread queue. - * - * Input parameters: - * the_thread_queue - pointer to a threadq header - * the_thread - pointer to a thread control block - * - * Output parameters: NONE - * - * INTERRUPT LATENCY: NONE - */ - void _Thread_queue_Requeue( Thread_queue_Control *the_thread_queue, Thread_Control *the_thread diff --git a/cpukit/score/src/threadsetpriority.c b/cpukit/score/src/threadsetpriority.c index a500624bb1..1ae4a27197 100644 --- a/cpukit/score/src/threadsetpriority.c +++ b/cpukit/score/src/threadsetpriority.c @@ -1,6 +1,11 @@ -/* - * Thread Handler / Thread Set Priority +/** + * @file * + * @brief Set Thread Priority + * @ingroup ScoreThread + */ + +/* * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/ts64dividebyinteger.c b/cpukit/score/src/ts64dividebyinteger.c index b48c188977..55dc816a8f 100644 --- a/cpukit/score/src/ts64dividebyinteger.c +++ b/cpukit/score/src/ts64dividebyinteger.c @@ -1,6 +1,9 @@ /** - * @file score/src/ts64dividebyinteger.c -*/ + * @file + * + * @brief Divide Timestamp By Integer + * @ingroup SuperCore + */ /* * COPYRIGHT (c) 1989-2008. diff --git a/cpukit/score/src/watchdogadjust.c b/cpukit/score/src/watchdogadjust.c index 5dc4b31895..b0723d0f0f 100644 --- a/cpukit/score/src/watchdogadjust.c +++ b/cpukit/score/src/watchdogadjust.c @@ -1,7 +1,11 @@ -/* - * Watchdog Handler - * +/** + * @file * + * @brief Watchdog Adjust + * @ingroup ScoreWatchdog + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * @@ -18,20 +22,6 @@ #include #include -/* - * _Watchdog_Adjust - * - * This routine adjusts the delta chain backward or forward in response - * to a time change. - * - * Input parameters: - * header - pointer to the delta chain to be adjusted - * direction - forward or backward adjustment to delta chain - * units - units to adjust - * - * Output parameters: - */ - void _Watchdog_Adjust( Chain_Control *header, Watchdog_Adjust_directions direction, -- cgit v1.2.3