Embedded Debugging with the Black Magic Probe

The “Black Magic Probe” is a combined hardware & software project, designed by 1BitSquared in collaboration with Black Sphere Technologies. At the hardware level, it implements JTAG and SWD interfaces for ARM Cortex A-series and M-series microcontrollers. At the software level, it provides a “gdbserver” implementation and Flash programmer support for ranges of microcontrollers of various brands. The firmware of the Black Magic Probe is an open source project; the schematic of the hardware version 2.1 is available as well.

The firmware for the Black Magic Probe is maintained on GitHub. The debug probe itself is available from 1BitSquared Germany, 1BitSquared USA, and several distributors (Adafruit, Elektor).

Back to page

The distinguishing feature of the Black Magic Probe is that it has native support for the GDB “Remote Serial Protocol”. In other words, it embeds the “gdbserver” stub. This means that you can directly connect to the debug probe with GDB, any IDE or front-end that uses GDB in the background, or any program that supports the Remote Serial Protocol. The Black Magic Probe requires neither drivers nor any middle-ware.

Debugging with the Black Magic Probe

To support the Black Magic Probe, we wrote a book on how to use the debug probe, with troubleshooting tips, plus several more advanced debugging techniques. This book is available as a free download in PDF format, from this site (see the Downloads & Resources section), or from its GitHub project. If you prefer a printed version of the book, you can buy it from from Lulu. Note, however, that the printed book may lag behind the PDF version —which is regularly updated to cover new releases of the firmware and the hardware.

Back to page

This book is copyright 2020-2023, CompuPhase, and licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License ().

Together with the book, we developed a number of utilities to use with the Black Magic Probe. There is a front-end for GDB that is tailored to the Black Magic Probe. On start-up, it scans for available debug probes, and automatically handles the querying & set-up for the selected microcontroller in the background. Plus, this front-end supports semihosting, serial terminal viewer and SWO tracing —features that are typically needed for embedded debugging (but that general-purpose front-ends often lack).

Back to page

Black Magic Debugger

Back to page

Black Magic SWO Trace Capture

Back to page

Black Magic Flash Programmer

Back to page

Black Magic Profiler

Other utilities handle firmware downloading (with options for serialization and code protection), profiling for performance optimization, or diagnosing your set-up if the Black Magic Probe does not work as expected.

The book devotes a few chapters on run-time tracing, as a non-intrusive alternative to “stop-&-stare” debugging. Specifically, it proposes the use of the “Common Trace Format” (CTF) for efficient run-time tracing (efficient in the terms of low memory/resource requirements, as well as low overhead). Correspondingly, we also developed a few utilities for supporting CTF in embedded systems, and for monitoring trace messages.

All utilities are available as ready-to-run binaries for Windows and Linux, in addition to the full source code (under the Apache v.2 open source license). Both can be found on the same GitHub project as for the book.

Book information

Software summary

               

	bmdebug	A front-end for GDB that has specific support for the Black Magic Probe and the ctxLink probe. It has several features that are particularly useful for debugging embedded targets.
	bmflash	A utility to download firmware into Flash memory of a microcontroller, with support for serialization, Tcl scripting, and (for some microcontrollers) code protection. This is a stand-alone tool, that does not require GDB.
	bmprofile	A sampling profiler for the ARM Cortex architecture, enabling you to check where the firmware spends its cycles. Since the code is sampled using the CoreSight component inside the ARM Cortex microcontrollers, the sampling does not affect the code execution.
	bmserial	A serial monitor/terminal that allows you to receive and transmit text or data over the serial line. The Black Magic Probe has a TTL UART (in addition to its GDB interface) for talking to devices that use the UART for console I/O. Furthermore, the Black Magic Probe redirects the RTT protocol (Real-Time Transfer) to serial, and it can redirect SWO tracing and semihosting to serial as well.
	bmtrace	A utility to monitor SWO trace messages, with support for multiple channels, filtering on keywords, and the Common Trace Format. SWO tracing must be configured in the microcontroller (and in the debug probe) before it is operational, and the utility handles this for various families of microcontrollers.
	bmscan	A command-line utility to locate which COM port (Windows) or which ttyACM device is assigned to the Black Magic Probe. It can locate a ctxLink probe configure for WiFi by doing a network scan.
	elf‑postlink	A command-line utility to set the checksum in the vector table. Microcontrollers in the LPC series (by NXP) require this checksum. Firmware programmers typically set it during downloading the code to the microcontroller, but there are situations where it is convenient when the correct value is already set in the ELF file.
	tracegen	A command-line utility to generate C source files from a TSDL specification for the Common Trace Format. The Common Trace Format, its use and its advantages, are explained in the book.

Downloads & Resources

Embedded Debugging with the Black Magic Probe (PDF)
Embedded Debugging with the Black Magic Probe (paperback)
Utilities for Microsoft Windows, version 1.3.6918
Utilities for Linux, version 1.3.6918

Further information

Black Magic Probe project on GitHub

https://github.com/blackmagic-debug/blackmagic

“Embedded Debugging with the Black Magic Probe” project on GitHub

https://github.com/compuphase/Black-Magic-Probe-Book