score misc: Score misc: Clean up Doxygen #5

20 files changed, 133 insertions, 223 deletions

diff --git a/cpukit/score/src/coremsgbroadcast.c b/cpukit/score/src/coremsgbroadcast.c
index d5d1f95563..7cee3e8fce 100644
--- a/cpukit/score/src/coremsgbroadcast.c
+++ b/cpukit/score/src/coremsgbroadcast.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 Broadcast a Message to the Message Queue
+ *  @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,26 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Broadcast
- *
- *  This function sends a message for every thread waiting on the queue and
- *  returns the number of threads made ready by the message.
- *
- *  Input parameters:
- *    the_message_queue            - message is submitted to this message queue
- *    buffer                       - pointer to message buffer
- *    size                         - size in bytes of message to send
- *    id                           - id of message queue
- *    api_message_queue_mp_support - api specific mp support callout
- *    count                        - area to store number of threads made ready
- *
- *  Output parameters:
- *    count                         - number of threads made ready
- *    CORE_MESSAGE_QUEUE_SUCCESSFUL - if successful
- *    error code                    - if unsuccessful
- */
-
 CORE_message_queue_Status _CORE_message_queue_Broadcast(
   CORE_message_queue_Control                *the_message_queue,
   const void                                *buffer,
diff --git a/cpukit/score/src/coremsgclose.c b/cpukit/score/src/coremsgclose.c
index 930c0adea9..38b0183fb0 100644
--- a/cpukit/score/src/coremsgclose.c
+++ b/cpukit/score/src/coremsgclose.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 Close a Message Queue
+ *  @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,20 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Close
- *
- *  This function closes a message by returning all allocated space and
- *  flushing the message_queue's task wait queue.
- *
- *  Input parameters:
- *    the_message_queue      - the message_queue to be flushed
- *    remote_extract_callout - function to invoke remotely
- *    status                 - status to pass to thread
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_message_queue_Close(
   CORE_message_queue_Control *the_message_queue,
   Thread_queue_Flush_callout  remote_extract_callout,
diff --git a/cpukit/score/src/coremsgflush.c b/cpukit/score/src/coremsgflush.c
index 0faf6c3c26..0681cbb0b7 100644
--- a/cpukit/score/src/coremsgflush.c
+++ b/cpukit/score/src/coremsgflush.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 Flush Pending Messages
+ *  @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,19 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Flush
- *
- *  This function flushes the message_queue's pending message queue.  The
- *  number of messages flushed from the queue is returned.
- *
- *  Input parameters:
- *    the_message_queue - the message_queue to be flushed
- *
- *  Output parameters:
- *    returns - the number of messages flushed from the queue
- */
-
 uint32_t   _CORE_message_queue_Flush(
   CORE_message_queue_Control *the_message_queue
 )
diff --git a/cpukit/score/src/coremsgseize.c b/cpukit/score/src/coremsgseize.c
index 84652d1b77..bb49810bbd 100644
--- a/cpukit/score/src/coremsgseize.c
+++ b/cpukit/score/src/coremsgseize.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 Size a Message from the Message Queue
+ *  @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,31 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Seize
- *
- *  This kernel routine dequeues a message, copies the message buffer to
- *  a given destination buffer, and frees the message buffer to the
- *  inactive message pool.  The thread will be blocked if wait is true,
- *  otherwise an error will be given to the thread if no messages are available.
- *
- *  Input parameters:
- *    the_message_queue - pointer to message queue
- *    id                - id of object we are waitig on
- *    buffer            - pointer to message buffer to be filled
- *    size_p            - pointer to the size of buffer to be filled
- *    wait              - true if wait is allowed, false otherwise
- *    timeout           - time to wait for a message
- *
- *  Output parameters:  NONE
- *
- *  NOTE: Dependent on BUFFER_LENGTH
- *
- *  INTERRUPT LATENCY:
- *    available
- *    wait
- */
-
 void _CORE_message_queue_Seize(
   CORE_message_queue_Control      *the_message_queue,
   Objects_Id                       id,
diff --git a/cpukit/score/src/coresemflush.c b/cpukit/score/src/coresemflush.c
index 5958159138..f0f819de2b 100644
--- a/cpukit/score/src/coresemflush.c
+++ b/cpukit/score/src/coresemflush.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 Flush
+ *  @ingroup ScoreSemaphore
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,19 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_semaphore_Flush
- *
- *  This function a flushes the semaphore's task wait queue.
- *
- *  Input parameters:
- *    the_semaphore          - the semaphore to be flushed
- *    remote_extract_callout - function to invoke remotely
- *    status                 - status to pass to thread
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_semaphore_Flush(
   CORE_semaphore_Control     *the_semaphore,
   Thread_queue_Flush_callout  remote_extract_callout,
diff --git a/cpukit/score/src/isrsmp.c b/cpukit/score/src/isrsmp.c
index e9504b502a..7fb3f75bc3 100644
--- a/cpukit/score/src/isrsmp.c
+++ b/cpukit/score/src/isrsmp.c
@@ -1,6 +1,11 @@
-/*
- *  ISR Enable/Disable for SMP Configurations
+/**
+ *  @file
  *
+ *  @brief Initialize, Disable, Enable, Flash, Enter, Exit ISR Implementation
+ *  @ingroup ScoreISR
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -57,11 +62,6 @@ int _ISR_SMP_Enter(void)
   return isr_nest_level;
 }
 
-/*
- *  Return values:
- *     0 - simple return
- *     1 - dispatching return
- */
 int _ISR_SMP_Exit(void)
 {
   ISR_Level level;
diff --git a/cpukit/score/src/objectgetinfo.c b/cpukit/score/src/objectgetinfo.c
index 416726343f..3955acc3ca 100644
--- a/cpukit/score/src/objectgetinfo.c
+++ b/cpukit/score/src/objectgetinfo.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get Object Information
+ *  @ingroup ScoreObject
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbsattachthread.c b/cpukit/score/src/schedulercbsattachthread.c
index 9641cc57e5..56602a22d1 100644
--- a/cpukit/score/src/schedulercbsattachthread.c
+++ b/cpukit/score/src/schedulercbsattachthread.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Attach Scheduler CBS Thread
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbsgetserverid.c b/cpukit/score/src/schedulercbsgetserverid.c
index 5147621e4d..e0f35779f6 100644
--- a/cpukit/score/src/schedulercbsgetserverid.c
+++ b/cpukit/score/src/schedulercbsgetserverid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler CBS Get Server id
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfschedule.c b/cpukit/score/src/scheduleredfschedule.c
index a45aca41d3..dbe21dc491 100644
--- a/cpukit/score/src/scheduleredfschedule.c
+++ b/cpukit/score/src/scheduleredfschedule.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler EDF Allocate
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011-2012 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityyield.c b/cpukit/score/src/schedulerpriorityyield.c
index 62c3807982..c000125daf 100644
--- a/cpukit/score/src/schedulerpriorityyield.c
+++ b/cpukit/score/src/schedulerpriorityyield.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Priority Handler / Yield
+/**
+ *  @file
  *
+ *  @brief Scheduler Priority Yield
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  Copyright (C) 2010 Gedare Bloom.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
@@ -19,12 +24,6 @@
 #include <rtems/score/schedulerpriority.h>
 #include <rtems/score/thread.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    ready chain
- *    select heir
- */
-
 void _Scheduler_priority_Yield(void)
 {
   Scheduler_priority_Per_thread *sched_info;
diff --git a/cpukit/score/src/schedulersimplesmptick.c b/cpukit/score/src/schedulersimplesmptick.c
index 3be87db846..72f8b1f761 100644
--- a/cpukit/score/src/schedulersimplesmptick.c
+++ b/cpukit/score/src/schedulersimplesmptick.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler Simple SMP Tick Method
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/smp.c b/cpukit/score/src/smp.c
index f0b576ee8c..cd4d2350ba 100644
--- a/cpukit/score/src/smp.c
+++ b/cpukit/score/src/smp.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief SMP Support
+ *  @ingroup Score
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
@@ -42,9 +49,6 @@ void rtems_smp_run_first_task(int cpu)
   _CPU_Context_switch_to_first_task_smp( &heir->Registers );
 }
 
-/*
- *  Process request to initialize this secondary core.
- */
 void rtems_smp_secondary_cpu_initialize(void)
 {
   int       cpu;
@@ -90,10 +94,6 @@ void rtems_smp_secondary_cpu_initialize(void)
   }
 }
 
-/*
- *  Process an interrupt processor interrupt which indicates a request
- *  from another core.
- */
 void rtems_smp_process_interrupt(void)
 {
   int        cpu;
@@ -179,9 +179,6 @@ void _SMP_Send_message(
   bsp_smp_interrupt_cpu( cpu );
 }
 
-/*
- *  Send interrupt processor request to all other nodes
- */
 void _SMP_Broadcast_message(
   uint32_t  message
 )
@@ -202,9 +199,6 @@ void _SMP_Broadcast_message(
   bsp_smp_broadcast_interrupt();
 }
 
-/*
- *  Send interrupt processor requests to perform first context switch 
- */
 void _SMP_Request_other_cores_to_perform_first_context_switch(void)
 {
   int    cpu;
@@ -215,10 +209,6 @@ void _SMP_Request_other_cores_to_perform_first_context_switch(void)
   }
 }
 
-/*
- *  Send message to other cores requesting them to perform
- *  a thread dispatch operation.
- */
 void _SMP_Request_other_cores_to_dispatch(void)
 {
   int i;
@@ -239,9 +229,6 @@ void _SMP_Request_other_cores_to_dispatch(void)
   }
 }
 
-/*
- *  Send message to other cores requesting them to shutdown.
- */
 void _SMP_Request_other_cores_to_shutdown(void)
 {
   bool   allDown;
diff --git a/cpukit/score/src/threadclearstate.c b/cpukit/score/src/threadclearstate.c
index 492f5336fc..cf59f3b561 100644
--- a/cpukit/score/src/threadclearstate.c
+++ b/cpukit/score/src/threadclearstate.c
@@ -1,6 +1,11 @@
-/*
- *  Thread Handler / Thread Clear State
+/**
+ *  @file
  *
+ *  @brief Clear Thread state
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,11 +32,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    priority map
- *    select heir
- */
 void _Thread_Clear_state(
   Thread_Control *the_thread,
   States_Control  state
diff --git a/cpukit/score/src/threadcreateidle.c b/cpukit/score/src/threadcreateidle.c
index 1f10065e5b..a0279dec49 100644
--- a/cpukit/score/src/threadcreateidle.c
+++ b/cpukit/score/src/threadcreateidle.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Handler
- *
+/**
+ *  @file
  *
+ *  @brief Create Idle Thread
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadmp.c b/cpukit/score/src/threadmp.c
index 426d68684f..9b85873f7d 100644
--- a/cpukit/score/src/threadmp.c
+++ b/cpukit/score/src/threadmp.c
@@ -1,7 +1,11 @@
-/*
- *  Multiprocessing Support for the Thread Handler
- *
+/**
+ *  @file
  *
+ *  @brief Distributed MP Support
+ *  @ingroup ScoreThreadMP
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,11 +25,6 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _Thread_MP_Handler_initialization
- *
- */
-
 void _Thread_MP_Handler_initialization (
   uint32_t    maximum_proxies
 )
@@ -50,11 +49,6 @@ void _Thread_MP_Handler_initialization (
 
 }
 
-/*
- *  _Thread_MP_Allocate_proxy
- *
- */
-
 Thread_Control *_Thread_MP_Allocate_proxy (
   States_Control  the_state
 )
@@ -101,11 +95,6 @@ Thread_Control *_Thread_MP_Allocate_proxy (
 }
 
 /*
- *  _Thread_MP_Find_proxy
- *
- */
-
-/*
  *  The following macro provides the offset of the Active element
  *  in the Thread_Proxy_control structure.  This is the logical
  *  equivalent of the POSITION attribute in Ada.
diff --git a/cpukit/score/src/threadstackfree.c b/cpukit/score/src/threadstackfree.c
index 1c20bad349..8a441009ec 100644
--- a/cpukit/score/src/threadstackfree.c
+++ b/cpukit/score/src/threadstackfree.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Handler
- *
+/**
+ *  @file
  *
+ *  @brief Deallocate Thread Stack
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,12 +32,6 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/config.h>
 
-/*
- *  _Thread_Stack_Free
- *
- *  Deallocate the Thread's stack.
- */
-
 void _Thread_Stack_Free(
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/threadstartmultitasking.c b/cpukit/score/src/threadstartmultitasking.c
index acc5b26f75..32a594bd3b 100644
--- a/cpukit/score/src/threadstartmultitasking.c
+++ b/cpukit/score/src/threadstartmultitasking.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Handler
- *
+/**
+ *  @file
  *
+ *  @brief Start Thread Multitasking
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,26 +31,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Start_multitasking
- *
- *  This kernel routine readies the requested thread, the thread chain
- *  is adjusted.  A new heir thread may be selected.
- *
- *  Input parameters:
- *    system_thread - pointer to system initialization thread control block
- *    idle_thread   - pointer to idle thread control block
- *
- *  Output parameters:  NONE
- *
- *  NOTE:  This routine uses the "blocking" heir selection mechanism.
- *         This ensures the correct heir after a thread restart.
- *
- *  INTERRUPT LATENCY:
- *    ready chain
- *    select heir
- */
-
 void _Thread_Start_multitasking( void )
 {
   /*
diff --git a/cpukit/score/src/timespeclessthan.c b/cpukit/score/src/timespeclessthan.c
index fedf83cba3..c120ae97b6 100644
--- a/cpukit/score/src/timespeclessthan.c
+++ b/cpukit/score/src/timespeclessthan.c
@@ -1,5 +1,8 @@
 /**
- *  @file  score/src/timespeclessthan.c
+ *  @file
+ *
+ *  @brief Timespec Less Than Operator
+ *  @ingroup Timespec
  */
 
 /*
diff --git a/cpukit/score/src/watchdogreportchain.c b/cpukit/score/src/watchdogreportchain.c
index aeea191cf5..ea6c2f7415 100644
--- a/cpukit/score/src/watchdogreportchain.c
+++ b/cpukit/score/src/watchdogreportchain.c
@@ -1,7 +1,8 @@
 /**
- *  @file watchdogreportchain.c
+ *  @file
  *
- *  This should only be used for debugging.
+ *  @brief Report Information on a Watchdog Chain
+ *  @ingroup ScoreWatchdog
  */
 
 /*  COPYRIGHT (c) 1989-2008.