add/adapt documentation

4 files changed, 137 insertions, 63 deletions

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