mspm0-ccs

MSPM0 Agent 技能

将此技能用于通过 CCS / CCS Theia、Keil/uVision 或 CMake + Arm GNU Toolchain + OpenOCD 工作流，使用 SysConfig 和 DriverLib 的 TI MSPM0 固件项目。适用于 Claude Code、OpenCode、OpenClaw、Continue、Cursor、Codex 等类似的命令行/编辑器 Agent。

默认工作流

1. 定位项目的 .syscfg 或 system.syscfg、可编辑源文件、生成的 ti_msp_dl_config.h，以及当前项目入口文件：CCS 项目中的 targetConfigs/*.ccxml、Keil/uVision 项目中的 *.uvprojx 和 scatter 文件，或 CMake/GCC/OpenOCD 项目中的 CMakeLists.txt 和 OpenOCD .cfg 文件。
2. 若有此技能，运行 python scripts/check_syscfg.py <project-dir>。
3. 读取 .syscfg 元数据：器件、封装、SDK 产品、SysConfig 版本、模块、实例、引脚、时钟和中断。
4. 检查生成的 ti_msp_dl_config.h，确认宏名称、IRQ 名称、实例名称，以及 SysConfig 初始化函数的准确拼写。
5. 添加不熟悉的 SysConfig 字段前，检查用户现有的 .syscfg、examples/*/manifest.json、TI SDK 示例或 source/ti/driverlib/.meta/*.syscfg.js。
6. 仅修改相关的 .syscfg 和应用代码中最小范围的内容。
7. 默认情况下，基于证据对 .syscfg 做最小修改，并在重新构建前运行 python scripts/run_sysconfig.py <project-dir>。仅当用户明确要求，或当前会话已提供经过确认的 SysConfig MCP 工具时，才使用 CCS SysConfig MCP。
8. 若要刷写或调试，在选择后端前运行 python scripts/detect_probe.py 或 python scripts/check_syscfg.py <project-dir> --probe。确认配置的探针与已连接的硬件匹配，并优先在编程后执行系统复位。

核心规则

• 将 .syscfg 视为引脚复用、外设设置、时钟、中断、DMA 所有权和生成的初始化代码的唯一可信来源。
• GPIO、UART、PWM、Timer、ADC、I2C、SPI、DMA 和时钟设置优先使用 SysConfig + DriverLib。
• 不要手动编辑生成的输出文件，例如 Debug/ti_msp_dl_config.c、Debug/ti_msp_dl_config.h、Keil 布局中项目根目录下的 ti_msp_dl_config.c / ti_msp_dl_config.h 文件对、device_linker.cmd、Objects/、Listings/、目标文件、映射文件或 .out 文件。
• 保留 .syscfg 元数据，例如 @cliArgs、@v2CliArgs、@versions、--device、--package 和 --product。
• 不要猜测生成的名称。读取 ti_msp_dl_config.h，并使用本地宏和本地初始化函数的拼写，例如 SYSCFG_DL_init()。
• 不要臆造 SysConfig 字段、枚举值、设备元数据、开发板名称、封装名称或工具版本。请对照本地示例、SDK 元数据或 SysConfig CLI 进行验证。
• 新版 SysConfig 可能会明确建议使用 CCS SysConfig MCP。默认情况下，本技能不会探测或要求使用这个未经验证的后端：只有在用户要求使用 MCP，或当前会话已提供经过确认的 SysConfig MCP 工具时，才使用它。否则，进行最小限度的手动编辑，然后立即使用独立 CLI 验证，并说明这种方式无法提供 MCP 的交互式修改反馈。
• 保留无关的用户代码、注释、版权声明、项目布局和现有 .syscfg 设置。如果请求的功能需要大幅重写，尽可能在修改前说明原因。
• 未经用户确认，不要更改设备、封装、SDK、编译器、CCS 版本、开发板或调试探针。
• 如果用户只要求“烧录”或“调试”，不要擅自假定使用 J-Link、XDS110、CMSIS-DAP/DAPLink 或 ST-Link。先检测已连接的探针。如果无法确定检测结果、连接了多个探针，或项目配置与实际探针冲突，请停止并询问用户要使用哪个后端。
• 将探针检测器的空结果视为无法确定，而不是没有探针连接的证明。有些 DAPLink/CMSIS-DAP 和 XDS110 设备只会显示为 Windows 的 USBDevice、HIDClass 或 Ports 子设备。请检查操作系统的 USB/PnP 设备和串行端口（在 Windows 上运行 python scripts/serial_console.py --list），然后尝试目标后端的只读探针检测/列表命令，或在判定探针不存在前询问用户。
• 如果 SysConfig 发出警告，请将其与构建/烧录是否成功分开报告。不要把产生警告的生成结果称为“无警告”。
• 如果未在已连接的开发板上验证硬件行为，请说明验证仅进行到源码、SysConfig 或构建阶段。

特定开发板的引脚注意事项

当用户明确说明开发板是 LCKFB Tianmengxing MSPM0G3507 时：

• 除非用户要求使用这些引脚，或本地项目已经有意使用它们，否则不要为用户的一般引脚分配选择 A21/PA21、A23/PA23、A02/PA02 和 A18/PA18。
• PA10 和 PA11 也标记为特殊引脚，但 Tianmengxing 将它们用作默认 UART 引脚。为 UART 选择引脚时，如果 PA10 TX 和 PA11 RX 未被占用，且与所请求的 UART 实例匹配，请优先考虑这两个引脚。对于 GPIO、PWM、SPI、I2C、定时器或其他非 UART 用途，仍应将 PA10/PA11 视为特殊引脚，并优先选择其他可用引脚。
• 如果用户要求将这些特殊引脚用于非默认用途，或重新使用这些引脚，请提醒他们注意 Tianmengxing 开发板说明。尤其要说明，改作他用可能会与开发板默认的 UART 连接冲突，或将其移除。
• 不要擅自将现有项目改用其他引脚。先说明开发板注意事项，再根据用户意图询问或继续操作。

项目结构检查

• 简单项目通常将大部分逻辑放在 main.c、empty.c 或少数几个文件中。在这些文件中进行范围明确的修改是可以接受的。
• 框架项目通常包含多个源代码目录，例如 app/、bsp/、components/、core/、drivers/、hal/、middleware/ 或 tasks/。添加外设或更改控制逻辑前，先确定各部分的归属边界。
• 不要假设每个 MSPM0 项目都类似 CCS 或只有单个文件。框架项目也可能使用 CCS、Keil 或 CMake/GCC/OpenOCD。
• 对于控制代码，在更改周期或优先级前，确认其时序来自定时器 ISR、RTOS 任务延时、硬件 PWM/ADC 触发链，还是主循环轮询。

Keil 项目检查

• 对于将 SysConfig 输出文件保留在项目根目录中的 Keil 类 MSPM0 项目，将 system.syscfg 和 ti_msp_dl_config.c / ti_msp_dl_config.h 视为配置源文件。
• 将 Keil .uvprojx 视为项目入口点，将散布文件视为链接器配置的唯一事实来源；除非请求明确针对 Objects/、Listings/、*.uvoptx、构建日志和生成的输出文件，否则仅检查这些内容，不要修改。
• 对于项目应用代码，遵循其自身的源代码布局，不要假设采用 CCS 默认布局。

CMake / GCC / OpenOCD 检查

• 对于 CMake/GCC/OpenOCD 项目，将 CMakeLists.txt、工具链文件和 OpenOCD .cfg 文件视为项目入口点。
• 如果存在现有的 CMake 构建目录，应通过该目录进行构建，例如 cmake --build cmake-build-debug --target <target>。
• 对 MSPM0 进行 OpenOCD 烧录通常需要支持 TI MSPM0 的 OpenOCD 构建版本或 TI 扩展分支。如果 OpenOCD 报告 unable to find a matching CMSIS-DAP device，应将其说明为探针发现失败，而不是固件故障。
• 如果当前项目使用 OpenOCD 而非 DSLite，则不要要求提供 CCS targetConfigs/*.ccxml。

FreeRTOS 检查

• 如果存在 FreeRTOSConfig.h、FreeRTOS.h、task.h、xTaskCreate 或 vTaskStartScheduler，则将该项目视为支持 RTOS。
• RTOS 处理应保持轻量：遵循现有任务、队列、ISR 和阻塞调用的边界；除非用户提出要求，否则不要强加特定的框架架构。

不明确的请求

如果用户遗漏了重要的硬件参数，不要默默选用有风险的值。

• 对于低风险默认值，请使用此技能的 examples/ 或本地 TI SDK 示例，然后告知用户采用了哪些默认值。
• 对于重要参数，编辑前先询问，并提供明确的建议。
• 重要的缺失参数包括引脚、外设实例、UART 波特率/数据位/奇偶校验/停止位、定时器周期、PWM 频率/占空比/极性、ADC 通道/参考电压/采样时间、DMA 方向/源/目标、中断优先级，以及外部模块的电源/逻辑电平。

示例：如果用户要求“添加定时器中断”，请询问他们想使用哪个定时器以及周期是多少；如果他们不确定，可以建议从 TIMG 的 1 ms 或 10 ms 开始。

外部模块与硬件调试

用户要求驱动外部模块、传感器、电机驱动器、舵机、显示屏、无线电设备或定制板卡时：

• 如果未提供相关信息，请索取模块数据手册、原理图、引脚图、电源电压、逻辑电平、通信协议和关键参数。
• 在归咎于代码之前，先核实接线假设：电源、接地、上拉电阻、电平转换、复位/使能引脚、启动引脚、片选、UART TX/RX 交叉连接、I2C 地址、SPI 模式、PWM 极性和共享引脚。
• 如果多次尝试失败，而 SysConfig、构建、烧录和代码逻辑看起来都正确，应明确指出可能存在接线、电源、模块模式、数据手册不匹配、硬件损坏或测试方法错误等问题。
• 明确区分“固件看起来正确”和“硬件已验证正确”。

参考资料选择

仅在需要时阅读参考资料：

• references/project_workflows.md：.syscfg 编辑、CCS / Keil / CMake 项目布局、SDK 架构查询、SysConfig CLI、构建、DSLite/J-Link 和 OpenOCD。
• references/driverlib_runtime_rules.md：DriverLib 用法、中断、时钟树、延时和常见运行时错误。
• references/hardware_validation_notes.md：已验证的天梦星 MSPM0G3507 经验、HFXT 警告、闪存/复位行为和实际开发板注意事项。
• references/debug_backends.md：CCS-DSS 和 OpenOCD/GDB 探针、闪存、断点、重试和手动解锁工作流。

将 examples/ 用作可复用测试模式的一个来源。打开单个示例文件之前，优先使用 scripts/list_examples.py 查看可用示例，但不要假定打包的示例优先于用户现有的项目结构或 TI 官方 SDK 示例。

示例

每个可复用示例都应包含：

examples/<name>/
├─ example.syscfg
├─ README.md
├─ manifest.json
└─ src/
   └─ source files copied from the minimal relevant project surface

不要要求用户将完整 CCS 项目放入 examples/。使用 scripts/capture_example.py 从真实项目中提取精简的示例包。

将示例应用到用户项目时：

• 将技能示例视为经过验证的参考，而非必须遵循的项目模板。
• 仅复制所需的 .syscfg 字段、生成名称预期、代码模式或调试经验。
• 保留用户现有的文件布局和命名。如果示例使用 BSP/，除非用户要求采用该结构或项目本来就遵循该结构，否则不要在用户项目中创建 BSP/。
• 如果示例的目录名、封装名称或分层方式与用户的本地风格冲突，优先采用用户的本地风格。
• 如果 TI 官方 SDK 示例和本地 SDK 元数据更符合用户的开发板、SDK 版本、外设或工具链，则应将它们视为同等或更高优先级的参考。
• 对于 DMA UART 示例，每个 UART 实例都应使用各自的 TX 缓冲区，避免使用共享的静态 printf 缓冲区，并根据各端口的用途选择 RX 处理方式：需要立即解析行的端口使用 ISR 回调，额外的接收端口使用 UART_poll()，不接收数据的端口则仅初始化 TX。
• 对于周期性定时器中断，在 .syscfg 中配置 TIMER 实例和中断，根据生成的 CPU 时钟确认生成的加载值，在应用代码中启用生成的 IRQ，并保持 ISR 简短。

工具

使用 Python 3.10 或更高版本运行捆绑脚本。serial_console.py 还需要 pyserial；如果导入失败，请告知用户运行 python -m pip install pyserial。TI SDK、SysConfig、CCS/UniFlash、OpenOCD 和 GDB 仍是外部工作流依赖项，本技能不会安装它们。

• python scripts/check_syscfg.py <project-dir>：静态检查项目中的 .syscfg、生成文件、引脚、初始化拼写、项目结构、CCS/Keil/CMake/OpenOCD 线索、构建输出、目标配置和验证提示。
• python scripts/run_sysconfig.py <project-dir>：发现项目声明的 SysConfig 和 MSPM0 SDK 版本，然后在隔离的临时目录中验证所选 .syscfg，不会覆盖项目输出。仅在有意显式覆盖时使用 --tool 或 --product。
• python scripts/detect_probe.py：以只读方式检测已连接的常见 CMSIS-DAP/DAPLink、J-Link、XDS110 和 ST-Link 硬件；结果为空并不代表结论明确，必须进一步通过操作系统/后端检查。
• python scripts/check_syscfg.py <project-dir> --probe：运行静态检查、检测已连接的探针、将其与项目线索进行比较；如果 CCS .ccxml 与物理探针冲突，则抑制不安全的烧录建议。
• python scripts/list_examples.py：列出 examples/*/manifest.json 中打包的示例。
• python scripts/capture_example.py <project-dir> --name <example-name> --include <glob>：将用户项目中选定的源文件和 .syscfg 打包到 examples/<example-name>/。
• python scripts/index_syscfg_examples.py <mspm0-sdk-root> --board LP_MSPM0G3507 --module UART：搜索本地 TI SDK 示例和模块元数据。
• python scripts/serial_console.py --list：列出串口。
• python scripts/ccs_dss_debug.py <project-dir> probe --leave-running：通过 CCS Debug Server Scripting 连接，读取复位/寄存器状态，验证已配置的 .ccxml 调试路径，并在断开连接前继续运行目标。
• python scripts/ccs_dss_debug.py <project-dir> load-symbols --symbol main：从 .out 加载调试符号，不烧录闪存。
• python scripts/openocd_debug.py <project-dir> probe：通过 OpenOCD 连接，短暂暂停运行，报告目标状态，然后恢复运行。
• python scripts/openocd_debug.py <project-dir> flash：通过 OpenOCD 烧录、验证并复位运行自动检测到的 .out、.elf、.axf 或 .hex 输出。
• python scripts/openocd_debug.py <project-dir> run-to-symbol --symbol main：使用 OpenOCD + arm-none-eabi-gdb 复位并运行，直到遇到符号断点。

对于已验证的 CH340 配置，关闭 VOFA+ 等其他串口工具后，运行 python scripts/serial_console.py -p COM6 -b 115200 --timestamp --duration 10。 对于基于行的 MCU 解析器，发送一个测试帧并等待回显：python scripts/serial_console.py -p COM6 -b 115200 --send "ping" --send-line --timestamp --duration 3。测试二进制负载时使用 --send-hex "00 00 80 3F"。

烧录后端

对于“烧录此项目”之类含义不明确的请求，在选择烧录后端之前，先运行：

python scripts/detect_probe.py
python scripts/check_syscfg.py <project-dir> --probe

探针检测是只读的。如果连接了多个探针、检测结果未知，或物理探针与项目配置冲突，在用户确认预期后端之前，请勿烧录。在 Windows 上，如果未识别到探针，请检查 Get-PnpDevice -PresentOnly 和 python scripts/serial_console.py --list；调试探针可能会在通用 USB 设备类别之外提供 CMSIS-DAP/XDS 接口或虚拟 COM 端口。

已验证的 CCS 烧录路径是使用 J-Link 的 DSLite / UniFlash。对于时钟树变更后的自动烧录，优先使用 DSLite System Reset：

dslite -c <target.ccxml> -e -r 2 -u <project.out>

对于 CMake/GCC/OpenOCD 项目，请使用项目现有的烧录目标或显式的 OpenOCD 配置。打包的 openocd_debug.py 辅助脚本也可以烧录现有的兼容输出。明确指定后端，并将探针发现错误与构建成功情况分开报告。

调试后端

将 CCS-DSS 和 OpenOCD/GDB 作为独立后端。开始调试或诊断探针反复故障之前，请阅读 references/debug_backends.md。

对于包含匹配的 targetConfigs/*.ccxml 的 CCS / CCS Theia / UniFlash 风格项目：

python scripts/ccs_dss_debug.py <project-dir> probe --leave-running

对于支持 OpenOCD 的 MSPM0 项目：

python scripts/openocd_debug.py <project-dir> probe

CCS-DSS 物理探针由 .ccxml 选择；它并非天然只能使用 J-Link。如果固件已烧录且无需重写闪存，请仅加载符号。对于 OpenOCD，不要对同一个探针并发执行操作。任一后端都不应在不告知用户的情况下执行破坏性恢复。如果目标看起来已锁定或受保护，应先区分探针/接线/复位故障、应用启动故障、SWD 密码或安全策略、无效的 NONMAIN 配置，以及闪存写入中断后的恢复状态。在天梦星 MSPM0G3507 上，曾复现过如下情况：可读取 SWD DPIDR，随后反复出现 Could not find MEM-AP to control the core 错误；这是在编程中断后发生的。请遵循 references/debug_backends.md 中的 UART BSL 恢复界限，不要据此认定探针不存在。使用匹配的 XDS 目标配置时，即使 Cortex-M0+ 会话无法连接，CCS-DSS 仍可能成功执行只读的 CFGAP_BOOTDIAG 检查。只有在用户明确授权数据丢失后，才能使用 BSL Mass Erase、DSSM Mass Erase 或 Factory Reset，并且必须遵循 references/debug_backends.md；切勿仅凭复位脉冲或命令超时就认定操作成功。调试操作可能会暂停 CPU，因此在实时控制硬件上使用断点或检查寄存器之前，请告知用户这一风险。