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. The project focuses 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¶
11 January - Stable Release V1.9.3
10 January - Stable Release V1.10.2
30 November - Stable Release V1.10.1
28 October - Stable Release V1.10.0
11 October - Release Candidate V1.10.0-rc1
17 September - Release Candidate V1.10.0-rc0
16 September - Stable Release V1.9.2
16 September - Stable Release V1.8.3
28 April - Stable Release V1.9.1
27 January - Stable Release V1.9.0
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 macOS.
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, containing GCC and GDB for your microcontroller. Plug the Black Magic Probe hardware, running the Black Magic Debug firmware, into your computer. 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. Further details are found in Getting Started.
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 anything is 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:
DE: 1BitSquared Germany Black Magic Probe V2.3 (Multiple accessory options) (Newest)
USA: 1BitSquared US Black Magic Probe V2.3 (Multiple accessory options) (Newest)
USA: Adafruit Industries Black Magic Probe V2.3 (With JTAG/SWD and UART cables) (Newest)
NL: Elektor Black Magic Probe V2.3 (With JTAG/SWD and UART cables and 7Pin Adapter) (Newest)
USA: Mouser Black Magic Probe V2.3 (With JTAG/SWD and UART cables) (Newest)
Other Hardware supported by Black Magic Debug:¶
ST-Link v2, v2.1 and Blue Pill. See stlink
ST-Link v3. See stlinkv3
STM8S Discovery (ST-Link V1). See swlink
F4 Discovery (STM32F407). See f4discovery
Black Pill F4 (STM32F401CC/STM32F401CE/STM32F411CE). See blackpill-f401cc, blackpill-f401ce, blackpill-f411ce
TI LaunchPad Tiva C onboard programmer. See launchpad-icdi
96Boards Carbon. See 96_carbon
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”. Please find more details on the hardware page.