[docs][libcpu][arm][cortex-a] add comment for gic.c

[laidene]

拉取/合并请求描述：(PR description)

[

为什么提交这份PR (why to submit this PR)

添加gic.c的注释，我认为可以辅助理解代码。

你的解决方案是什么 (what is your solution)

1 在对GIC寄存器宏定义处添加文档寄存器名称。
2 补全函数注释。
3 删除部分注释。

请提供验证的bsp和config (provide the config and bsp)

• BSP:none
• .config:none
• action:none

]

当前拉取/合并请求的状态 Intent for your PR

必须选择一项 Choose one (Mandatory):

• 本拉取/合并请求是一个草稿版本 This PR is for a code-review and is intended to get feedback
• 本拉取/合并请求是一个成熟版本 This PR is mature, and ready to be integrated into the repo

代码质量 Code Quality：

我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:

• 已经仔细查看过代码改动的对比 Already check the difference between PR and old code
• 代码风格正确，包括缩进空格，命名及其他风格 Style guide is adhered to, including spacing, naming and other styles
• 没有垃圾代码，代码尽量精简，不包含#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up
• 所有变更均有原因及合理的，并且不会影响到其他软件组件代码或BSP All modifications are justified and not affect other components or BSP
• 对难懂代码均提供对应的注释 I've commented appropriately where code is tricky
• 代码是高质量的 Code in this PR is of high quality
• 已经使用formatting 等源码格式化工具确保格式符合RT-Thread代码规范 This PR complies with RT-Thread code specification
• 如果是新增bsp, 已经添加ci检查到.github/ALL_BSP_COMPILE.json 详细请参考链接BSP自查

改动说明

1 在对GIC寄存器读写的宏定义处添加寄存器名称

参照 ARM ® Generic Interrupt Controller Architecture Specification(Architecture version 2.0)，给出寄存器在文档中的关键字，便于查看文档。

#define GIC_DIST_ACTIVE_CLEAR(hw_base, n)   __REG32((hw_base) + 0x380U + ((n)/32U) * 4U)    /* GICD_ICACTIVERn  */
#define GIC_DIST_PRI(hw_base, n)            __REG32((hw_base) + 0x400U +  ((n)/4U) * 4U)    /* GICD_IPRIORITYRn */
#define GIC_DIST_TARGET(hw_base, n)         __REG32((hw_base) + 0x800U +  ((n)/4U) * 4U)    /* GICD_ITARGETSRn  */
#define GIC_DIST_CONFIG(hw_base, n)         __REG32((hw_base) + 0xc00U + ((n)/16U) * 4U)    /* GICD_ICFGRn      */
#define GIC_DIST_SOFTINT(hw_base)           __REG32((hw_base) + 0xf00U)                     /* GICD_SGIR        */
#define GIC_DIST_CPENDSGI(hw_base, n)       __REG32((hw_base) + 0xf10U + ((n)/4U) * 4U)     /* GICD_CPENDSGIRn  */
#define GIC_DIST_SPENDSGI(hw_base, n)       __REG32((hw_base) + 0xf20U + ((n)/4U) * 4U)     /* GICD_SPENDSGIRn  */
#define GIC_DIST_ICPIDR2(hw_base)           __REG32((hw_base) + 0xfe8U)                     /* ICPIDR2          */

2 补全函数注释

/**
 * @brief Get the active interrupt number
 *
 * @note Read the GICC_IAR register and add the interrupt number offset to get
 *       the actual interrupt number.
 *       This read acts as an acknowledge for the interrupt, changing the interrupt
 *       state from pending to active.
 *
 *       GICC_IAR register bit fields:
 *       - GICC_IAR[31:13]: Reserved, read as 0
 *       - GICC_IAR[12:10]: CPUID
 *                          For SGIs: This value is the CPUID that requested the interrupt.
 *                          For other interrupts: This value reads as 0 (RAZ).
 *       - GICC_IAR[9:0]:  Interrupt ID
 *
 * @param index GIC controller index
 *
 * @return The actual interrupt number (with offset added).
 *         Note: For SGIs, the return value may include CPUID information in the upper bits.
 */
int arm_gic_get_active_irq(rt_uint32_t index)
{
    int irq;

    RT_ASSERT(index < ARM_GIC_MAX_NR);

    irq = GIC_CPU_INTACK(_gic_table[index].cpu_hw_base);
    irq += _gic_table[index].offset;
    return irq;
}

/**
 * @brief Initialize the GIC CPU Interface (GICC)
 *
 * @note: The exact bit definitions and behavior may vary depending on
 *        the GIC implementation (GICv1/GICv2) and security context..
 *
 * @param index    GIC controller index
 * @param cpu_base Base address of the GIC CPU Interface (GICC)
 *
 * @return 0
 */
int arm_gic_cpu_init(rt_uint32_t index, rt_uint32_t cpu_base)
{
    RT_ASSERT(index < ARM_GIC_MAX_NR);

    if (!_gic_table[index].cpu_hw_base)
    {
        _gic_table[index].cpu_hw_base = cpu_base;
    }
    cpu_base = _gic_table[index].cpu_hw_base;

    GIC_CPU_PRIMASK(cpu_base) = 0xf0U;
    GIC_CPU_BINPOINT(cpu_base) = 0x7U;
    /* Enable CPU interrupt */
    GIC_CPU_CTRL(cpu_base) = 0x01U;

    return 0;
}

3 删除部分注释

我认为 ARM_GIC_MAX_NR 不是核心数，多核smp也可以只有1个GIC控制器。
我认为注释不准确所以删除。

/* 'ARM_GIC_MAX_NR' is the number of cores */   /* 删除此处注释 */
static struct arm_gic _gic_table[ARM_GIC_MAX_NR];

测试

纯注释改动

[github-actions]

👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread!

为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。
To ensure your code complies with RT-Thread's coding style, please run the code formatting workflow by following the steps below (If the formatting of CI fails to run).

---

🛠 操作步骤 | Steps

1. 前往 Actions 页面 | Go to the Actions page
   点击进入工作流 → | Click to open workflow →

2. 点击 Run workflow | Click Run workflow

• 设置需排除的文件/目录（目录请以"/"结尾）
  Set files/directories to exclude (directories should end with "/")
• 将目标分支设置为 \ Set the target branch to：docs/libcpu/arm/cortex-a
• 设置PR number为 \ Set the PR number to：11128

3. 等待工作流完成 | Wait for the workflow to complete
   格式化后的代码将自动推送至你的分支。
   The formatted code will be automatically pushed to your branch.

完成后，提交将自动更新至 docs/libcpu/arm/cortex-a 分支，关联的 Pull Request 也会同步更新。
Once completed, commits will be pushed to the docs/libcpu/arm/cortex-a branch automatically, and the related Pull Request will be updated.

如有问题欢迎联系我们，再次感谢您的贡献！💐
If you have any questions, feel free to reach out. Thanks again for your contribution!

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

This PR adds comprehensive English documentation comments to the GIC (Generic Interrupt Controller) driver for ARM Cortex-A processors. The changes improve code readability by documenting register macros with official ARM specification names and adding detailed function documentation with parameter descriptions, return values, and usage notes.

Key Changes:

• Added ARM GIC register names as inline comments for all macro definitions (GICC_* and GICD_*)
• Added complete function documentation blocks for all 25+ public API functions
• Removed an inaccurate comment stating ARM_GIC_MAX_NR represents the number of CPU cores

[Copilot]

Missing space between "number" and "(with". Should be "number (with offset)" for consistency.

"number" 和 "(with" 之间缺少空格。应为 "number (with offset)" 以保持一致性。

[Copilot]

Missing space between "number" and "(with". Should be "number (with offset)" for consistency.

"number" 和 "(with" 之间缺少空格。应为 "number (with offset)" 以保持一致性。

[Copilot]

Missing space between "number" and "(with". Should be "number (with offset)" for consistency.

"number" 和 "(with" 之间缺少空格。应为 "number (with offset)" 以保持一致性。

[Copilot]

Missing space between "number" and "(with". Should be "number (with offset)" for consistency.

"number" 和 "(with" 之间缺少空格。应为 "number (with offset)" 以保持一致性。

[Copilot]

Missing space between "number" and "(with". Should be "number (with offset)" for consistency.

"number" 和 "(with" 之间缺少空格。应为 "number (with offset)" 以保持一致性。

[Rbb666]

@laidene 还请压缩成一个commit提交谢谢

[laidene]

@laidene 还请压缩成一个commit提交谢谢

已压缩为一个commit