score misc: Clean up Doxygen #13 (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/8013205

28 files changed, 175 insertions, 21 deletions

diff --git a/cpukit/score/cpu/arm/armv7m-context-switch.c b/cpukit/score/cpu/arm/armv7m-context-switch.c
index bb73c6671a..0fd3c206d0 100644
--- a/cpukit/score/cpu/arm/armv7m-context-switch.c
+++ b/cpukit/score/cpu/arm/armv7m-context-switch.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief ARM7M CPU Context Switch
+ */
+
 /*
  * Copyright (c) 2011 Sebastian Huber.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c b/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c
index 726db75e20..de0b020f23 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief ARMV7M Set Exception Priority and Handler
+ */
+
 /*
  * Copyright (c) 2012 Sebastian Huber.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/arm/armv7m-initialize.c b/cpukit/score/cpu/arm/armv7m-initialize.c
index 79647d1ad6..cb3c19656d 100644
--- a/cpukit/score/cpu/arm/armv7m-initialize.c
+++ b/cpukit/score/cpu/arm/armv7m-initialize.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief ARM7M CPU Initialize
+ */
+
 /*
  * Copyright (c) 2011 Sebastian Huber.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/arm/armv7m-isr-dispatch.c b/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
index 42ea404f0f..7c2cd7370c 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief ARMV7M ISR Dispatch
+ */
+
 /*
  * Copyright (c) 2011 Sebastian Huber.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c b/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
index 1827f97dfa..d27bf8b009 100644
--- a/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
+++ b/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief ARMV7M Start and Stop Multitasking
+ */
+
 /*
  * Copyright (c) 2011 Sebastian Huber.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/arm/rtems/score/armv7m.h b/cpukit/score/cpu/arm/rtems/score/armv7m.h
index b561369f37..62f69ff490 100644
--- a/cpukit/score/cpu/arm/rtems/score/armv7m.h
+++ b/cpukit/score/cpu/arm/rtems/score/armv7m.h
@@ -457,6 +457,10 @@ void _ARMV7M_Set_exception_handler(
   ARMV7M_Exception_handler handler
 );
 
+/**
+ *  @brief ARMV7M Set Exception Priority and Handler
+ *
+ */
 void _ARMV7M_Set_exception_priority_and_handler(
   int index,
   int priority,
diff --git a/cpukit/score/cpu/arm/rtems/score/cpu.h b/cpukit/score/cpu/arm/rtems/score/cpu.h
index e69f8037dc..c1ffb0765d 100644
--- a/cpukit/score/cpu/arm/rtems/score/cpu.h
+++ b/cpukit/score/cpu/arm/rtems/score/cpu.h
@@ -398,6 +398,10 @@ void _CPU_Context_Initialize(
      while (1);                             \
    } while (0);
 
+/**
+ *  @brief CPU Initialize
+ *
+ */
 void _CPU_Initialize( void );
 
 void _CPU_ISR_install_vector(
@@ -406,6 +410,10 @@ void _CPU_ISR_install_vector(
   proc_ptr *old_handler
 );
 
+/**
+ *  @brief CPU Context Switch
+ *
+ */
 void _CPU_Context_switch( Context_Control *run, Context_Control *heir );
 
 void _CPU_Context_restore( Context_Control *new_context )
diff --git a/cpukit/score/cpu/bfin/cpu.c b/cpukit/score/cpu/bfin/cpu.c
index 2f620fbfe0..05b9243513 100644
--- a/cpukit/score/cpu/bfin/cpu.c
+++ b/cpukit/score/cpu/bfin/cpu.c
@@ -1,5 +1,10 @@
-/*  Blackfin CPU Dependent Source
+/**
+ * @file
  *
+ * @brief Blackfin CPU Dependent Source
+ */
+
+/*
  *  COPYRIGHT (c) 2006 by Atos Automacao Industrial Ltda.
  *             written by Alain Schaefer <alain.schaefer@easc.ch>
  *                    and Antonio Giovanini <antonio@atos.com.br>
diff --git a/cpukit/score/cpu/bfin/rtems/score/cpu.h b/cpukit/score/cpu/bfin/rtems/score/cpu.h
index 85d5cd8ae6..f6fab7543b 100644
--- a/cpukit/score/cpu/bfin/rtems/score/cpu.h
+++ b/cpukit/score/cpu/bfin/rtems/score/cpu.h
@@ -1065,6 +1065,7 @@ void _CPU_Context_Initialize(
 /* functions */
 
 /**
+ *  @brief CPU Initialize
  *  This routine performs CPU dependent initialization.
  *
  *  Port Specific Information:
diff --git a/cpukit/score/cpu/m32r/context_init.c b/cpukit/score/cpu/m32r/context_init.c
index ab974242e7..bdfd758d91 100644
--- a/cpukit/score/cpu/m32r/context_init.c
+++ b/cpukit/score/cpu/m32r/context_init.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief M32R CPU Context Initialize
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/cpu/m32r/cpu.c b/cpukit/score/cpu/m32r/cpu.c
index b274ecb63f..238174634f 100644
--- a/cpukit/score/cpu/m32r/cpu.c
+++ b/cpukit/score/cpu/m32r/cpu.c
@@ -1,6 +1,10 @@
-/*
- *  M32R CPU Dependent Source
+/**
+ * @file
  *
+ * @brief M32R CPU Support
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/cpu/m32r/cpu_asm.c b/cpukit/score/cpu/m32r/cpu_asm.c
index a4db4ae6b2..1af93a78be 100644
--- a/cpukit/score/cpu/m32r/cpu_asm.c
+++ b/cpukit/score/cpu/m32r/cpu_asm.c
@@ -1,10 +1,18 @@
-/*  cpu_asm.c  ===> cpu_asm.S or cpu_asm.s
+/**
+ * @file
  *
- *  NOTE:  This is supposed to be a .S or .s file NOT a C file.
+ * @brief M32R ISR Handler
+ *
+ *  cpu_asm.c  ===> cpu_asm.S or cpu_asm.s
+ *
+ *  @note This is supposed to be a .S or .s file NOT a C file.
  *
  *  M32R does not yet have interrupt support.  When this functionality
  *  is written, this file should become obsolete.
  *
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/cpu/m32r/rtems/score/cpu.h b/cpukit/score/cpu/m32r/rtems/score/cpu.h
index df5b196382..d6886ffefc 100644
--- a/cpukit/score/cpu/m32r/rtems/score/cpu.h
+++ b/cpukit/score/cpu/m32r/rtems/score/cpu.h
@@ -795,6 +795,7 @@ uint32_t   _CPU_ISR_Get_level( void );
 /* Context handler macros */
 
 /**
+ *  @brief CPU Context Initialize
  *  @ingroup CPUContext
  *  Initialize the context to a state suitable for starting a
  *  task after a context restore operation.  Generally, this
@@ -1062,6 +1063,7 @@ void _CPU_Context_Restart_self(
 /* functions */
 
 /**
+ *  @brief CPU Initialize
  *  This routine performs CPU dependent initialization.
  *
  *  Port Specific Information:
diff --git a/cpukit/score/cpu/nios2/irq.c b/cpukit/score/cpu/nios2/irq.c
index b7123151f0..5750f1311f 100644
--- a/cpukit/score/cpu/nios2/irq.c
+++ b/cpukit/score/cpu/nios2/irq.c
@@ -1,8 +1,12 @@
-/*
- *  NIOS2 exception and interrupt handler
+/**
+ * @file
  *
- *  Derived from c4x/irq.c
+ * @brief NIOS2 Exception and Interrupt Handler
  *
+ * @note Derived from c4x/irq.c
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -78,7 +82,7 @@ RTEMS_INLINE_ROUTINE void __IIC_Handler(void)
 
     active = _Nios2_Get_ctlreg_ipending();
   }
-  
+
 }
 
 void __ISR_Handler(void)
@@ -100,7 +104,7 @@ void __ISR_Handler(void)
   _Thread_Dispatch_increment_disable_level();
 
   __IIC_Handler();
-  
+
   /* Make sure that interrupts are disabled again */
   _CPU_ISR_Disable( level );
 
diff --git a/cpukit/score/cpu/nios2/nios2-initialize.c b/cpukit/score/cpu/nios2/nios2-initialize.c
index e192d774e6..6f316b8dd0 100644
--- a/cpukit/score/cpu/nios2/nios2-initialize.c
+++ b/cpukit/score/cpu/nios2/nios2-initialize.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 CPU Initialize
+ */
+
 /*
  * Copyright (c) 2006 Kolja Waschk (rtemsdev/ixo.de)
  *
diff --git a/cpukit/score/cpu/nios2/nios2-isr-install-raw-handler.c b/cpukit/score/cpu/nios2/nios2-isr-install-raw-handler.c
index ee566b8a64..702a36792e 100644
--- a/cpukit/score/cpu/nios2/nios2-isr-install-raw-handler.c
+++ b/cpukit/score/cpu/nios2/nios2-isr-install-raw-handler.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 CPU ISR Install Raw Handler
+ */
+
 /*
  * Copyright (c) 2006 Kolja Waschk (rtemsdev/ixo.de)
  *
diff --git a/cpukit/score/cpu/nios2/nios2-isr-install-vector.c b/cpukit/score/cpu/nios2/nios2-isr-install-vector.c
index cf5cc278c6..eed1a38242 100644
--- a/cpukit/score/cpu/nios2/nios2-isr-install-vector.c
+++ b/cpukit/score/cpu/nios2/nios2-isr-install-vector.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 CPU ISR Install Vector
+ */
+
 /*
  * Copyright (c) 2006 Kolja Waschk (rtemsdev/ixo.de)
  *
diff --git a/cpukit/score/cpu/nios2/nios2-isr-set-level.c b/cpukit/score/cpu/nios2/nios2-isr-set-level.c
index 99964764ae..a753a4f7a6 100644
--- a/cpukit/score/cpu/nios2/nios2-isr-set-level.c
+++ b/cpukit/score/cpu/nios2/nios2-isr-set-level.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 ISR Set Level
+ */
+
 /*
  * Copyright (c) 2011 embedded brains GmbH
  *
diff --git a/cpukit/score/cpu/nios2/nios2-mpu-descriptor.c b/cpukit/score/cpu/nios2/nios2-mpu-descriptor.c
index dd97a29023..126320f9c5 100644
--- a/cpukit/score/cpu/nios2/nios2-mpu-descriptor.c
+++ b/cpukit/score/cpu/nios2/nios2-mpu-descriptor.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 MPU Descriptor
+ */
+
 /*
  * Copyright (c) 2011 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/nios2/nios2-mpu-disable-protected.c b/cpukit/score/cpu/nios2/nios2-mpu-disable-protected.c
index 77a00fde61..f43ac38dd3 100644
--- a/cpukit/score/cpu/nios2/nios2-mpu-disable-protected.c
+++ b/cpukit/score/cpu/nios2/nios2-mpu-disable-protected.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS2 MPU Disable Protected
+ */
+
 /*
  * Copyright (c) 2011 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/nios2/nios2-thread-dispatch-disabled.c b/cpukit/score/cpu/nios2/nios2-thread-dispatch-disabled.c
index b939e02e8b..73b383f29a 100644
--- a/cpukit/score/cpu/nios2/nios2-thread-dispatch-disabled.c
+++ b/cpukit/score/cpu/nios2/nios2-thread-dispatch-disabled.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief NIOS II Specific Thread Dispatch Disabled Indicator.
+ */
+
 /*
  * Copyright (c) 2011 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/cpu/nios2/rtems/score/cpu.h b/cpukit/score/cpu/nios2/rtems/score/cpu.h
index 68ab01df34..7beb4ec06f 100644
--- a/cpukit/score/cpu/nios2/rtems/score/cpu.h
+++ b/cpukit/score/cpu/nios2/rtems/score/cpu.h
@@ -290,7 +290,7 @@ uint32_t _CPU_ISR_Get_level( void );
 
 /**
  * @brief Initializes the CPU context.
- * 
+ *
  * The following steps are performed:
  *  - setting a starting address
  *  - preparing the stack
@@ -318,14 +318,26 @@ void _CPU_Context_Initialize(
 
 void _CPU_Fatal_halt( uint32_t _error ) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
+/**
+ * @brief CPU Initialize
+ *
+ */
 void _CPU_Initialize( void );
 
+/**
+ * @brief CPU ISR Install Raw Handler
+ *
+ */
 void _CPU_ISR_install_raw_handler(
   uint32_t vector,
   proc_ptr new_handler,
   proc_ptr *old_handler
 );
 
+/**
+ * @brief CPU ISR Install Vector.
+ *
+ */
 void _CPU_ISR_install_vector(
   uint32_t vector,
   proc_ptr new_handler,
diff --git a/cpukit/score/cpu/nios2/rtems/score/nios2-utility.h b/cpukit/score/cpu/nios2/rtems/score/nios2-utility.h
index 022990d919..b99dd02cd2 100644
--- a/cpukit/score/cpu/nios2/rtems/score/nios2-utility.h
+++ b/cpukit/score/cpu/nios2/rtems/score/nios2-utility.h
@@ -307,6 +307,10 @@ static inline bool _Nios2_Has_internal_interrupt_controller( void )
   return _Nios2_ISR_Get_status_mask() == NIOS2_ISR_STATUS_MASK_IIC;
 }
 
+/*
+ *  @brief Nios2 ISR Set level
+ *
+ */
 uint32_t _Nios2_ISR_Set_level( uint32_t new_level, uint32_t status );
 
 typedef struct {
@@ -399,6 +403,10 @@ bool _Nios2_MPU_Setup_region_registers(
   uint32_t *mpuacc
 );
 
+/**
+ * @brief Nios2 MPU Get region descriptor.
+ *
+ */
 bool _Nios2_MPU_Get_region_descriptor(
   const Nios2_MPU_Configuration *config,
   int index,
@@ -488,6 +496,10 @@ static inline void _Nios2_MPU_Restore( uint32_t config )
   _Nios2_Set_ctlreg_config( config );
 }
 
+/*
+ *  @brief Nios2 MPU Disable Protected
+ *
+ */
 uint32_t _Nios2_MPU_Disable_protected( void );
 
 void _Nios2_MPU_Reset( const Nios2_MPU_Configuration *config );
diff --git a/cpukit/score/cpu/sh/context.c b/cpukit/score/cpu/sh/context.c
index 597c868d00..e470e7a4ef 100644
--- a/cpukit/score/cpu/sh/context.c
+++ b/cpukit/score/cpu/sh/context.c
@@ -1,3 +1,9 @@
+/**
+ * @file
+ *
+ * @brief SuperH CPU Context
+ */
+
 /*
  *  Authors: Ralf Corsepius (corsepiu@faw.uni-ulm.de) and
  *           Bernd Becker (becker@faw.uni-ulm.de)
diff --git a/cpukit/score/cpu/sh/cpu.c b/cpukit/score/cpu/sh/cpu.c
index d4f1644dd2..57d6ffc6db 100644
--- a/cpukit/score/cpu/sh/cpu.c
+++ b/cpukit/score/cpu/sh/cpu.c
@@ -1,7 +1,13 @@
-/*
- *  This file contains information pertaining to the Hitachi SH
- *  processor.
+/**
+ * @file
+ *
+ * @brief SuperH CPU Support
  *
+ * This file contains information pertaining to the Hitachi SH
+ * processor.
+ */
+
+/*
  *  Authors: Ralf Corsepius (corsepiu@faw.uni-ulm.de) and
  *           Bernd Becker (becker@faw.uni-ulm.de)
  *
diff --git a/cpukit/score/cpu/sh/rtems/score/cpu.h b/cpukit/score/cpu/sh/rtems/score/cpu.h
index 9a61b5e940..f5ad90c766 100644
--- a/cpukit/score/cpu/sh/rtems/score/cpu.h
+++ b/cpukit/score/cpu/sh/rtems/score/cpu.h
@@ -789,11 +789,12 @@ extern uint8_t   _bit_set_table[];
 /* functions */
 
 /*
+ *  @brief CPU Initialize
+ *
  *  _CPU_Initialize
  *
  *  This routine performs CPU dependent initialization.
  */
-
 void _CPU_Initialize(void);
 
 /*
@@ -866,21 +867,21 @@ void _CPU_Context_restore(
 ) RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
 /*
+ *  @brief This routine saves the floating point context passed to it.
+ *
  *  _CPU_Context_save_fp
  *
- *  This routine saves the floating point context passed to it.
  */
-
 void _CPU_Context_save_fp(
   Context_Control_fp **fp_context_ptr
 );
 
 /*
+ *  @brief This routine restores the floating point context passed to it.
+ *
  *  _CPU_Context_restore_fp
  *
- *  This routine restores the floating point context passed to it.
  */
-
 void _CPU_Context_restore_fp(
   Context_Control_fp **fp_context_ptr
 );
diff --git a/cpukit/score/cpu/v850/cpu.c b/cpukit/score/cpu/v850/cpu.c
index 6a7dd205af..50065b6623 100644
--- a/cpukit/score/cpu/v850/cpu.c
+++ b/cpukit/score/cpu/v850/cpu.c
@@ -1,7 +1,7 @@
 /**
- *  @file
+ * @file
  *
- *  v850 CPU Dependent Source
+ * @brief v850 CPU Initialize
  */
 
 /*
diff --git a/cpukit/score/cpu/v850/rtems/score/cpu.h b/cpukit/score/cpu/v850/rtems/score/cpu.h
index d77344bdca..b6fb59d7b6 100644
--- a/cpukit/score/cpu/v850/rtems/score/cpu.h
+++ b/cpukit/score/cpu/v850/rtems/score/cpu.h
@@ -1041,11 +1041,14 @@ void _CPU_Context_Initialize(
 /* functions */
 
 /**
+ *  @brief CPU Initialize
  *  This routine performs CPU dependent initialization.
  *
  *  Port Specific Information:
  *
  *  This is implemented in C.
+ *
+ *  v850 CPU Dependent Source
  */
 void _CPU_Initialize(void);