add/adapt documentation

13 files changed, 190 insertions, 69 deletions

diff --git a/cpukit/score/cpu/arm/ChangeLog b/cpukit/score/cpu/arm/ChangeLog
index 609e088ff7..81e582ba19 100644
--- a/cpukit/score/cpu/arm/ChangeLog
+++ b/cpukit/score/cpu/arm/ChangeLog
@@ -1,3 +1,10 @@
+2010-04-08	Sebastian Huber <sebastian.huber@embedded-brains.de>
+
+	* arm_exc_abort.S, arm_exc_handler_high.c, arm_exc_handler_low.S,
+	arm_exc_interrupt.S, cpu.c, cpu_asm.S, rtems/asm.h, rtems/score/arm.h,
+	rtems/score/cpu.h, rtems/score/cpu_asm.h, rtems/score/types.h:
+	Documentation.
+
 2010-04-07	Joel Sherrill <joel.sherrill@oarcorp.com>
 
 	* arm_exc_abort.S: Fix warnings about TRUE/FALSE not defined.
diff --git a/cpukit/score/cpu/arm/arm_exc_abort.S b/cpukit/score/cpu/arm/arm_exc_abort.S
index 7f2be2a59c..704d713f2c 100644
--- a/cpukit/score/cpu/arm/arm_exc_abort.S
+++ b/cpukit/score/cpu/arm/arm_exc_abort.S
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup arm
+ * @ingroup ScoreCPU
  *
  * @brief ARM data and prefetch abort exception prologue and epilogue.
  */
diff --git a/cpukit/score/cpu/arm/arm_exc_handler_high.c b/cpukit/score/cpu/arm/arm_exc_handler_high.c
index 6b8cf9265c..176c1b4561 100644
--- a/cpukit/score/cpu/arm/arm_exc_handler_high.c
+++ b/cpukit/score/cpu/arm/arm_exc_handler_high.c
@@ -1,7 +1,9 @@
 /**
  * @file
  *
- * ARM exception support code.
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM exception support implementation.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/arm_exc_handler_low.S b/cpukit/score/cpu/arm/arm_exc_handler_low.S
index 22b74f2b6a..c43d430e2f 100644
--- a/cpukit/score/cpu/arm/arm_exc_handler_low.S
+++ b/cpukit/score/cpu/arm/arm_exc_handler_low.S
@@ -1,7 +1,9 @@
 /**
  * @file
  *
- * ARM exception support code.
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM exception support implementation.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/arm_exc_interrupt.S b/cpukit/score/cpu/arm/arm_exc_interrupt.S
index 3c86ba46c9..18b129c4ad 100644
--- a/cpukit/score/cpu/arm/arm_exc_interrupt.S
+++ b/cpukit/score/cpu/arm/arm_exc_interrupt.S
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup arm
+ * @ingroup ScoreCPU
  *
  * @brief ARM interrupt exception prologue and epilogue.
  */
diff --git a/cpukit/score/cpu/arm/cpu.c b/cpukit/score/cpu/arm/cpu.c
index 3ad6207b2f..551c80cde3 100644
--- a/cpukit/score/cpu/arm/cpu.c
+++ b/cpukit/score/cpu/arm/cpu.c
@@ -1,7 +1,9 @@
 /**
  * @file
  *
- * ARM support code.
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM architecture support implementation.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/cpu_asm.S b/cpukit/score/cpu/arm/cpu_asm.S
index 7630ee67ce..9eebabae38 100644
--- a/cpukit/score/cpu/arm/cpu_asm.S
+++ b/cpukit/score/cpu/arm/cpu_asm.S
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM architecture support implementation.
+ */
+
 /*
  *  $Id$
  *
diff --git a/cpukit/score/cpu/arm/rtems/asm.h b/cpukit/score/cpu/arm/rtems/asm.h
index f8b027cf1b..9d56c514a6 100644
--- a/cpukit/score/cpu/arm/rtems/asm.h
+++ b/cpukit/score/cpu/arm/rtems/asm.h
@@ -1,6 +1,12 @@
 /**
- * @file rtems/asm.h
+ * @file
  *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM assembler support API.
+ */
+
+/*
  *  This include file attempts to address the problems
  *  caused by incompatible flavors of assemblers and
  *  toolsets.  It primarily addresses variations in the
@@ -42,6 +48,16 @@
 #include <rtems/score/cpuopts.h>
 #include <rtems/score/arm.h>
 
+/**
+ * @defgroup ScoreCPUARMASM ARM Assembler Support
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM assembler support.
+ *
+ * @{
+ */
+
 /*
  *  Recent versions of GNU cpp define variables which indicate the
  *  need for underscores and percents.  If not using GNU cpp or
@@ -157,4 +173,6 @@
 #endif /* __thumb__ */
 .endm
 
+/** @} */
+
 #endif /* _RTEMS_ASM_H */
diff --git a/cpukit/score/cpu/arm/rtems/score/arm.h b/cpukit/score/cpu/arm/rtems/score/arm.h
index 119f235015..42ad413512 100644
--- a/cpukit/score/cpu/arm/rtems/score/arm.h
+++ b/cpukit/score/cpu/arm/rtems/score/arm.h
@@ -1,5 +1,9 @@
 /**
- * @file rtems/score/arm.h
+ * @file
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM assembler support API.
  */
 
 /*
@@ -24,6 +28,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup ScoreCPU
+ *
+ * @{
+ */
+
 /*
  *  This file contains the information required to build
  *  RTEMS for a particular member of the "arm"
@@ -79,6 +89,8 @@ extern "C" {
 
 #define CPU_NAME "ARM"
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/score/cpu/arm/rtems/score/cpu.h b/cpukit/score/cpu/arm/rtems/score/cpu.h
index de452e8cb4..7b2b5d7d39 100644
--- a/cpukit/score/cpu/arm/rtems/score/cpu.h
+++ b/cpukit/score/cpu/arm/rtems/score/cpu.h
@@ -1,5 +1,9 @@
 /**
- * @file rtems/score/cpu.h
+ * @file
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM architecture support API.
  */
 
 /*
@@ -45,6 +49,16 @@
   #define FALSE 0
 #endif
 
+/**
+ * @defgroup ScoreCPUARM ARM Specific Support
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM specific support.
+ *
+ * @{
+ */
+
 #ifdef __thumb__
   #define ARM_SWITCH_REGISTERS uint32_t arm_switch_reg
   #define ARM_SWITCH_TO_ARM ".align 2\nbx pc\n.arm\n"
@@ -59,6 +73,12 @@
   #define ARM_SWITCH_ADDITIONAL_OUTPUT
 #endif
 
+/**
+ * @name Program Status Register
+ *
+ * @{
+ */
+
 #define ARM_PSR_N (1 << 31)
 #define ARM_PSR_Z (1 << 30)
 #define ARM_PSR_C (1 << 29)
@@ -82,6 +102,16 @@
 #define ARM_PSR_M_UND 0x1b
 #define ARM_PSR_M_SYS 0x1f
 
+/** @} */
+
+/** @} */
+
+/**
+ * @addtogroup ScoreCPU
+ *
+ * @{
+ */
+
 /* If someone uses THUMB we assume she wants minimal code size */
 #ifdef __thumb__
   #define CPU_INLINE_ENABLE_DISPATCH FALSE
@@ -183,23 +213,19 @@
 
 #define CPU_ENABLE_C_ISR_DISPATCH_IMPLEMENTATION TRUE
 
+/** @} */
+
 #ifndef ASM
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-typedef enum {
-  ARM_EXCEPTION_RESET = 0,
-  ARM_EXCEPTION_UNDEF = 1,
-  ARM_EXCEPTION_SWI = 2,
-  ARM_EXCEPTION_PREF_ABORT = 3,
-  ARM_EXCEPTION_DATA_ABORT = 4,
-  ARM_EXCEPTION_RESERVED = 5,
-  ARM_EXCEPTION_IRQ = 6,
-  ARM_EXCEPTION_FIQ = 7,
-  MAX_EXCEPTIONS = 8
-} Arm_symbolic_exception_name;
+/**
+ * @addtogroup ScoreCPU
+ *
+ * @{
+ */
 
 typedef struct {
   uint32_t register_cpsr;
@@ -216,24 +242,14 @@ typedef struct {
   uint32_t register_pc;
 } Context_Control;
 
-/* XXX This is out of date */
-typedef struct {
-  uint32_t register_r0;
-  uint32_t register_r1;
-  uint32_t register_r2;
-  uint32_t register_r3;
-  uint32_t register_ip;
-  uint32_t register_lr;
-} CPU_Exception_frame;
-
-typedef CPU_Exception_frame CPU_Interrupt_frame;
-
 typedef struct {
   /* Not supported */
 } Context_Control_fp;
 
 SCORE_EXTERN Context_Control_fp _CPU_Null_fp_context;
 
+extern uint32_t arm_cpu_mode;
+
 static inline uint32_t arm_interrupt_disable( void )
 {
   uint32_t arm_switch_reg;
@@ -279,40 +295,6 @@ static inline void arm_interrupt_flash( uint32_t level )
   );
 }
 
-static inline uint32_t arm_status_irq_enable( void )
-{
-  uint32_t arm_switch_reg;
-  uint32_t psr;
-
-  RTEMS_COMPILER_MEMORY_BARRIER();
-
-  asm volatile (
-    ARM_SWITCH_TO_ARM
-    "mrs %[psr], cpsr\n"
-    "bic %[arm_switch_reg], %[psr], #0x80\n"
-    "msr cpsr, %[arm_switch_reg]\n"
-    ARM_SWITCH_BACK
-    : [arm_switch_reg] "=&r" (arm_switch_reg), [psr] "=&r" (psr)
-  );
-
-  return psr;
-}
-
-static inline void arm_status_restore( uint32_t psr )
-{
-  ARM_SWITCH_REGISTERS;
-
-  asm volatile (
-    ARM_SWITCH_TO_ARM
-    "msr cpsr, %[psr]\n"
-    ARM_SWITCH_BACK
-    : ARM_SWITCH_OUTPUT
-    : [psr] "r" (psr)
-  );
-
-  RTEMS_COMPILER_MEMORY_BARRIER();
-}
-
 #define _CPU_ISR_Disable( _isr_cookie ) \
   do { \
     _isr_cookie = arm_interrupt_disable(); \
@@ -413,9 +395,13 @@ static inline uint16_t CPU_swap_u16( uint16_t value )
   return (uint16_t) (((value & 0xffU) << 8) | ((value >> 8) & 0xffU));
 }
 
-/* XXX */
+/** @} */
 
-extern uint32_t arm_cpu_mode;
+/**
+ * @addtogroup ScoreCPUARM
+ *
+ * @{
+ */
 
 typedef struct {
   uint32_t r0;
@@ -439,6 +425,52 @@ typedef struct {
 
 typedef void arm_exc_abort_handler( arm_cpu_context *context );
 
+typedef enum {
+  ARM_EXCEPTION_RESET = 0,
+  ARM_EXCEPTION_UNDEF = 1,
+  ARM_EXCEPTION_SWI = 2,
+  ARM_EXCEPTION_PREF_ABORT = 3,
+  ARM_EXCEPTION_DATA_ABORT = 4,
+  ARM_EXCEPTION_RESERVED = 5,
+  ARM_EXCEPTION_IRQ = 6,
+  ARM_EXCEPTION_FIQ = 7,
+  MAX_EXCEPTIONS = 8
+} Arm_symbolic_exception_name;
+
+static inline uint32_t arm_status_irq_enable( void )
+{
+  uint32_t arm_switch_reg;
+  uint32_t psr;
+
+  RTEMS_COMPILER_MEMORY_BARRIER();
+
+  asm volatile (
+    ARM_SWITCH_TO_ARM
+    "mrs %[psr], cpsr\n"
+    "bic %[arm_switch_reg], %[psr], #0x80\n"
+    "msr cpsr, %[arm_switch_reg]\n"
+    ARM_SWITCH_BACK
+    : [arm_switch_reg] "=&r" (arm_switch_reg), [psr] "=&r" (psr)
+  );
+
+  return psr;
+}
+
+static inline void arm_status_restore( uint32_t psr )
+{
+  ARM_SWITCH_REGISTERS;
+
+  asm volatile (
+    ARM_SWITCH_TO_ARM
+    "msr cpsr, %[psr]\n"
+    ARM_SWITCH_BACK
+    : ARM_SWITCH_OUTPUT
+    : [psr] "r" (psr)
+  );
+
+  RTEMS_COMPILER_MEMORY_BARRIER();
+}
+
 void arm_exc_data_abort_set_handler( arm_exc_abort_handler handler );
 
 void arm_exc_data_abort( void );
@@ -453,6 +485,20 @@ void arm_exc_interrupt( void );
 
 void arm_exc_undefined( void );
 
+/** @} */
+
+/* XXX This is out of date */
+typedef struct {
+  uint32_t register_r0;
+  uint32_t register_r1;
+  uint32_t register_r2;
+  uint32_t register_r3;
+  uint32_t register_ip;
+  uint32_t register_lr;
+} CPU_Exception_frame;
+
+typedef CPU_Exception_frame CPU_Interrupt_frame;
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/score/cpu/arm/rtems/score/cpu_asm.h b/cpukit/score/cpu/arm/rtems/score/cpu_asm.h
index 306a4c1004..ac93112c30 100644
--- a/cpukit/score/cpu/arm/rtems/score/cpu_asm.h
+++ b/cpukit/score/cpu/arm/rtems/score/cpu_asm.h
@@ -1,5 +1,9 @@
 /**
- * @file rtems/score/cpu_asm.h
+ * @file
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM assembler support API.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/rtems/score/types.h b/cpukit/score/cpu/arm/rtems/score/types.h
index 8c24072043..16b988a107 100644
--- a/cpukit/score/cpu/arm/rtems/score/types.h
+++ b/cpukit/score/cpu/arm/rtems/score/types.h
@@ -1,5 +1,9 @@
 /**
- * @file rtems/score/types.h
+ * @file
+ *
+ * @ingroup ScoreCPU
+ *
+ * @brief ARM architecture types API.
  */
 
 /*
@@ -29,6 +33,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup ScoreCPU
+ *
+ * @{
+ */
+
 /*
  *  This section defines the basic types for this processor.
  */
@@ -41,6 +51,8 @@ typedef float           single_precision;   /* single precision float */
 typedef double          double_precision;   /* double precision float */
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index c271caf846..62b6d8d901 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -40,6 +40,14 @@ extern "C" {
  */
 
 /**
+ * @defgroup ScoreCPU CPU Architecture Support
+ *
+ * @ingroup Score
+ *
+ * @brief Provides CPU architecture dependent services.
+ */
+
+/**
  *  The following type defines the control block used to manage
  *  object names.
  */