pyGdbToolkit: quickstart
What is pyGdbToolkit?
pyGdbToolkit is an open-source collection of GDB commands for inspecting and diagnosing embedded targets, especially Arm Cortex-M microcontrollers. Developed by H2Lab, it extends your debugger with readable reports about the processor, peripherals, faults, RTOS tasks, and security configuration.
Its client/server mode goes beyond manual commands: an optional LLM agent can help audit the target by correlating firmware source code with observations from its execution. Rather than only explaining a code fragment or a register dump in isolation, the agent can investigate a question across software context and the connected target, under the auditor’s supervision.
Source code on GitHub · Package on PyPI · Full documentation
Why use it?
Instead of switching between vendor tools, register manuals, and one-off scripts, you can investigate a target from the same GDB session used to debug its firmware. pyGdbToolkit uses the existing debugger connection to help you:
- Identify the processor and discover target information with
lscpu. - Understand peripheral registers using CMSIS-SVD descriptions rather than raw addresses.
- Diagnose crashes by decoding Cortex-M fault status and exception context.
- Inspect security settings and RTOS state, including supported MPU, TrustZone, Camelot, and Zephyr configurations.
- Connect source-level intent with runtime evidence through the dashboard’s optional LLM agent, combining authorized project-source access with debugger observations to guide an investigation.
It is useful for firmware bring-up, debugging unexpected hardware behaviour, and embedded security investigations. Available information depends on the target and its debug access. You can work directly in GDB or use a terminal dashboard backed by a supervised debugging session.
1. Install from PyPI
You need Python 3.12 or newer, GDB with compatible embedded Python support (typically gdb-multiarch for Arm), and a connected target with a debug probe and a configured OpenOCD or pyOCD server.
Install the published package with pip; no Git checkout is required. A virtual environment keeps the installation separate from your system’s Python packages:
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install pygdbtoolkit
Before connecting hardware, check the Python interpreter embedded in GDB:
gdb-multiarch -nx -batch -ex 'python import sys; print(sys.version); print(sys.path)'
Use a Python environment compatible with that interpreter. GDB must be able to import the package and its dependencies; activating a virtual environment alone does not guarantee this. Check the import separately:
gdb-multiarch -nx -batch -ex 'python import pyGdbToolkit'
If this fails, follow the Python environment setup in the first-session guide before continuing. It explains how to make the installed environment visible to GDB.
2. Choose your session mode
Both modes provide the same toolkit commands, but the client/server dashboard also offers an optional LLM-assisted audit workflow:
| Mode | Best suited to |
|---|---|
| Direct GDB | An existing debugging setup, or users who prefer GDB’s native prompt. |
| Server and client | A supervised probe/GDB session with live logs, a terminal dashboard, and optional LLM-assisted audits correlating firmware sources with target execution. |
Option A: connect directly from GDB
Start your board’s OpenOCD or pyOCD GDB server separately, then open your firmware’s ELF file:
gdb-multiarch firmware.elf
At the GDB prompt:
(gdb) target extended-remote localhost:3333
(gdb) monitor reset halt
(gdb) python import pyGdbToolkit
(gdb) lscpu
Replace firmware.elf and port 3333 with your own firmware and server settings. The reset command depends on the debug server and resets the target; omit it if you need to preserve the current state, and halt the target before inspection. lscpu reports the detected core and available device information.
For board and probe setup, see the configuration examples.
Option B: use the server and terminal dashboard
Choose a configuration example matching your probe and board, save it as servercfg.json, and adapt its executable paths, target settings, and ports. Then start the session:
pyGdbServer servercfg.json
The server starts the configured OpenOCD or pyOCD process and GDB, loads the toolkit, and runs the configured initialization commands. In another terminal, activate the same Python environment and launch the client:
. .venv/bin/activate
pyGdbClient ws://localhost:1234
Use the WebSocket port from your configuration: the documented pyOCD example uses 1234, while the OpenOCD example uses 1235. This is the client connection, not GDB’s target port.
At the dashboard prompt, try:
lscpu
gdb info registers
monitor help
Toolkit commands such as lscpu run directly; prefix native GDB commands with gdb. Use quit to disconnect the client, or quit --all to stop the supervised session as well.
Keep the server bound to loopback for this local quickstart. For remote access, automation, and full configuration, see the server/client guide.
Go beyond manual commands with an LLM-assisted audit
The dashboard can attach an LLM agent to the debugging session. You describe an audit objective in natural language; the agent can plan a sequence of inspections, request observations through GDB, the debug server, and toolkit commands, then use the results to refine its analysis. This turns individual commands into a guided investigation rather than requiring you to select and interpret every command yourself.
The key benefit is bringing the target’s software sources and its execution into the same audit context. With a supported project loaded and source access explicitly enabled where required, the agent can inspect relevant code and relate it to observed registers, memory, fault context, or RTOS state. This helps check whether the implementation’s intended behaviour agrees with what is actually observable on the device. Source access depends on the selected backend and project setup; it is not enabled automatically for every session.
For example, with the appropriate project context and agent configured, you could ask:
Find the code that configures memory protection, inspect the target’s current MPU settings, and explain any differences between the intended policy and the observed configuration.
Or, after the target stops in a fault handler:
Use the fault context and the corresponding firmware sources to investigate the failing operation. Distinguish confirmed observations from hypotheses and suggest the next checks.
These are investigation requests, not predefined commands or guarantees of a finding. The agent can chain complementary observations and relate them to source code, going well beyond a static code explanation or a manually collected register report. Its conclusions still require review: source code, build artifacts, and the flashed firmware must correspond for meaningful comparisons.
Target operations remain subject to a local protection policy, with explicit approval for operations that require it. LLM assistance is optional and must be configured separately. For production or confidential audit data, use a local model on trusted equipment; do not enable source sharing with an external provider unless disclosure is authorized.
For supported providers, project loading, source-access permissions, and setup instructions, follow the agent-assisted audit guide.
3. Discover the target’s memory
The following examples use the direct GDB prompt. In the dashboard, enter the same toolkit commands without the (gdb) prefix.
Memory discovery works without a loaded SVD or firmware ELF. With the target connected and halted, start with:
(gdb) memmap discover
(gdb) memmap show
(gdb) memmap report mapping.json
This gathers available identity and memory-map information, displays the result, and exports a report to mapping.json on the machine running GDB. It is useful when exploring an unfamiliar board before loading peripheral descriptions.
On a target you are authorized to probe, you can also sample access at declared memory-region endpoints:
(gdb) memmap discover --verify
These are real target accesses, not an exhaustive memory scan. Successful samples do not prove that a whole region is accessible, and failures do not by themselves prove protection. See the memory discovery guide for probing precautions and report interpretation.
4. Inspect a peripheral
With the target halted, load its CMSIS-SVD register description and list the peripherals:
(gdb) svd load
(gdb) svd list
(gdb) svd show GPIOA
Use a peripheral name returned by svd list; GPIOA is an example. This lets you inspect named registers and fields instead of manually decoding addresses. Automatic loading depends on device support and may need network access. To use a local description instead:
(gdb) svd read /path/to/device.svd
Register reads can have hardware side effects. Check the device reference manual before inspecting sensitive peripherals. See the SVD guide for details.
5. Investigate a fault
For example, set a breakpoint on your firmware’s fault handler before resuming execution. If its symbol is HardFault_Handler:
(gdb) break HardFault_Handler
(gdb) continue
If execution stops in a Cortex-M fault handler, run:
(gdb) fault_info
The report decodes fault status and the available stacked exception context, helping you understand why the firmware crashed. Use your firmware’s actual handler symbol, and inspect the stopped state before resetting the board. Interpretation and limitations are covered in the fault analysis guide.
Common startup problems
| Symptom | First checks |
|---|---|
| GDB cannot import the toolkit or a dependency | Check GDB’s embedded Python version and import path. A working import in your shell’s Python does not guarantee one in GDB. |
| OpenOCD or pyOCD cannot start | Check executable paths, board configuration, USB permissions, and whether another process is already using the probe. |
| The dashboard cannot connect | Wait for server initialization and check the configured WebSocket host and port. |
| Automatic SVD loading fails | Check network access and device support, or use svd read with a matching local SVD file. |
| A command cannot read memory | Check the target connection, selected core, halt state, and debug-access restrictions. |
For detailed fixes, use the first-session troubleshooting guide.
Go further
Once your first session works, try an LLM-assisted audit to connect software analysis with runtime inspection, or explore the security audit commands and RTOS inspection manually. For automation, advanced configuration, supported targets, and the complete command reference, continue with the full Read the Docs guide.