XFlashGate MCU Debug

通过ESP-DAP进行MCU源码调试的Visual Studio Code插件。提供工程与工具配置、设备算法选择、下载校验、源码调试、运行变量观察、RTT终端及故障分析。

环境要求

工具和厂家算法不随插件打包。当前实机验证目标为STM32C551，FreeRTOS样本使用Cortex-M33非TrustZone、非MPU且启用FPU的port。其它芯片、内核及RTOS port的支持取决于目标能力和适配配置，不能将该样本的通过结果推广到全部MCU。

打开MCU工程，在左侧 XFlashGate → MCU调试 → 配置调试 进入分组表单。
在“工具与构建”选择一个GNU安装目录或bin目录；GCC、GDB、nm、objdump从同一目录识别。CMake/Ninja可使用本机路径或自动识别，J-Link和Keil主目录为可选项。
选择工程已有CMake preset及对应ELF/AXF，执行 查看同步预览 → 同步CMake与调试配置 → 配置并构建。插件保留已有CPU/FPU/ABI、宏和链接脚本。
填写设备URL、目标MCU和core/AP，执行 检查设备。从设备已有列表按算法名称选择，插件管理设备内部标识。
选择 GDB Server 或 J-Link兼容，使用 附加调试 或 下载并调试。
使用VS Code原生断点、调用栈、Variables、Watch、F10/F11/Shift+F11；可添加并使用F5调试配置。

直接模式连接设备GDB RSP；J-Link兼容模式通过本机J-Link Server连接设备原生探针接口。这两种端口不能互换。下载并调试先使用设备所选算法下载与核对，再进入所选源码调试模式；附加不隐式下载或构建。

本机工具路径按工程和系统保存到本机存储，不写入可提交的工程设置。换机器或VS Code Profile后需要重新识别本机工具。设备动作凭据使用SecretStorage；不要把凭据写入JSON或日志。

Memory：命令 XFlashGate: Memory（内置只读），暂停时按页查看RAM，支持地址与数值分析。首版不修改内存。

FreeRTOS：底部 XFlashGate RTOS 可展开任务、保存寄存器、调用栈和变量，并定位源码。任务快照在主会话继续、写入或结束后失效；不会用CPU线程代替完整任务上下文。

Live Watch：在配置中显式启用，默认2次/秒；适合地址稳定的全局变量。运行观察不通过后台暂停目标实现，停机局部变量仍使用Variables/Watch。

外设寄存器：底部 XFlashGate 外设 支持CMSIS-SVD和Keil SFD文本、筛选、寄存器/位域/枚举及手动读取。二进制SFR不支持。只读也可能触发硬件副作用，带readAction的寄存器会要求确认，只写寄存器拒绝读取。

RTT：底部 XFlashGate RTT 与Terminal同级，使用图标工具栏。支持UTF-8/hex、ANSI/级别高亮、搜索、清屏、跟随输出、原始导出及移至新窗口/返回底部。输入可选择独立下行通道与行尾，Enter发送，方向键回看历史；提交到连接与被MCU消费是不同状态。

RTT、Live Watch及任务视图依赖目标固件的符号、内存与能力。准备失败时请按原入口提示修正地址、通道、符号或连接模式。

优先捕获能停住的HardFault现场。保存异常/当前寄存器、配置范围内的RAM、匹配符号、调用栈和按帧组织的变量值，并支持报告源码定位及只读离线回放。缺失或截断的采集会明确标注，不用低可信扫描冒充完整回溯。

自动HardFault捕获按实际内核能力启用，看门狗冻结按实际芯片身份与配置匹配；停止时先恢复CPU运行，再恢复本插件改变的冻结位并读回核对，避免停机接力期间看门狗到期。当前C551有目标配置，其它MCU不能复用C551外设地址。复位后的RAM和完整CPU状态恢复不属于当前版本范围。

通过 XFlashGate: AI/MCP诊断 显式开启，默认关闭，仅用于可信本机工程。开启后在VS Code MCP: List Servers 中启动并信任本插件服务；也可复制本次外部客户端连接配置。关闭或重启后凭据失效。

八个工具提供当前会话状态、线程、调用栈、变量、暂停RAM、RTT缓存、已保存故障报告和外设采集缓存。接口没有下载、写内存、复位、继续或任意GDB命令，不自动附加/暂停MCU；Remote/Web工作区不在首发验收范围。

正常停止等待本插件GDB/J-Link进程释放，核对本会话硬件断点槽并恢复调试控制。VS Code宿主异常退出后，重开可能显示 恢复上次未结束调试；核对仍是同一设备和MCU后执行。身份/固件改变或资源被其它会话占用时拒绝沿用旧控制值。

这个入口只清理调试控制，不下载Flash、不复位目标，也不还原RAM或CPU现场。失败记录保留，诊断入口可定位错误并重试。

工具找不到：回到配置页重新选择GNU/CMake/Ninja目录或文件，并执行“检查工具版本”。
GNU链接器无法加载liblto_plugin.dll：检查GNU工具链的安装路径，选择不含中文的工具目录后重试完整构建。工具版本检查通过，并不能确认链接器能够加载所需DLL。
设备忙或鉴权失败：协调其它调试器释放资源；在“设置动作凭据”更新凭据后重新检查。
变量不可用：核对ELF/AXF与机器码、当前栈帧和DWARF；优化掉的变量不能凭空恢复。
RTT无输出或输入未就绪：核对RTT控制块搜索范围、上下行通道、端口及目标初始化状态。
任务或外设值过期：暂停后从原视图重新手动采集；继续后的旧快照不能当作当前状态。

产品名称更改后仍保留扩展ID xcheng.esp-dap-debug、原配置/命令/视图ID和既有F5/任务入口。工具问题可在 XFlashGate: 查看诊断记录 定位；反馈前请去除凭据、个人目录和目标业务敏感数据。