FreeRTOS GDB

1.0.4 verified Mon Apr 27 auth: no python

Python module for inspecting FreeRTOS kernel objects (tasks, queues, semaphores, timers, event groups) from within GDB. Current version: 1.0.4. Part of Espressif's toolchain, closely tied to ESP-IDF. Release cadence is low, with infrequent updates.

pip install freertos-gdb

Common errors

error ModuleNotFoundError: No module named 'freertos_gdb' ↓

cause Trying to import the module outside GDB's Python environment.

fix

Run the import inside GDB's Python interpreter after loading a firmware binary.

error Failed to locate FreeRTOS kernel objects. Ensure the target is running FreeRTOS. ↓

cause The firmware does not have FreeRTOS kernel symbols or is not running.

fix

Check that your firmware includes FreeRTOS and is currently executing (halted with GDB).

Warnings

breaking Only works within GDB's Python interpreter (not standalone Python). ↓

fix Load your firmware binary in GDB, then run 'python import freertos_gdb; freertos_gdb.FreeRTOS()' from GDB prompt.

gotcha Requires FreeRTOS kernel symbols to be present in the target firmware; otherwise commands will fail or show no output. ↓

fix Ensure your firmware is compiled with FreeRTOS debug symbols (e.g., CONFIG_FREERTOS_DEBUG in ESP-IDF).

Imports

FreeRTOS
```
from freertos_gdb import FreeRTOS
```
Standard import to access FreeRTOS inspection commands.

Quickstart

Import and instantiate FreeRTOS in GDB Python console to enable FreeRTOS-aware debugging commands.

# In GDB, after loading firmware:
import freertos_gdb
freertos_gdb.FreeRTOS()
# Then use commands: info tasks, info queues, etc.