docs: add NuttX up_debugpoint_add architecture analysis

Analyze debugpoint API support across 7 NuttX architectures
(ARMv7-M, ARMv8-M, ARMv7-A, ARM64, RISC-V, Xtensa, x86_64).

Current fpb_debugmon_nuttx.c is ARM Cortex-M only due to
DebugMonitor IRQ attach and 0x20000000 address space hardcoding.
The up_debugpoint_add callback mechanism itself is cross-arch.

Includes short/mid/long-term adaptation suggestions for
RISC-V and other platforms.

Author: FASTSHIFT

Tools/WebServer/docs/nuttx-debugpoint-arch-analysis.md

@@ -0,0 +1,120 @@
+# NuttX up_debugpoint_add 架构适配性分析
+
+> 日期: 2026-04-01
+> 范围: `fpb_debugmon_nuttx.c` 对 NuttX debugpoint API 的依赖分析
+
+## 1. NuttX debugpoint API 概述
+
+NuttX 在 `include/nuttx/arch.h` 中定义了统一的调试点接口，受 `CONFIG_ARCH_HAVE_DEBUG` 宏控制：
+
+```c
+int up_debugpoint_add(int type, void *addr, size_t size,
+                      debug_callback_t callback, void *arg);
+int up_debugpoint_remove(int type, void *addr, size_t size);
+```
+
+支持的调试点类型：
+
+| 类型 | 值 | 说明 |
+|------|:--:|------|
+| `DEBUGPOINT_WATCHPOINT_RO` | 0x01 | 只读监视点 |
+| `DEBUGPOINT_WATCHPOINT_WO` | 0x02 | 只写监视点 |
+| `DEBUGPOINT_WATCHPOINT_RW` | 0x03 | 读写监视点 |
+| `DEBUGPOINT_BREAKPOINT` | 0x04 | 断点 |
+| `DEBUGPOINT_STEPPOINT` | 0x05 | 单步 |
+
+## 2. 各架构实现情况
+
+通过搜索 NuttX 源码中 `up_debugpoint_add` 的实现文件：
+
+| 架构 | 实现文件 | 硬件机制 | BREAKPOINT | WATCHPOINT | STEPPOINT |
+|------|---------|---------|:----------:|:----------:|:---------:|
+| ARMv7-M | `arm_dbgmonitor.c` | FPB + DWT | ✅ | ✅ | ✅ |
+| ARMv8-M | `arm_dbgmonitor.c` | FPB + DWT | ✅ | ✅ | ✅ |
+| ARMv7-A | `arm_hwdebug.c` | HW Breakpoint | ✅ | ✅ | ❌ |
+| ARM64 | `arm64_hwdebug.c` | HW Breakpoint | ✅ | ✅ | ❌ |
+| RISC-V | `riscv_debug.c` | Trigger Module | ✅ | ✅ | ✅ |
+| Xtensa | `xtensa_debug.c` | IBREAKA/DBREAK | ✅ | ✅ | ❌ |
+| x86_64 | `x86_64_hwdebug.c` | DR0-DR3 | ✅ | ✅ | ❌ |
+
+未实现的架构：ARMv6-M (Cortex-M0/M0+)、MIPS、Simulator 等。
+
+## 3. fpb_debugmon_nuttx.c 当前实现分析
+
+### 3.1 依赖的 API
+
+| API | 用途 | 必需 |
+|-----|------|:----:|
+| `up_debugpoint_add(DEBUGPOINT_BREAKPOINT, ...)` | 设置断点触发回调 | ✅ |
+| `up_debugpoint_remove(DEBUGPOINT_BREAKPOINT, ...)` | 移除断点 | ✅ |
+| `running_regs()` | 获取当前寄存器上下文 | ✅ |
+| `REG_PC` | 修改 PC 寄存器实现跳转 | ✅ |
+| `irq_attach(NVIC_IRQ_DBGMONITOR, ...)` | 挂载 DebugMonitor 中断 | ⚠️ ARM 专用 |
+| `arm_enable_dbgmonitor()` | 启用 DebugMonitor | ⚠️ ARM 专用 |
+
+### 3.2 架构适配性问题
+
+| 问题 | 严重度 | 说明 |
+|------|:------:|------|
+| `irq_attach(NVIC_IRQ_DBGMONITOR, ...)` 是 ARM 专用 | **高** | RISC-V/Xtensa/x86 没有 NVIC 和 DebugMonitor 中断 |
+| `arm_enable_dbgmonitor()` 是 ARM 专用 | **高** | 其他架构不需要此初始化 |
+| `arm_dbgmonitor` handler 是 ARM 专用 | **高** | 其他架构有自己的异常分发机制 |
+| `running_regs()` + `REG_PC` 是通用的 | 低 | NuttX 各架构都有此宏，但寄存器索引不同 |
+| 地址空间判断 `< 0x20000000` 是 ARM 专用 | **中** | RISC-V 的内存映射完全不同 |
+
+### 3.3 结论
+
+当前 `fpb_debugmon_nuttx.c` **仅适配 ARM Cortex-M（ARMv7-M / ARMv8-M）**。
+
+核心原因：
+1. 初始化流程绑定了 ARM 的 DebugMonitor 异常机制（NVIC IRQ 挂载 + `arm_enable_dbgmonitor`）
+2. 地址空间判断硬编码了 ARM 的内存映射（Code region < 0x20000000）
+
+但 `up_debugpoint_add` 回调机制本身是跨架构的——RISC-V、Xtensa、x86_64 都实现了。
+
+## 4. 跨架构适配建议
+
+### 4.1 短期方案：条件编译
+
+将 ARM 专用的初始化逻辑用 `#ifdef CONFIG_ARCH_ARM` 包裹，其他架构跳过 IRQ 挂载步骤（因为 NuttX 的 debugpoint 框架已经在各架构内部处理了异常分发）：
+
+```c
+int fpb_debugmon_init(void) {
+#if defined(CONFIG_ARCH_ARM)
+    /* ARM: 需要手动挂载 DebugMonitor handler */
+    irq_attach(NVIC_IRQ_DBGMONITOR, arm_dbgmonitor, NULL);
+    up_enable_irq(NVIC_IRQ_DBGMONITOR);
+    arm_enable_dbgmonitor();
+#endif
+    /* up_debugpoint_add 回调机制是跨架构的，无需额外初始化 */
+    g_debugmon_state.initialized = true;
+    return 0;
+}
+```
+
+### 4.2 中期方案：移除地址空间硬编码
+
+当前代码根据 `< 0x20000000` 判断是否使用 FPB breakpoint。对于非 ARM 架构，应统一使用 `DEBUGPOINT_BREAKPOINT`，让 NuttX 的架构层自行选择硬件机制：
+
+```c
+/* 统一使用 BREAKPOINT，NuttX 架构层会选择合适的硬件机制 */
+int type = DEBUGPOINT_BREAKPOINT;
+size_t size = 0;
+```
+
+### 4.3 长期方案：重命名模块
+
+`fpb_debugmon` 这个名字暗示了 ARM FPB + DebugMonitor，但实际上通过 NuttX debugpoint API 已经抽象了底层硬件。建议重命名为 `fl_debugpoint` 或类似名称，反映其跨架构本质。
+
+## 5. 各架构可行性总结
+
+| 架构 | 可行性 | 需要的改动 |
+|------|:------:|-----------|
+| ARMv7-M (Cortex-M3/M4/M7) | ✅ 已支持 | 无 |
+| ARMv8-M (Cortex-M23/M33/M55) | ✅ 已支持 | 无 |
+| RISC-V | ✅ 可行 | 移除 ARM 初始化 + 地址判断 |
+| Xtensa (ESP32) | ✅ 可行 | 同上 |
+| ARMv7-A (Cortex-A7/A9) | ⚠️ 部分可行 | 需验证 running_regs() 行为 |
+| ARM64 (Cortex-A53/A55) | ⚠️ 部分可行 | 同上 |
+| x86_64 | ⚠️ 部分可行 | 需验证 DR 寄存器回调机制 |
+| ARMv6-M (Cortex-M0/M0+) | ❌ 不可行 | 无 FPB/DWT 硬件，NuttX 未实现 debugpoint |