DOCS/BKPT DEBUG
BKPT DEBUG · VS CODE
BKPT Debug
BKPT Debug is a VS Code extension for STM32 firmware over a plain ST-LINK or J-Link probe. One panel, the Debug Layout, holds everything: step through your code, catch and explain faults, see where the CPU spends its time, watch variables live, and record RTOS traces. No vendor GDB server, no SEGGER software, no CubeProgrammer: the probe is driven directly by BKPT's own tools, bundled with the extension.
This guide is written in the order you meet things:
- Getting started: from a programmed board to your code halted at
main, the keys, and every setting. - Debugging: run control, breakpoints, the call stack, registers and memory, and how the layout's tiles work.
- PC sampling: live CPU load, hot functions and per-line heat while the target runs, with no instrumentation.
- Live watch: variables from your ELF as values and graphs, running, halted or stepping.
- Fault Analyzer: a fault stops the target at the exception and the debugger tells you why.
- Hardware trace: the SWV sources (on-chip PC sampling, exception trace, the ITM console) inside a debug session.
- Recording a trace: RTOS and event traces with the ViewAlyzer views inside VS Code.
- AI assistants: the bundled MCP server.
One panel, tiled
Everything is a tile in the Debug Layout. The default arrangement is the call stack and breakpoints on the left, your code in the centre, registers and PC sampling on the right. Drag a tile by its title onto the edge of another to split, onto its header to tab, or to the strip to move it; the arrangement is remembered per workspace. The Views menu in the strip shows or hides tiles:
| TILE | WHAT IT SHOWS | NEEDS |
|---|---|---|
| Call Stack | Frames with their locals; click a frame to select it | a session, halted |
| Breakpoints | Every breakpoint with the debugger's verdict on it | |
| Code | The halted line, the selected frame, per-line sample counts, click-to-toggle breakpoints; files as tabs in tiling editor groups | |
| Registers | Core registers, changed ones marked, the FPU bank folded below | a session, halted |
| PC Sampling | Live CPU load, the hottest functions, the source line | PC sampling on |
| Fault Analyzer | The caught fault explained, register by register | a session |
| Memory | 256 bytes at an address expression, hex and ASCII, editable while halted | a session, halted |
| Hardware Trace | The Profiling Source switch and the on-chip trace controls | a session |
| ITM Console | Text the firmware prints on ITM stimulus ports | SWV over SWO |
| Exceptions | Traced exception counts | SWV over SWO |
| Record, Symbols | The trace recorder's form and the ELF symbol picker | |
| Traces, Timeline, Events, CPU, Task Details, Health | The ViewAlyzer views, on a recording or on the live streams of a session | a recording or a session |
What you need
- An ST-LINK or J-Link probe. Nothing to install for either; 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; a setting is there for unusual places. Tracing and live watch work without it.
- The board programmed with your firmware, by your usual tool. BKPT Debug never flashes, and tells you when the firmware on the target does not match your ELF.
Not sure what is missing? Run BKPT Debug: Check Setup Health from the Command Palette.
Free version
The bundled engine runs unactivated, which caps capture length and the number of user traces shown, with a short cooldown between captures; the extension always shows the exact limits in effect. Viewing recordings and debugging are unlimited. Already own ViewAlyzer? Run BKPT Debug: Use My Licensed ViewAlyzer and your limits apply.