---name: rtos-debugdescription: 当需要进行 FreeRTOS/RT-Thread/Zephyr 的线程感知调试，查看任务列表、栈水位或死锁检测时使用。---

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，rt_thread_init → RT-Thread，k_thread_create → Zephyr。
• 不依赖 OpenOCD 的 RTOS awareness 功能，改用 GDB 直接读取 RTOS 内核数据结构。
• FreeRTOS 提供完整支持（任务列表、栈水位、队列），RT-Thread/Zephyr 提供基本任务列表支持。

执行步骤

1. 先阅读 references/usage.md 和 references/rtos-patterns.md，了解常见 RTOS 问题模式。
2. 确保 GDB Server（OpenOCD 或 JLinkGDBServer）已在运行。
3. 若不确定 RTOS 类型，先运行 scripts/rtos_debugger.py 的 --detect 模式。
4. 使用 --tasks 查看任务列表和状态。
5. 使用 --stack-check 检查各任务栈水位。
6. 使用 --deadlock 检查死锁特征。
7. 使用 --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。