Black Magic Debug: The Plug&Play MCU Debugger

Black Magic Debug Project Goals

The goal of this project is the creation of an easy to use. Mostly plug and play, JTAG/SWD debugger for embedded microcontrollers. Focusing on professional embedded software developers that prefer retaining control over their build systems and testing environments instead of relying on highly abstracted vendor tools that give the impression of simplicity at the cost of transparency.

Project News

What is Black Magic Debug

In most cases Black Magic Debug takes the form of a firmware for the Black Magic Probe hardware, and implements a GNU DeBugger (GDB) server.

The Black Magic GDB server features:

  • Automatic target detection

  • No need for target specific configuration scripts

  • All protocol and target specific control is done through GDB monitor commands

  • No “software in the middle” like OpenOCD required

  • Easily scriptable thanks to the GDB scripting capabilities

  • Interface to the host computer is a standard USB CDC ACM device (virtual serial port), which does not require special drivers on Linux or OS X.

  • Targets ARM Cortex-M and Cortex-A based microcontrollers

  • Provides full debugging functionality, including: watchpoints, flash memory breakpoints, memory and register examination, flash memory programming, etc.

  • [Semihosting / Host IO support] as well as [Serial Wire Debug TRACESWO support].

  • Implements USB DFU class for easy firmware upgrade as updates become available.

  • Works with Windows, Linux and Mac environments.

All you need is to install the GNU cross compilation toolchain installed, containing GCC and GDB for your microcontroller installed, the microcontroller is supported by BMD, plug in the Black Magic Probe hardware running the Black Magic Debug firmware into your computer, and instruct your GDB to use the BMP as your remote target using the target extended_remote *serial_port* command and you are off to the races.

If you are an embedded development beginner Black Magic Probe is also a great choice for you. But expect more of a Unix command line experience than a Windows klickybunti GUI.

If there is anything unclear or hard to understand let us know. Our goal is to make the documentation on this website comprehensive enough that it is all you need to get started with microcontroller development and debugging using the Black Magic Probe.

Supported Targets

Quick Demo

Here is a quick example of a GDB session using the Black Magic Probe.

The session goes through the following steps:

  • Connecting to BMP -> target extended remote <serial port>

  • Scanning for targets using SWD -> monitor swdp_scan

  • Attaching to the detected target -> attach 1

  • Loading the project binary -> load

  • Starting the firmware with a breakpoint set to the start of the main function -> start

  • Stepping over the main function -> next,[enter,...]

  • Continuing execution -> continue

  • Breaking and detaching from the target -> CTRL-C, CTRL-D

Support the Project

The best way to support the project is purchasing the official Black Magic Probe hardware. If you would like to support the project beyond that please consider supporting these individuals and organizations:

Getting Hardware

The official Black Magic Probe hardware was specifically designed with Black Magic Debug in mind and the proceeds from the sales directly support and further the development of the software. See the Support the Project section for other means of sponsoring the development of Black Magic Debug.

The official Black Magic Probe hardware is available from these distributors in alphabetical order:

Other Hardware supported by Black Magic Debug:

  • Stlink V2.1 and V3 based boards with a BMDA variant of the BMD (PROBE_HOST=pc-stlinkv2)

  • LibFTDI based based boards boards with a BMDA variant of the BMD (PROBE_HOST=libftdi)

  • StlinkV2 based boards with BMD ST-Link firmware (PROBE_HOST=stlink ST_BOOTLOADER=1) flashed with stlink-tool to unmodfied board, see Readme.md.

  • StlinkV2 based boards with BMD ST-Link firmware (PROBE_HOST=stlink) with BMD own bootloader flashed to the board.

  • STM8S Discovery (StlinkV1) and Bluepill board with BMD SW-Link firmware (PROBE_HOST=swlink)

  • F4 Discovery (STM32F407) with BMD f4discovery firmware (PROBE_HOST=f4discovery)

  • Blackpill V2 (STM32F411) (PROBE_HOST=blackpillv2)

  • launchpad-icdi with BMD launchpad-icdi firmware (PROBE_HOST=launchpad-icdi)

  • Hydrabus(?) (PROBE_HOST=hydrabus)

  • TM4C(?) (PROBE_HOST=tm4c)

Black Magic Debug App (BMDA)

You can also compile the Black Magic Debug as a stand alone application instead of a firmware that you can flash onto a microcontroller. This mode resembles the way OpenOCD is used as an “application in the middle”.

To compile BMDA you need to run make PROBE_HOST=hosted. The resulting application can be run on your computer and is able to detect all kinds of hardware probes including:

  • Black Magic Probe

  • FTDI adapters

  • CMSIS_DAP capable debuggers

  • JLink (slow)

  • ST-Link V2/V3

Contact:

  • If you have questions or suggestions feel free to join us in our chat Discord