STM32 GDB Debugger

Clears the session journal (keeps the run-id).

Closes a named debug session, tearing down its GDB client and server.

Captures expressions, performs one debug action, captures them again, and reports changes.

Freezes peripherals (IWDG, WWDG, RTC, timers) while the core is halted via the DBGMCU freeze registers, so the watchdog cannot reset the target out from under the debugger. Family is taken from the debug profile MCU if omitted.

Resumes execution of the target device until the next breakpoint. Safe to call when the target is already running (reports already_running instead of erroring), so 'make sure it is running' is expressible.

One-call repro step: set an optional conditional/temporary breakpoint at a location, run, and return the stop event PLUS the decoded backtrace and innermost-frame locals. Collapses set_breakpoint + run + read frame/vars into a single round-trip.

Reads and decodes a peripheral register with SVD bitfield names and enumerated values.

Deletes a breakpoint by its ID.

Read the loaded AcceptanceSpec or the last verdict. what=summary (name + check counts), checks (full check list), or last_result (the most recent run_acceptance report).

Read the BoardDescription imported by import_netlist. what=summary (MCU + peripherals + counts), pins (full MCU pin map), nets, power (power/ground nets), or peripherals (distinct peripherals in use).

Read the synthesized FrameworkPlan. what=summary (mcu + clocks + peripherals), clocks, gpio (per-pin config), peripherals (init blocks), init_order, or unresolved (the TODO holes that need target data or a design decision). Run design_framework first.

Reports the attached programmable USB hub: identity, channel list, per-port power and USB2 data-line state, and per-port voltage/current on models with an ADC. Read-only. Returns hub_unavailable when the [hub] extra is not installed or no hub is attached.

Synthesize a deterministic FrameworkPlan (Pillar D) from the session's imported board: which clocks to enable, how each pin must be muxed, and which peripheral init blocks to emit, in dependency order. Supply per-peripheral HAL .Init parameters via design={'USART1': {'baud': 115200, ...}} and optional AF numbers via af_map. Mandatory .Init members are auto-filled with HAL-standard defaults (a complete, valid init struct, not a half-initialized one) and a few are derived from the netlist (UART flow control from RTS/CTS pins, SPI NSS from an NSS pin); each field is tagged explicit/derived/defaul…

Lists physical ST-Link, J-Link, and CMSIS-DAP probes currently connected over USB. Preserves serial numbers so multiple identical probes are never silently collapsed.

Detects whether FreeRTOS symbols are available in the current GDB session.

Reads and decodes Cortex-M fault registers into likely fault causes.

Disassembles N instructions at a location (default $pc).

Works out which hub channel each debug probe is plugged into, by disconnecting one channel's USB data lines at a time and seeing which probe disappears from detect_probe. Data lines, not power, so a neighbouring board mid-experiment is not rebooted. SLOW and opt-in: it runs detect_probe once per channel plus a baseline, and on Windows each of those walks the whole USB device tree (~8.5 s). Refuses while any GDB server is alive unless force=true. With apply=true the result is written into the active debug profile.

Writes a single self-contained JSON report (journal + metrics + profile, optionally a state snapshot and a coredump) tied to the run-id, so a bug session is fully reproducible and shareable from one artifact.

One-call bring-up: flash an ELF (loads symbols), reset-halt, set a temporary breakpoint at an entry point (default 'main'), run to it, and return the decoded stop context. With hub_channel (or usb_location) and no session running, it starts one pinned to that probe first -- so 'flash the firmware on channel 4' is this single call, on a bench with several probes, without disconnecting any of the others.

Erases a flash range on the target (OpenOCD 'flash erase_address pad'), rounding out to the driver's erase-sector boundaries. The recovery tool for a board that will not boot: clearing a corrupt OTA journal, a stale boot descriptor, or a half-written image. Requires an explicit address AND length — there is deliberately no mass-erase default.

Flashes a compiled firmware binary to the target. Accepts GCC .elf or Keil .axf. By default it then resets and RUNS the firmware (Keil-style 'Load + Run'). Pass reset_run=false to flash only (e.g. to set breakpoints before the firmware starts). Refuses (elf_layout_unsupported) an image GDB would flash incompletely, such as a Keil ARMCC5 AXF whose RW initializer lies outside its segment; flash its fromelf BIN instead.

Returns the stored board/session defaults.

Polls GDB for any asynchronous events (like hitting a breakpoint) or stdout messages.

Returns recent logs captured from the active GDB server process.

Returns captured log lines for a channel (rtt/swo/uart).

Returns this session's record by view: 'journal' (every tool call with args/ok/summary/duration; supports limit), 'timeline' (compact human-readable replay), or 'metrics' (per-tool call counts, success/failure, durations).

Returns the current named GDB operation timeouts (connect, reset, memory, registers, source, run, download).

Returns the append-only audit log of every memory-write decision (written, blocked, or simulated).

Interrupts/halts the target device execution.

Starts (or stops) a local, read-only web dashboard for the hub: every port's power and data-line state, live voltage/current with a few minutes of history, which debug session sits on which channel (and whether its GDB server is live), and a timeline of hub actions. Serves on 127.0.0.1 only and returns the URL. When the shared hub daemon owns the hub (the default with several MCP servers on a rack) this returns the daemon's always-on page, which also lists every connected server. In local mode the page runs inside this server and, while it runs, no OTHER process can open the hub; state=off sto…

Parse a schematic netlist (KiCad .net today) into a machine-readable BoardDescription: the MCU part/family/line, a per-pin map (package pin -> port pin -> net -> inferred peripheral function), and the power/ground nets. This is the input contract for automated framework design. Pass 'path' or 'text'. The result is stored on the session; read views with describe_board.

Translate a controlled-vocabulary product spec (human/product terms) into the per-peripheral design params design_framework consumes, and cross-check it against the imported netlist. This is the upstream guard the pipeline lacked: instead of hand-writing HAL macros, supply intent -- UART framing '8N1', direction 'txrx', flow_control 'rtscts'; SPI role 'master', spi_mode 0..3, data_size, bit_order; I2C speed 'fast', addressing '7bit'; ADC resolution 12, conversion 'continuous'; a timer update_hz; plus dma / interrupt / priority opt-ins -- and the machine expands it deterministically (8E1 -> UAR…

Discovers firmware project artifacts such as ELF, map, linker script, SVD, and STM32CubeMX .ioc metadata.

Lists breakpoints with their HIT COUNTS. A hit_count of 0 means the code path was never reached — so a run_and_wait timeout means the precondition (a flag/state) to get there was not satisfied. Use this instead of retrying.

Lists functions in the loaded symbols, optionally filtered by a regex.

Lists all debug target sessions (the 'default' one plus any named) with their liveness and port. To debug MULTIPLE boards at once, pass a 'session' argument (any string) to any tool — e.g. start_debug_session(session='rackA', ...) — and each gets fully isolated state.

Lists source lines around a location (function, 'file.c:42', or '*0xADDR').

Lists global/static variables in the loaded symbols, optionally filtered by a regex.

Load a machine-checked AcceptanceSpec (product-spec → deterministic checks) from an inline 'spec' object or a JSON 'path'. Checks: memory_u32 (any memory-mapped register), variable (C global), core_register, no_fault, stopped_at (PC in a symbol). Stored on the session; evaluate with run_acceptance.

Loads a previously captured core file for offline analysis.

Loads a YAML debug config and applies compatible fields to the active debug profile. Fields the file defines REPLACE the stored ones, so re-loading a rack config after re-cabling never accumulates the previous rig's hub.map channels; fields it omits are left alone.

Register a verified device-fact pack (Pillar F) so the deterministic solvers cover a new STM32 family: its DMA request routing, irregular NVIC vectors, clock PLL profile, and timer bus/width. Facts are DATA, never guessed -- STM32F4/L4 ship built-in; add a family by supplying a validated pack (schema 'stm32-device-pack/v1') via path= (a JSON file) or inline pack=. Call with no arguments to report current coverage. Honest by design: a malformed pack is rejected with the list of problems and never half-loaded; shadowing a built-in family needs allow_override=true.

Loads an SVD file for peripheral parsing.

Loads symbols from an ELF/AXF into the current GDB session WITHOUT flashing. Symbols are per-session, so after a fresh connect or recover_session you need this (or flash_firmware) before symbol breakpoints resolve. Falls back to the debug profile's elf_path if elf_path is omitted.

Shows the type/layout of an expression or type name (GDB ptype).

Identifies THIS running stm32-gdb-mcp server: release version, git commit, the package directory the code was imported from (plus the install root the git probe used), whether compact mode is hiding tools, and how many tools this build advertises versus how many exist. Needs NO debug session, NO probe and NO target — call it the moment a tool you expect is missing or behaves like an older build, instead of guessing which checkout the client actually launched.

Samples a hub port's voltage and current over a window and returns the series plus min/max/mean per channel. Read-only, and costs no target traffic -- so it works while the core is running, which is the point: it is the only instrument here that sees actual power draw, and an MCU that entered Stop and one that only thinks it did look identical over SWD. Requires a model with an ADC.

Removes power from a hub port and restores it: a true cold boot of whatever is on that port, and the only in-band way to clear a wedged probe USB endpoint. On models with an ADC the voltage during the off window is measured and reported, so a rail that never actually collapsed (bulk capacitance, a second supply, a coin cell) is flagged instead of being reported as a cold boot that did not happen. Requires confirm=true while the guard is in confirm mode or a session has a live GDB server on the port.

Reads the call stack as a decoded list of frames {level, func, file, line, addr} plus a one-line summary. Set include_raw=true to also get the raw GDB output.

Reads CPU core registers as a decoded {name: hex} map plus a one-line summary of PC/LR/SP. Set include_raw=true to also get the raw GDB output.

Enables (if needed) and reads the DWT cycle counter (DWT_CYCCNT) for on-chip timing measurements.

Reads Cortex-M SCB fault status registers (CFSR, HFSR, DFSR, MMFAR, BFAR, AFSR).

Returns a decoded {name: value} map of locals and arguments for a stack frame, plus a count summary. Set include_raw=true for the raw GDB output.

Reads FreeRTOS state by 'what': 'current_task' (pxCurrentTCB), 'tasks' (ready list: names/priorities/TCB/stack), 'task_lists' (ready/delayed/suspended/deleted), 'queue' or 'mutex' (needs handle = a Queue_t expression), or 'heap' (heap_4/5 usage).

Reads a block of memory from the target. Returns the raw bytes in memory order, plus value_le -- the same bytes as one little-endian value -- for a 1/2/4/8-byte read. Use value_le for a peripheral register: the raw string arrives least-significant-byte first, so reversing it by hand is where bit positions get misread.

Reads a peripheral register using its name from the loaded SVD.

Reads memory with an explicit element width and count.

Reads the value of a C variable currently in scope.

Reconstructs the full crash site after a HardFault: decodes fault registers, unwinds the auto-stacked exception frame from MSP/PSP via EXC_RETURN to recover the true faulting PC, and resolves it to source file:line. Run this when halted in a fault handler.

Recovers a dropped or wedged session: cleanly tears down the GDB client and server, then restarts the server (with retry/backoff for a busy probe) using the last start_debug_session arguments and reconnects. Use after a probe_unavailable or connection_lost error. When a programmable USB hub is configured (debug_profile hub.channel), a retry that cannot fix the probe escalates to toggling its USB data lines and then power-cycling the port -- the only in-band cure for a wedged endpoint. Any hub action taken is reported in recovery_steps.

Render the synthesized FrameworkPlan to a HAL C init skeleton (bsp_init.c + bsp_init.h). Every derived fact (clock enables, GPIO modes, mapped .Init fields) is concrete; every unresolved value is a clearly marked TODO — nothing is fabricated. Returns the files, their content, and a todo_count. Run design_framework first.

Files a GitHub issue about an MCP problem from THIS session — auto-bundling the session journal, metrics, and MCP version into a structured report (via the gh CLI). Call this when a tool misbehaves or confuses you. Deduplicated per session so retries don't spam. Defaults to the stm32-gdb-mcp repo.

Resets the target device. Can optionally halt immediately after reset. strategy="cold" removes target power through a configured programmable USB hub before resetting, which is the only strategy that produces a true power-on reset (RCC_CSR POR flag, cleared .noinit, drained RAM); it fails rather than silently doing a warm reset when no hub channel is mapped. It needs no confirm argument -- asking for a cold reset by name IS the confirmation the hub guard wants -- and it stops the GDB session before the cut, then re-establishes it.

Maps an address or expression (e.g. '$pc', '0x08001234') to its source file:line and nearest symbol, returning {resolved, symbol, offset, section, file, line}. resolved=false means GDB found no symbol there.

Evaluate the loaded AcceptanceSpec against live silicon state and return a deterministic pass/fail/error verdict per check (the closed-loop judge). An unreadable target is reported as 'error', never a silent pass. A failing/errored check derived by synthesize_acceptance carries provenance.source — the init function + line that should satisfy it — so fixes are precision-guided. Run load_acceptance first; halt the target at the state you want to assert.

Run one bounded loop iteration: (optional build) → (optional flash+run-to) → evaluate the AcceptanceSpec against live silicon, then record the verdict and return a decision (converged / should_continue / exhausted / stalled) plus the checks to fix. A build or run-to failure is recorded as a phase_error, not a crash. Refuses to run a terminal loop unless force=true. start_acceptance_loop first.

Resumes the target and waits, returning a structured stop event (reason, symbolized frame, breakpoint id, signal) or a timeout. Use this instead of continue_execution + polling to close the debug loop.

Runs the target freely for a wall-clock duration, halts it, and returns one structured report with final frame/context and optional expression captures. Useful for counters, telemetry buffers, polling loops, and timing-sensitive bus diagnostics without breakpoint perturbation.

Spec-to-silicon capstone (Pillar G): run the whole deterministic DESIGN half in one call. Chains the existing, individually verified tools in dependency order -- import_netlist? -> import_spec? -> design_framework -> solve_clock_tree? -> solve_timer? -> render_framework -> synthesize_acceptance -- turning a netlist plus a product spec into a flashable HAL skeleton and a machine-checked acceptance spec, then hands off to the build/verify loop. Optional stages (marked ?) run only when their input is present. Honest by construction: it GUESSES NOTHING -- it sequences verified tools and aggregates…

Replays a declarative scenario — a list of {tool, args} steps — deterministically and returns a per-step pass/fail report. Provide inline 'steps' or a 'path' to a JSON scenario file. The minimal-step way to re-run a complex bug repro.

Runs until a given location is reached (function, 'file.c:42', or '*0xADDR').

Statistical PC profiler: enables DWT and samples the program counter while the core RUNS (non-intrusive, over SWD — no SWO pin or firmware change). Returns a symbolized hot-spot histogram (top functions by %), not raw hex — the fast way to find where firmware spends time or what loop it is stuck in. A high 'unsampleable' count means the core is halted/asleep; a high 'zero_samples' count means nothing was profiled at all. Leave enable=true: GDB cannot write the enable bit while the core runs, so this halts briefly to set it and resumes, and only when it is not already set. Note some links canno…

Saves a YAML debug config file.

Selects a stack frame by level (0 = innermost) for subsequent variable reads.

Validates the link right after connecting: reads CPUID and DBGMCU IDCODE and checks byte order, that a real Cortex-M is present, and that the device matches the expected family (from the profile MCU or the 'expected_family' arg). Run this first to catch endianness/config faults before debugging. Halts the core first (identity reads are unreliable while running); pass halt=false to skip.

Sets the SWD/JTAG adapter clock (kHz) at runtime. The default ST-Link speed is only ~480 kHz; raising it (e.g. 4000) speeds up flashing and memory reads ~8x. Lower it if reads/flash become unreliable.

Sets a breakpoint at a function, line, or address. Supports an optional condition (break only when true), temporary (auto-delete on first hit), and ignore_count (skip N hits) so the AI can set a hypothesis trap and resume.

Stores board/session defaults such as MCU, probe, GDB server args, ELF path, and SVD path. Top-level fields you omit keep their value, but a nested block you pass (hub, rtt, uart, swo, reset, hil) REPLACES the stored one whole -- pass merge=true to deep-merge into it instead.

Connects or disconnects a hub port's USB2 data lines, leaving power untouched. This un-enumerates a probe without rebooting the board it is attached to. With exclusive=true every other port's data line is disconnected, so exactly one probe stays visible -- which keeps start_debug_session's single-probe auto-select valid on a multi-board rack.

Switches a hub port's power on or off. Powering off removes VBUS from whatever is on that port, so it cold-boots the board and un-enumerates its probe. Requires confirm=true while the guard is in confirm mode (the default) or a session has a live GDB server on the port.

Overrides one or more named timeouts (positive seconds). Useful for a slow or flaky probe. Recorded in the journal so replays are deterministic.

Sets a hardware watchpoint on a memory address or variable.

Configures memory-write guardrails: mode ('enforce' or 'dry_run'), and optional allow/protected regions. Protected regions (option bytes, IWDG, WWDG) block writes by default; dry_run simulates every write.

One-call SWO/ITM printf setup. Configures the target's TPIU+ITM from the debugger (no firmware ITM-init needed) for the given core clock (hclk_hz) and SWO baud, and returns the OpenOCD capture commands + the firmware printf retarget snippet. Then capture with logging(action=start, channel='swo', file=<output>). Requires the SWO pin (e.g. PB3) wired to the probe.

Evaluates sizeof(expr) against the loaded symbols.

Synthesize a concrete SystemClock_Config() for the session's FrameworkPlan (Pillar D Tier 3) - the last hand-written gap in generated init code. Given a clock source (HSE + crystal Hz, or HSI) and a target SYSCLK, it computes the exact PLL dividers (M/N/P or R, Q for 48 MHz USB), AHB/APB bus prescalers, and flash wait-states via pure datasheet math, then stores the result so the next render_framework emits real clock code instead of a TODO stub. Deterministic and honest: an unmodelled device or an infeasible target is surfaced, never guessed. Built-in profiles: STM32F401/F407/F411 and mainstre…

Solve a timer's Prescaler/Period (PSC/ARR) for a target update frequency (Pillar D Tier 3). Turns intent ('TIM3 at 1 kHz') into concrete register values using the timer input clock (TIMxCLK) derived from the solved clock tree. Record a target via design_framework(design={'TIM3': {'update_hz': 1000}}) then run solve_clock_tree first, or pass timer_clock_hz directly for a what-if. Deterministic and honest: an exact target yields zero-error PSC/ARR, an inexact one yields the closest pair plus the achieved frequency and ppm error, and an unrepresentable target or an unknown timer bus is surfaced, …

Start a bounded spec-to-silicon acceptance loop (Pillar C) for the loaded AcceptanceSpec. Each run_acceptance_iteration does one build → flash → run-to-state → run_acceptance pass; the loop stops on convergence, on max_iterations, or on a stall (same checks failing repeatedly). Omit build/flash to run evaluate-only iterations (you flash manually). Load a spec first.

Starts the specified GDB Server (openocd, stlink, jlink) and connects the GDB Client to it. openocd REQUIRES server_args naming the probe and target, e.g. ['-f','interface/stlink.cfg','-f','target/stm32l4x.cfg'] — without them OpenOCD cannot find a config or adapter. Omitted values come from the active debug profile.

Starts background log capture on a channel: 'rtt' (SEGGER RTT, default cmd JLinkRTTClient), 'swo' (ITM printf — run setup_swo then pass file=<output>; or command=<external decoder>), or 'uart' (serial, port required). One tool for all three channels.

Single-steps the target: kind='over' (over the line), 'into' (into calls), 'out' (run until the function returns), or 'instruction' (one machine instruction; set over=true to step over a call).

Stops the GDB client/server, variable tracking, and all active RTT/SWO/UART readers.

Stops background log capture on a channel (rtt/swo/uart).

Returns the correct OpenOCD server_args for an MCU family + probe (e.g. STM32L431 + stlink -> ['-f','interface/stlink.cfg','-f','target/stm32l4x.cfg']) and validates the config files exist in OpenOCD's bundled scripts dir. Call this to get start_debug_session args — do NOT search the disk for .cfg files.

Auto-derive a machine-checked AcceptanceSpec from the synthesized FrameworkPlan (Pillar D Tier 3) and load it as the session's acceptance judge — welding design synthesis to the acceptance loop. Always emits a no_fault check (init must not HardFault); adds a memory_u32 bits_set check per clock the plan enables (RCC enable bit), a memory_u32 bits_set check per interrupt the plan enables (arch-standard NVIC ISER bit, from the resolved IRQ number), and a masked memory_u32 eq check per configured pin (GPIO MODER = AF/analog; F1's CRL/CRH is skipped). Register/IRQ/port placements come from the sess…

Returns descriptions and complete schemas for full-surface tools, including tools hidden in compact mode.

Background variable tracking: action='start' (needs variable + interval_ms), 'stop', or 'get' (returns the sampled data for trend/leak analysis).

Validate the imported BoardDescription: detect a package pin wired to multiple nets (short), a peripheral signal routed to multiple pins, a port pin driven by multiple nets, and missing power/ground/debug/reset nets. With a pin-capability DB (db_path or the STM32_GDB_MCP_PIN_DB env) it also checks alternate-function legality; unknown pins degrade to 'unverified', never a false conflict. Run import_netlist first.

Validates a YAML debug config object without saving it.

Verifies that target flash matches an ELF (GDB compare-sections). Compares read-only sections, which is what lives in flash; writable sections hold the ELF's initial RAM values and always differ once the firmware has run, so including them would fail every healthy target. Pass include_writable=true only right after a load, before the target has executed.

Waits for the next stop event WITHOUT resuming the target, returning a structured stop event or a timeout.

Writes a value to a specific memory address.

Writes memory with an explicit C integer width.