[PATCH 1/4] arm: Improve Doxygen file comments

Sebastian Huber sebastian.huber at embedded-brains.de
Wed May 24 13:01:32 UTC 2023 

---
 cpukit/score/cpu/arm/__aeabi_read_tp.c          |  8 ++++++++
 cpukit/score/cpu/arm/__tls_get_addr.c           |  8 ++++++++
 cpukit/score/cpu/arm/arm-exception-default.c    |  9 +++++++++
 .../score/cpu/arm/arm-exception-frame-print.c   |  9 +++++++++
 cpukit/score/cpu/arm/armv4-sync-synchronize.c   |  8 ++++++++
 cpukit/score/cpu/arm/armv7-thread-idle.c        |  7 +++++--
 .../score/cpu/arm/armv7m-context-initialize.c   |  7 +++++--
 cpukit/score/cpu/arm/armv7m-context-restore.c   |  7 +++++--
 cpukit/score/cpu/arm/armv7m-context-switch.c    |  5 ++++-
 cpukit/score/cpu/arm/armv7m-exception-default.c |  9 +++++++++
 .../cpu/arm/armv7m-exception-handler-get.c      |  7 +++++--
 .../cpu/arm/armv7m-exception-handler-set.c      |  7 +++++--
 .../cpu/arm/armv7m-exception-priority-get.c     |  8 ++++++--
 .../cpu/arm/armv7m-exception-priority-handler.c |  5 ++++-
 .../cpu/arm/armv7m-exception-priority-set.c     |  7 +++++--
 cpukit/score/cpu/arm/armv7m-initialize.c        |  4 +++-
 cpukit/score/cpu/arm/armv7m-isr-dispatch.c      |  5 ++++-
 cpukit/score/cpu/arm/armv7m-isr-enter-leave.c   |  7 +++++--
 cpukit/score/cpu/arm/armv7m-isr-level-get.c     |  6 ++++--
 cpukit/score/cpu/arm/armv7m-isr-level-set.c     |  6 ++++--
 .../score/cpu/arm/armv7m-isr-vector-install.c   |  7 +++++--
 .../cpu/arm/armv7m-multitasking-start-stop.c    |  5 ++++-
 cpukit/score/cpu/arm/cpu.c                      |  6 +++++-
 cpukit/score/cpu/arm/include/rtems/asm.h        |  5 ++++-
 .../score/cpu/arm/include/rtems/score/armv4.h   | 17 +++++++++++++++++
 .../score/cpu/arm/include/rtems/score/armv7m.h  |  5 ++++-
 cpukit/score/cpu/arm/include/rtems/score/cpu.h  |  5 ++++-
 .../score/cpu/arm/include/rtems/score/cpuimpl.h |  5 ++++-
 .../cpu/arm/include/rtems/score/paravirt.h      |  6 +++---
 29 files changed, 165 insertions(+), 35 deletions(-)

diff --git a/cpukit/score/cpu/arm/__aeabi_read_tp.c b/cpukit/score/cpu/arm/__aeabi_read_tp.c
index b9e9464f24..0f4eba8d9a 100644
--- a/cpukit/score/cpu/arm/__aeabi_read_tp.c
+++ b/cpukit/score/cpu/arm/__aeabi_read_tp.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of __aeabi_read_tp().
+ */
+
 /*
  * Copyright (c) 2014 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/__tls_get_addr.c b/cpukit/score/cpu/arm/__tls_get_addr.c
index d28b58c11f..7ef42fdcb4 100644
--- a/cpukit/score/cpu/arm/__tls_get_addr.c
+++ b/cpukit/score/cpu/arm/__tls_get_addr.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of __tls_get_addr().
+ */
+
 /*
  * Copyright (C) 2014, 2015 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/arm-exception-default.c b/cpukit/score/cpu/arm/arm-exception-default.c
index 8c991fb747..02df769287 100644
--- a/cpukit/score/cpu/arm/arm-exception-default.c
+++ b/cpukit/score/cpu/arm/arm-exception-default.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARM_Exception_default().
+ */
+
 /*
  * Copyright (c) 2013 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/arm-exception-frame-print.c b/cpukit/score/cpu/arm/arm-exception-frame-print.c
index 6b5ecf46bf..7bc6795ea5 100644
--- a/cpukit/score/cpu/arm/arm-exception-frame-print.c
+++ b/cpukit/score/cpu/arm/arm-exception-frame-print.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_Exception_frame_print().
+ */
+
 /*
  * Copyright (C) 2012, 2013 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/armv4-sync-synchronize.c b/cpukit/score/cpu/arm/armv4-sync-synchronize.c
index 6af6960a20..2f454306d8 100644
--- a/cpukit/score/cpu/arm/armv4-sync-synchronize.c
+++ b/cpukit/score/cpu/arm/armv4-sync-synchronize.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of __sync_synchronize().
+ */
+
 /*
  * Copyright (c) 2015 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/armv7-thread-idle.c b/cpukit/score/cpu/arm/armv7-thread-idle.c
index 1db6d535b8..720cb2be83 100644
--- a/cpukit/score/cpu/arm/armv7-thread-idle.c
+++ b/cpukit/score/cpu/arm/armv7-thread-idle.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU Thread Idle Body
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_Thread_Idle_body().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-context-initialize.c b/cpukit/score/cpu/arm/armv7m-context-initialize.c
index a078c8f757..d67bcf93b5 100644
--- a/cpukit/score/cpu/arm/armv7m-context-initialize.c
+++ b/cpukit/score/cpu/arm/armv7m-context-initialize.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU Initialize Context
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_Context_Initialize().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-context-restore.c b/cpukit/score/cpu/arm/armv7m-context-restore.c
index bf402953a3..b888abe29f 100644
--- a/cpukit/score/cpu/arm/armv7m-context-restore.c
+++ b/cpukit/score/cpu/arm/armv7m-context-restore.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU Restore Context
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_Context_restore().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-context-switch.c b/cpukit/score/cpu/arm/armv7m-context-switch.c
index 091611aebf..74d6b953ef 100644
--- a/cpukit/score/cpu/arm/armv7m-context-switch.c
+++ b/cpukit/score/cpu/arm/armv7m-context-switch.c
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARM7M CPU Context Switch
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_Context_switch().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-exception-default.c b/cpukit/score/cpu/arm/armv7m-exception-default.c
index 3e832e3a88..35dde50dc3 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-default.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-default.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Exception_default().
+ */
+
 /*
  * Copyright (c) 2013 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/score/cpu/arm/armv7m-exception-handler-get.c b/cpukit/score/cpu/arm/armv7m-exception-handler-get.c
index 63fcfffcfa..41effd1e18 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-handler-get.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-handler-get.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief ARMV7M Get Exception Handler
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Get_exception_handler().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-exception-handler-set.c b/cpukit/score/cpu/arm/armv7m-exception-handler-set.c
index a138cbeec1..94c9dc5360 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-handler-set.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-handler-set.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief ARMV7M Set Exception Handler
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Set_exception_handler().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-exception-priority-get.c b/cpukit/score/cpu/arm/armv7m-exception-priority-get.c
index c22e874404..bb0892a32f 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-priority-get.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-priority-get.c
@@ -1,10 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief ARMV7M Get Exception Priority
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Get_exception_priority().
  */
+
 /*
  * 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 f77aa73522..b94366e07c 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-priority-handler.c
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARMV7M Set Exception Priority and Handler
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Set_exception_priority_and_handler().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-exception-priority-set.c b/cpukit/score/cpu/arm/armv7m-exception-priority-set.c
index da0a635497..05136a47db 100644
--- a/cpukit/score/cpu/arm/armv7m-exception-priority-set.c
+++ b/cpukit/score/cpu/arm/armv7m-exception-priority-set.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief ARMV7M Set Exception Priority
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Set_exception_priority().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-initialize.c b/cpukit/score/cpu/arm/armv7m-initialize.c
index 09fd792eca..0f47b49af7 100644
--- a/cpukit/score/cpu/arm/armv7m-initialize.c
+++ b/cpukit/score/cpu/arm/armv7m-initialize.c
@@ -3,7 +3,9 @@
 /**
  * @file
  *
- * @brief ARM7M CPU Initialize
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of _CPU_Initialize().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-isr-dispatch.c b/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
index 5ab9d1fae2..ea168969ba 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-dispatch.c
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARMV7M ISR Dispatch
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Thread_dispatch().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-isr-enter-leave.c b/cpukit/score/cpu/arm/armv7m-isr-enter-leave.c
index e2f5b5b62f..1490f6e219 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-enter-leave.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-enter-leave.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief ARMV7M Interrupt Service Enter and Leave
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Interrupt_service_enter() and _ARMV7M_Interrupt_service_leave().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-isr-level-get.c b/cpukit/score/cpu/arm/armv7m-isr-level-get.c
index d597e3bf3d..cc2b674e13 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-level-get.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-level-get.c
@@ -1,9 +1,11 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU Get ISR Level
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of _CPU_ISR_Get_level().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-isr-level-set.c b/cpukit/score/cpu/arm/armv7m-isr-level-set.c
index 01835075fb..72c9684025 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-level-set.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-level-set.c
@@ -1,9 +1,11 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU Set ISR Level
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of _CPU_ISR_Set_level().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-isr-vector-install.c b/cpukit/score/cpu/arm/armv7m-isr-vector-install.c
index 1616577895..c1e9eb70cb 100644
--- a/cpukit/score/cpu/arm/armv7m-isr-vector-install.c
+++ b/cpukit/score/cpu/arm/armv7m-isr-vector-install.c
@@ -1,9 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @brief CPU ISR Vector Install
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _CPU_ISR_install_vector().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c b/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
index ffd21772a8..a9b59dec84 100644
--- a/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
+++ b/cpukit/score/cpu/arm/armv7m-multitasking-start-stop.c
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARMV7M Start Multitasking
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This source file contains the implementation of
+ *   _ARMV7M_Start_multitasking().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/cpu.c b/cpukit/score/cpu/arm/cpu.c
index f5bc7041cd..65f1ad2014 100644
--- a/cpukit/score/cpu/arm/cpu.c
+++ b/cpukit/score/cpu/arm/cpu.c
@@ -5,7 +5,11 @@
  *
  * @ingroup RTEMSScoreCPUARM
  *
- * @brief ARM architecture support implementation.
+ * @brief This source file contains static assertions to ensure the consistency
+ *   of interfaces used in C and assembler and it contains the ARM-specific
+ *   implementation of _CPU_Initialize(), _CPU_ISR_Get_level(),
+ *   _CPU_ISR_Set_level(), _CPU_ISR_install_vector(),
+ *   _CPU_Context_Initialize(), and _CPU_Fatal_halt().
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/include/rtems/asm.h b/cpukit/score/cpu/arm/include/rtems/asm.h
index 0bbe43c837..79892aae0c 100644
--- a/cpukit/score/cpu/arm/include/rtems/asm.h
+++ b/cpukit/score/cpu/arm/include/rtems/asm.h
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARM Assembler Support API
+ * @ingroup RTEMSScoreCPUARMASM
+ *
+ * @brief This header file provides interfaces to address problems caused by
+ *   incompatible flavor of assemblers and toolsets.
  *
  * This include file attempts to address the problems
  * caused by incompatible flavors of assemblers and
diff --git a/cpukit/score/cpu/arm/include/rtems/score/armv4.h b/cpukit/score/cpu/arm/include/rtems/score/armv4.h
index fbfbcf2495..1d3a6de5ff 100644
--- a/cpukit/score/cpu/arm/include/rtems/score/armv4.h
+++ b/cpukit/score/cpu/arm/include/rtems/score/armv4.h
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This header file provides interfaces of the ARMv4 architecture
+ *   support.
+ */
+
 /*
  * Copyright (c) 2013 embedded brains GmbH & Co. KG
  *
@@ -34,6 +43,12 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @addtogroup RTEMSScoreCPUARM
+ *
+ * @{
+ */
+
 #ifdef ARM_MULTILIB_ARCH_V4
 
 void bsp_interrupt_dispatch( void );
@@ -104,6 +119,8 @@ static inline void _ARMV4_Status_restore( uint32_t psr )
 
 #endif /* ARM_MULTILIB_ARCH_V4 */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/cpukit/score/cpu/arm/include/rtems/score/armv7m.h b/cpukit/score/cpu/arm/include/rtems/score/armv7m.h
index 2b1e785cf7..0f129f1d2e 100644
--- a/cpukit/score/cpu/arm/include/rtems/score/armv7m.h
+++ b/cpukit/score/cpu/arm/include/rtems/score/armv7m.h
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARMV7M Architecture Support
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This header file provides interfaces of the ARMv7-M architecture
+ *   support.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/include/rtems/score/cpu.h b/cpukit/score/cpu/arm/include/rtems/score/cpu.h
index 055130e856..3cd43970b1 100644
--- a/cpukit/score/cpu/arm/include/rtems/score/cpu.h
+++ b/cpukit/score/cpu/arm/include/rtems/score/cpu.h
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief ARM Architecture Support API
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This header file defines implementation interfaces pertaining to the
+ *   port of the executive to the ARM architecture.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/include/rtems/score/cpuimpl.h b/cpukit/score/cpu/arm/include/rtems/score/cpuimpl.h
index 18db3fda1b..f9b40889f5 100644
--- a/cpukit/score/cpu/arm/include/rtems/score/cpuimpl.h
+++ b/cpukit/score/cpu/arm/include/rtems/score/cpuimpl.h
@@ -3,7 +3,10 @@
 /**
  * @file
  *
- * @brief CPU Port Implementation API
+ * @ingroup RTEMSScoreCPUARM
+ *
+ * @brief This header file defines implementation interfaces pertaining to the
+ *   port of the executive to the ARM architecture.
  */
 
 /*
diff --git a/cpukit/score/cpu/arm/include/rtems/score/paravirt.h b/cpukit/score/cpu/arm/include/rtems/score/paravirt.h
index e3fb9009ad..4aa98499ad 100644
--- a/cpukit/score/cpu/arm/include/rtems/score/paravirt.h
+++ b/cpukit/score/cpu/arm/include/rtems/score/paravirt.h
@@ -3,10 +3,10 @@
 /**
  * @file
  *
- * @brief ARM Paravirtualization Definitions
+ * @ingroup RTEMSScoreCPUARMParavirt
  *
- * This include file contains definitions pertaining to paravirtualization
- * of the ARM port.
+ * @brief This header file provides definitions pertaining to
+ *   paravirtualization of the ARM port.
  */
 
 /*
-- 
2.35.3

More information about the devel mailing list