SKILL.md
RTOS 调试
适用场景
- 固件运行了 RTOS（FreeRTOS、RT-Thread 或 Zephyr），需要查看任务状态。
- 怀疑任务栈溢出导致 HardFault 或异常行为。
- 需要检测死锁（所有任务都处于等待状态）。
- 需要查看队列、信号量等内核对象状态。
- 需要自动识别固件使用的 RTOS 类型。
必要输入
- 带符号的
ELF文件路径。 - 已运行的 GDB Server（OpenOCD 或 JLinkGDBServer），通过
--port指定 GDB 端口。 - 可选显式指定 RTOS 类型（
--rtos freertos|rt-thread|zephyr）。
自动探测
- 通过 ELF 符号表自动判断 RTOS 类型：
vTaskStartScheduler→ FreeRTOS，rtthreadinit→ RT-Thread，kthreadcreate→ Zephyr。 - 不依赖 OpenOCD 的 RTOS awareness 功能，改用 GDB 直接读取 RTOS 内核数据结构。
- FreeRTOS 提供完整支持（任务列表、栈水位、队列），RT-Thread/Zephyr 提供基本任务列表支持。
执行步骤
- 先阅读 [references/usage.md](references/usage.md) 和 [references/rtos-patterns.md](references/rtos-patterns.md)，了解常见 RTOS 问题模式。
- 确保 GDB Server（OpenOCD 或 JLinkGDBServer）已在运行。
- 若不确定 RTOS 类型，先运行 [scripts/rtosdebugger.py](scripts/rtosdebugger.py) 的
--detect模式。 - 使用
--tasks查看任务列表和状态。 - 使用
--stack-check检查各任务栈水位。 - 使用
--deadlock检查死锁特征。 - 使用
--queues查看队列和信号量状态。
失败分流
- 当缺少 GDB 时，返回
environment-missing。 - 当没有可用的
ELF时，返回artifact-missing。 - 当 GDB 无法连接到 GDB Server 时，返回
connection-failure。 - 当 ELF 中未检测到 RTOS 符号时，返回
project-config-error。 - 当 GDB 可以连接但无法读取 RTOS 数据结构时，返回
target-response-abnormal。 - 当无法确定 RTOS 类型时，返回
ambiguous-context。
平台说明
- 自带脚本使用 Python 标准库和 subprocess 调用 GDB，跨平台兼容。
- GDB Server 需要由用户或上游 skill（
debug-gdb-openocd或debug-jlink）预先启动。 - RTOS 数据结构读取依赖 ELF 符号信息，Release 优化可能导致部分符号被优化掉。
输出约定
- 输出检测到的 RTOS 类型和版本（如果可获取）。
- 输出任务列表，包含任务名、状态、优先级和栈使用信息。
- 栈水位低于安全阈值时输出告警。
- 死锁检测结果以明确的是/否形式输出。
- 在
Project Profile中更新rtos字段。
交接关系
- 当确认栈溢出时，建议使用
memory-analysis分析固件内存布局。 - 当需要更深入的单步调试时，交给
debug-gdb-openocd或debug-jlink。