BKPT Debug

Debug and trace STM32 firmware in VS Code over a plain ST-LINK or J-Link. Step through code, catch and explain faults, see where the CPU spends its time, inspect ETM/SWV history, and watch variables live. No vendor GDB server, CubeProgrammer, or OpenOCD dependency.

• Debugger: start, attach, step, breakpoints, call stack, registers, memory, all around your code in one dockable layout.
• Fault Analyzer: HardFault, BusFault, MemManage, UsageFault and SecureFault caught at the exception itself, before any handler runs. Every set fault-status bit decoded in plain language, escalations called out, the stacked frame recovered, and the faulting line one click away. No fault handler needed in your firmware.
• Target scan: a read-only CoreSight walk of the connected chip: every debug component, the DWT comparator budget, ETM and the trace sink. Anything the silicon lacks is disabled with the reason, never silently hidden.
• ETM history: the on-chip trace buffer records instruction trace in a rolling loop while the target runs; each breakpoint, pause or fault (steps optional) drains it into a flame graph, a history cursor through your code, and historical disassembly. Exact execution history, not samples.
• PC sampling: live CPU load, hottest functions and per-line heat in the editor while the target runs. On-chip DWT sampling over SWO when the core has it, polling over the probe otherwise; zero overhead either way.
• DWT control: sample interval, exception enter/exit/return trace, the event counters and ITM timestamps, each choice labelled with its rate and SWO share, and a load meter that warns before the pin overflows.
• ITM console: what the firmware prints on ITM stimulus ports, live and timestamped, all 32 ports selectable.
• Live watch: pick variables from your ELF, no recorder library, no code changes. Watch them as values or graphs, running, halted or stepping: polled up to 1 kHz, or on a DWT comparator so the chip emits the value on every write with zero probe traffic.
• Trace analysis: inspect debug-session trace in synchronized timeline, event, graph, task-detail, health, ETM flame-graph, and disassembly views.

Made by BKPT Labs.

Getting started

1. Connect your board through an ST-LINK or J-Link probe. Program it with your usual tool first: BKPT Debug never flashes, and it tells you if the firmware on the target does not match your ELF.
2. Click BKPT Debug in the activity bar and choose Open Debug Layout. Pick your ELF in the top strip.
3. Press F5. The target resets, runs to main and halts with your code center stage.

From there: F5 continue, F6 pause, F10 / F11 / Shift+F11 step, Shift+F5 stop. Click a line number to set a breakpoint. Everything else is a tile in the layout: call stack with locals, breakpoints, registers, memory, PC sampling, Fault Analyzer, and the trace views. Drag tiles to arrange them; the layout is remembered per workspace.

Firmware already running? Attach to Running Target joins it without a reset.

What you need

• ST-LINK or J-Link: nothing to install, both are driven directly. For J-Link, set your MCU's SEGGER device name in Settings.
• arm-none-eabi-gdb: the Arm GNU toolchain or STM32CubeCLT on your machine. Found automatically; the setting is there if you keep it somewhere unusual. Tracing and live watch do not need it.

License

Free-mode limits come from the bundled trace backend and apply consistently to debug-session captures. In the BKPT Debug activity sidebar, use Activate License Key… for a retail Solo or Team purchase. Use Install License File… for a signed offline/OEM .license file; the backend verifies it before copying it into its canonical per-user state directory. The CLI and desktop application read the same state.

The sidebar reports the effective status and tier. Retail licenses show the account email and updates entitlement; OEM licenses show the partner, signed expiry, and grace date. Free mode shows the limits reported by the backend. The adjacent Set Arm GDB Path… action opens VS Code Settings directly at bkptDebug.gdbPath for machines where the GNU Arm toolchain is not found automatically.

Fault Analyzer

Run the firmware, hit a fault, read what happened. The debugger catches HardFault, BusFault, MemManage, UsageFault and friends at the exception itself, before any handler runs, then shows:

• the root cause in one line ("HardFault: escalated UsageFault, undefined instruction"), including escalations;
• every set bit of the fault status registers, with what it means, and the fault address when the core says it is valid;
• the stack in use, the FPU frame state, and the recovered pre-exception registers;
• the faulting pc and lr resolved to function and line: click to open the source.

Pick which fault classes to catch on the tile. Analyze now explains a fault on any halted target after the fact.

PC sampling

Turn it on and the debugger samples the program counter over the probe while the target runs. You get live CPU load, the hottest functions (interrupt handlers badged, click a row to jump), per-line sample counts in the editor gutter (amber while a line is executing), and a timeline of what the CPU was doing, one lane per function. Statistical, with zero overhead on the target.

Hardware trace (SWV)

The Hardware Trace tile has one switch. Sampling is the default: a rough profile with nothing to set up. The debugger scans the target and picks the source for you: on-chip PC sampling over the SWO pin when the core has the DWT and an ITM, polling over the probe otherwise. The tile always says which one is running and how fast, in one line ("On-chip, every 16384 cycles (~10.4 kHz at 170 MHz)" or "Polling over ST-LINK, ~3.1 kHz").

On-chip trace (advanced) opens everything the core has, the way Eclipse's SWV panel does: PC sampling with its interval (64 to 16384 cycles, each entry labelled with the rate it yields and its share of the SWO pin), exception trace (every interrupt's enter, exit and return), the DWT event counters (CPI, exception, sleep, LSU, fold), data watches on the DWT comparators (pick a slot in a Symbols row: the chip emits the value on every write, no probe traffic), ITM stimulus ports and timestamps. A control the core lacks is disabled with the reason, not hidden, and a load line turns red before the pin overflows.

The ITM Console tile shows what the firmware prints on ITM stimulus ports (read-only), the Exceptions tile the traced exception counts. The selected sources are applied when the debugger attaches and restored when the session ends.

Watch variables live

The Symbols tile works on any firmware, no recorder library, no code changes. Pick variables from your ELF, and each one shows its live value in the row or graphs in the trace view, updating while the target runs and on every step.

The Events table is paged and virtualized for large traces. Clicking an event pins the shared time cursor, so Timeline and Traces move to the same point without duplicating the live wire stream in memory.