rtos-debug

Original：🇨🇳 Chinese

Translated

1 scriptsChecked / no sensitive code detected

Used for thread-aware debugging of FreeRTOS/RT-Thread/Zephyr, such as viewing task lists, stack watermarks, or detecting deadlocks.

4installs

Added on2026-05-16

NPX Install

npx skill4agent add leokemp223/embed-ai-tool rtos-debug

Firmware runs RTOS (FreeRTOS, RT-Thread, or Zephyr) and needs to check task status.
Suspect task stack overflow causes HardFault or abnormal behavior.
Need to detect deadlocks (all tasks are in waiting state).
Need to view the status of kernel objects such as queues and semaphores.
Need to automatically identify the RTOS type used by the firmware.

Path to the signed
```
ELF
```
file.
Running GDB Server (OpenOCD or JLinkGDBServer), specify the GDB port via
```
--port
```
.
Optional explicit specification of RTOS type (
```
--rtos freertos|rt-thread|zephyr
```
).

Automatically determine the RTOS type through the ELF symbol table:
```
vTaskStartScheduler
```
→ FreeRTOS,
```
rt_thread_init
```
→ RT-Thread,
```
k_thread_create
```
→ Zephyr.
Does not depend on OpenOCD's RTOS awareness function, instead uses GDB to directly read RTOS kernel data structures.
Full support for FreeRTOS (task list, stack watermark, queues), basic task list support for RT-Thread/Zephyr.

First read references/usage.md and references/rtos-patterns.md to understand common RTOS problem patterns.
Ensure the GDB Server (OpenOCD or JLinkGDBServer) is running.
If unsure of the RTOS type, first run the
```
--detect
```
mode of scripts/rtos_debugger.py.
Use
```
--tasks
```
to view the task list and status.
Use
```
--stack-check
```
to check the stack watermark of each task.
Use
```
--deadlock
```
to check for deadlock characteristics.
Use
```
--queues
```
to view the status of queues and semaphores.

Returns
```
environment-missing
```
when GDB is missing.
Returns
```
artifact-missing
```
when no available
```
ELF
```
is present.
Returns
```
connection-failure
```
when GDB cannot connect to the GDB Server.
Returns
```
project-config-error
```
when no RTOS symbols are detected in the ELF.
Returns
```
target-response-abnormal
```
when GDB can connect but cannot read RTOS data structures.
Returns
```
ambiguous-context
```
when the RTOS type cannot be determined.

The built-in scripts use Python standard libraries and subprocess to call GDB, which is cross-platform compatible.
The GDB Server needs to be pre-started by the user or upstream skills (
```
debug-gdb-openocd
```
or
```
debug-jlink
```
).
Reading RTOS data structures depends on ELF symbol information; Release optimization may cause some symbols to be optimized out.

Output the detected RTOS type and version (if available).
Output the task list, including task name, status, priority, and stack usage information.
Output an alarm when the stack watermark is below the safety threshold.
Output deadlock detection results in a clear yes/no format.
Update the
```
rtos
```
field in
```
Project Profile
```
.

When stack overflow is confirmed, it is recommended to use
```
memory-analysis
```
to analyze the firmware memory layout.
When deeper single-step debugging is required, hand over to
```
debug-gdb-openocd
```
or
```
debug-jlink
```
.