From 26eb5816df304c56e684dbb312412885a5f39d49 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Wed, 10 Apr 2024 14:47:51 +0200
Subject: dev/irq: Improve Doxgyen group assignments

Make the GIC interrupt controller support a subgroup of the generic interrupt
controller support.
---
 bsps/aarch64/include/dev/irq/arm-gic-arch.h    | 13 +++++++++++--
 bsps/arm/include/dev/irq/arm-gic-arch.h        | 13 +++++++++++--
 bsps/include/dev/irq/arm-gic-irq.h             | 15 ++++++++++++---
 bsps/include/dev/irq/arm-gic-regs.h            | 15 ++++++++++++---
 bsps/include/dev/irq/arm-gic-tm27.h            |  7 ++++---
 bsps/include/dev/irq/arm-gic.h                 | 18 ++++++++++++------
 bsps/include/dev/irq/arm-gicv3.h               | 13 +++++++++++--
 bsps/shared/dev/irq/arm-gicv2-get-attributes.c |  5 +++--
 bsps/shared/dev/irq/arm-gicv2-zynqmp.c         |  6 ++++--
 bsps/shared/dev/irq/arm-gicv2.c                |  5 +++--
 bsps/shared/dev/irq/arm-gicv3.c                | 13 +++++++++++--
 11 files changed, 94 insertions(+), 29 deletions(-)

diff --git a/bsps/aarch64/include/dev/irq/arm-gic-arch.h b/bsps/aarch64/include/dev/irq/arm-gic-arch.h
index 94b832c2c5..5ca2c7314e 100644
--- a/bsps/aarch64/include/dev/irq/arm-gic-arch.h
+++ b/bsps/aarch64/include/dev/irq/arm-gic-arch.h
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsAArch64Shared
+ * @ingroup DevIRQGIC
  *
- * @brief AArch64-specific ARM GICv3 handlers.
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) support specific to the AArch64 architecture.
  */
 
 /*
@@ -46,6 +47,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup DevIRQGIC
+ *
+ * @{
+ */
+
 static inline uint32_t arm_interrupt_enable_interrupts(void)
 {
   uint32_t status = _CPU_ISR_Get_level();
@@ -72,6 +79,8 @@ static inline void arm_interrupt_facility_set_exception_handler(void)
   );
 }
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/bsps/arm/include/dev/irq/arm-gic-arch.h b/bsps/arm/include/dev/irq/arm-gic-arch.h
index f2ea76f22f..f6c8b5d426 100644
--- a/bsps/arm/include/dev/irq/arm-gic-arch.h
+++ b/bsps/arm/include/dev/irq/arm-gic-arch.h
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsARMShared
+ * @ingroup DevIRQGIC
  *
- * @brief ARM-specific IRQ handlers.
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) support specific to the Arm architecture.
  */
 
 /*
@@ -44,6 +45,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup DevIRQGIC
+ *
+ * @{
+ */
+
 static inline uint32_t arm_interrupt_enable_interrupts(void)
 {
   return _ARMV4_Status_irq_enable();
@@ -62,6 +69,8 @@ static inline void arm_interrupt_facility_set_exception_handler(void)
    */
 }
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/bsps/include/dev/irq/arm-gic-irq.h b/bsps/include/dev/irq/arm-gic-irq.h
index 1fcf594360..c3615a12a0 100644
--- a/bsps/include/dev/irq/arm-gic-irq.h
+++ b/bsps/include/dev/irq/arm-gic-irq.h
@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @ingroup arm_gic
+ * @ingroup DevIRQGIC
  *
- *  @brief ARM GIC IRQ
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) support.
  */
 
 /*
@@ -43,6 +44,12 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @addtogroup DevIRQGIC
+ *
+ * @{
+ */
+
 #define ARM_GIC_IRQ_SGI_0 0
 #define ARM_GIC_IRQ_SGI_1 1
 #define ARM_GIC_IRQ_SGI_2 2
@@ -108,6 +115,8 @@ uint32_t arm_gic_irq_processor_count(void);
 void arm_gic_irq_initialize_secondary_cpu(void);
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/bsps/include/dev/irq/arm-gic-regs.h b/bsps/include/dev/irq/arm-gic-regs.h
index 097ff67c13..c03a7a7a07 100644
--- a/bsps/include/dev/irq/arm-gic-regs.h
+++ b/bsps/include/dev/irq/arm-gic-regs.h
@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @ingroup arm_gic
+ * @ingroup DevIRQGIC
  *
- *  @brief ARM GIC Register definitions
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) memory-mapped registers.
  */
 
 /*
@@ -38,6 +39,12 @@
 
 #include <bsp/utility.h>
 
+/**
+ * @addtogroup DevIRQGIC
+ *
+ * @{
+ */
+
 typedef struct {
   uint32_t iccicr;
 #define GIC_CPUIF_ICCICR_CBPR BSP_BIT32(4)
@@ -225,4 +232,6 @@ typedef struct {
   uint32_t icspigrpmodr[64];
 } gic_sgi_ppi;
 
+/** @} */
+
 #endif /* LIBBSP_ARM_SHARED_ARM_GIC_REGS_H */
diff --git a/bsps/include/dev/irq/arm-gic-tm27.h b/bsps/include/dev/irq/arm-gic-tm27.h
index f2a16afae3..70e76c7603 100644
--- a/bsps/include/dev/irq/arm-gic-tm27.h
+++ b/bsps/include/dev/irq/arm-gic-tm27.h
@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @ingroup arm_gic
+ * @ingroup DevIRQGIC
  *
- *  @brief ARM GIC TM27 Support
+ * @brief This header file provides the TM27 support for the ARM Generic
+ *   Interrupt Controller (GIC).
  */
 
 /*
diff --git a/bsps/include/dev/irq/arm-gic.h b/bsps/include/dev/irq/arm-gic.h
index 73c9a688d5..4e418de68f 100644
--- a/bsps/include/dev/irq/arm-gic.h
+++ b/bsps/include/dev/irq/arm-gic.h
@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
- *  @ingroup arm_gic
+ * @ingroup DevIRQGIC
  *
- *  @brief ARM GIC Support
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) support.
  */
 
 /*
@@ -45,11 +46,14 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- *  @defgroup arm_gic ARM GIC
+ * @defgroup DevIRQGIC ARM Generic Interrupt Controller (GIC) Support
  *
- *  @ingroup RTEMSBSPsARMShared
+ * @ingroup RTEMSImplClassicIntr
  *
- *  @brief ARM_GIC Support Package
+ * @brief This group contains the Interrupt Manager implementation parts
+ *   specific to the ARM Generic Interrupt Controller.
+ *
+ * @{
  */
 
 #define GIC_ID_TO_ONE_BIT_REG_INDEX(id) ((id) >> 5)
@@ -248,6 +252,8 @@ static inline void gic_id_set_handling_model(
   dist->icdicfr[i] = icdicfr;
 }
 
+/* @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/bsps/include/dev/irq/arm-gicv3.h b/bsps/include/dev/irq/arm-gicv3.h
index 09d1b50422..8829c32384 100644
--- a/bsps/include/dev/irq/arm-gicv3.h
+++ b/bsps/include/dev/irq/arm-gicv3.h
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup arm_gic
+ * @ingroup DevIRQGIC
  *
- * @brief This header file contains interfaces to access an Arm GICv3.
+ * @brief This header file provides interfaces of the ARM Generic Interrupt
+ *   Controller (GIC) support specific to the GICv3.
  */
 
 /*
@@ -44,6 +45,12 @@
 extern "C" {
 #endif
 
+/**
+ * @addtogroup DevIRQGIC
+ *
+ * @{
+ */
+
 #define PRIORITY_DEFAULT 127
 
 #define MPIDR_AFFINITY2(val) BSP_FLD64(val, 16, 23)
@@ -387,6 +394,8 @@ static inline void gicv3_get_attributes(
   }
 }
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/bsps/shared/dev/irq/arm-gicv2-get-attributes.c b/bsps/shared/dev/irq/arm-gicv2-get-attributes.c
index 3280671ab6..613174bb3a 100644
--- a/bsps/shared/dev/irq/arm-gicv2-get-attributes.c
+++ b/bsps/shared/dev/irq/arm-gicv2-get-attributes.c
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsShared
+ * @ingroup DevIRQGIC
  *
- * @brief This source file contains the interrupt get attribute implementation.
+ * @brief This source file contains the implementation of
+ *   bsp_interrupt_get_attributes() for the GICv2.
  */
 
 /*
diff --git a/bsps/shared/dev/irq/arm-gicv2-zynqmp.c b/bsps/shared/dev/irq/arm-gicv2-zynqmp.c
index ee4479155a..bb9bfafb48 100644
--- a/bsps/shared/dev/irq/arm-gicv2-zynqmp.c
+++ b/bsps/shared/dev/irq/arm-gicv2-zynqmp.c
@@ -3,9 +3,11 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsShared
+ * @ingroup DevIRQGIC
  *
- * @brief This source file contains the interrupt get attribute implementation.
+ * @brief This source file contains the implementation of
+ *   bsp_interrupt_get_attributes() for the GICv2 of Xilinx Zynq UltraScale+
+ *   MPSoC and RFSoC devices.
  */
 
 /*
diff --git a/bsps/shared/dev/irq/arm-gicv2.c b/bsps/shared/dev/irq/arm-gicv2.c
index e3e31e5ab9..263278148b 100644
--- a/bsps/shared/dev/irq/arm-gicv2.c
+++ b/bsps/shared/dev/irq/arm-gicv2.c
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsARMShared
+ * @ingroup DevIRQGIC
  *
- * @brief This source file contains the implementation of ARM GICv2 support.
+ * @brief This source file contains the implementation of the generic GICv2
+ *   support.
  */
 
 /*
diff --git a/bsps/shared/dev/irq/arm-gicv3.c b/bsps/shared/dev/irq/arm-gicv3.c
index 8aad0f6482..fd7abd6a13 100644
--- a/bsps/shared/dev/irq/arm-gicv3.c
+++ b/bsps/shared/dev/irq/arm-gicv3.c
@@ -1,6 +1,15 @@
-/*
- * SPDX-License-Identifier: BSD-2-Clause
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup DevIRQGIC
  *
+ * @brief This source file contains the implementation of the generic GICv3
+ *   support.
+ */
+
+/*
  * Copyright (C) 2019 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
-- 
cgit v1.2.3