Black Magic Probe

Skip to main content (skip navigation menu)






Embedded Debugging with the Black Magic Probe

 

The “Black Magic Probe” is a combined hardware & software project. At the hardware level, it implements JTAG and SWD interfaces for ARM Cortex A-series and M-series micro-controllers. At the software level, it provides a “gdbserver” implementation and Flash programmer support for ranges of micro-controllers of various brands. Both the hardware & software components of the Black Magic Probe are open source projects, designed by 1BitSquared in collaboration with Black Sphere Technologies.

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).

Black Magic Probe

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. Like the Black Magic Probe project itself, this book is open source (more accurately: licensed under the “BY-NC-SA” license). It can be downloaded in PDF and ODF formats 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.

Book cover

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

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 micro-controller 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).

Black Magic Debugger

Other utilities handle firmware downloading (with options for serialization and code protection), 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.

Downloads & Resources

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

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