Black Magic Open-Source Debug Probe for ARM With Eclipse and GDB

The ‘Black Magic Probe’ (or in short: BMP) is a very small and open-source JTAG/SWD debug probe with a built-in GDB Server. I saw that probe referenced in different places, so I thought I would try it out with a few of my NXP LPC and Kinetis boards:

BMP with LPC and Kinetis Boards

The probe is designed by 1BitSquared in collaboration with Black Sphere Technologies and is open source. It runs on ‘native’ probe hardware (which I bought), or the firmware can be programmed on different STLink hardware.

I ordered the BMP from Adafruit ($60 USD). The probe comes as a very small board (35x15mm), and the kit included the 10pin SWD cable and a 4pin UART cable. The probe includes a UART-2-USB CDC functionality, so this is definitely a plus.

Black Magic Debug Probe

I wanted to try it out with Eclipse and see if it would be a good fit for my projects or for student projects. Here is what I have used:

• Black Magic Debug Probe, HW version 2.1, ordered from Adafruit.
• Probe firmware: (Firmware v1.6.1-1-g74af1f5) (Hardware Version 3)
• Eclipse: NXP MCUXpresso IDE v11.0.0
• Boards
  • NXP FDRM-KL25Z
  • NXP FRDM-KL27Z
  • NXP LPC824-MAX
  • NXP LPC800-DIP
  • NXP LPC845-‘dipsy’

Be aware that only a few target and devices are supported by the BMP! Make sure your device is listed! But if the device is listed might not mean that every package or derivative is supported, so better check.

USB Devices

The board enumerates under Windows with two serial ports (the first one is the debug port, the second one the UART-2-USB port).

Black Magic Debug Probe Devices

Because my probe already has the latest firmware, I did not update it with the ‘Black Magic Firmware Upgrade’. For more details, see this link. The DFU utility is available on http://dfu-util.sourceforge.net/

I did not had the time to try out the ‘Black Magic Trace Capture,’ which looks interesting, but it seems to be experimental. More information can be found in this link.

While different from other GDB JTAG/SWD with the client/server concepts, this probe already implements the GDB server inside the probe. So instead of connecting to a (local or remote) GDB server, I connect to the (first) serial port (in my case: COM80), which probe implements. On one end this makes things simpler (no need to provide or run the server binary which needs to be implemented for each host), on the other side it makes it less flexible (so no remote debugging except through COM port sharing).

So instead of connecting from the GDB to a USB or TCP port, I have to connect using the gdb command:

target extended-remote

To make things a bit strange, it requires a ‘\\.\’ prefix on Windows if the port number is >10 (which is the case on my machine):

target extended-remote \\.\COM81

I recommend to run the probe first with the command line gdb, and after this works, move up to using it with Eclipse.

Command Line GDB

Make sure that the GDB version used is from the *same* toolchain/gcc, which was used to build the binary! A mismatch of gcc and gdb can cause strange failures!

Using the GNU ARM toolchain in the MCUXpresso V11.0.0, the GDB is located in (adapt to your installation path):

C:\nxp\MCUXpressoIDE_11.0.0_2516\ide\tools\bin\arm-none-eabi-gdb.exe

Which gives:

C:\nxp\MCUXpressoIDE_11.0.0_2516\ide\tools\bin\arm-none-eabi-gdb.exe: warning: Couldn't determine a path for the index cache directory.
GNU gdb (GNU Tools for Arm Embedded Processors 8-2018-q4-major) 8.2.50.20181213-git
Copyright (C) 2018 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=i686-w64-mingw32 --target=arm-none-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word".
(gdb)

Allow gdb to access memory outside of the memory map:

(gdb) set mem inaccessible-by-default off

Connect to the port of the BMD:

(gdb) target extended-remote \\.\COM81

Use ‘monitor help’ to get a list of supported monitor commands:

(gdb) monitor help
General commands:
        version -- Display firmware version info
        help -- Display help for monitor commands
        jtag_scan -- Scan JTAG chain for devices
        swdp_scan -- Scan SW-DP for devices
        targets -- Display list of available targets
        morse -- Display morse error message
        connect_srst -- Configure connect under SRST: (enable|disable)
        hard_srst -- Force a pulse on the hard SRST line - disconnects target
        tpwr -- Supplies power to the target: (enable|disable)
        traceswo -- Start trace capture

Scan the SWD chain for targets:

monitor swdp_scan

Which gives for the FRDM-KL25Z:

(gdb) monitor swdp_scan
Target voltage: 3.0V
Available Targets:
No. Att Driver
 1      KL25
 2      Kinetis Recovery (MDM-AP)
(gdb)

Attach to the first device in the list (the second one for the KL25Z is an artificial one for flash recovery):

attach 1

Then load the binary with the following:

load binary.axf

Be patient, flashing is rather slow (~2 KB/sec) for KL25Z.

Then ‘kill’ the program, which will reset and run the target:

kill

Finally, I can now exit the GDB with:

quit

Debugging FRDM-KL25Z with Black Magic Debug probe

With these steps, I have something I can automate. I can put this into a script file:

set mem inaccessible-by-default off
target extended-remote \\.\COM81
monitor swdp_scan
attach 1
load kl25z.axf
#compare-sections
kill
quit

And then, I can call gdb with that script:

"C:\nxp\MCUXpressoIDE_11.0.0_2516\ide\tools\bin\arm-none-eabi-gdb.exe" -x gdbscript.txt

Debug With Eclipse

With having a working setup using command line tools, it is now time to do the same with Eclipse — in my case, with the MCUXpresso IDE.

First, create a new debug configuration for the project under ‘GDB Hardware Debugging’:

BMP GDB Hardware Debugging Launch Configuration

In the ‘Debugger’ Tab, point to the gdb executable with ‘use remote target’ unchecked:

Debugger Tab

In the ‘Startup tab,’ use the following settings (adapt to your COM port):

set mem inaccessible-by-default off
target extended-remote \\.\COM81
monitor swdp_scan
attach 1

Startup Tab

With this, I can use Eclipse and source-level debug the board:

Debugging with BMP and Eclipse

Other Microcontrollers?

I was able to get the probe quickly working for the KL25Z microcontroller. But I failed to get it working for the other targets.

The KL27 is supposed to be supported, but the probe only reports a generic ARM Cortex-M:

(gdb) monitor swdp_scan
Target voltage: 3.3V
Available Targets:
No. Att Driver
1 ARM Cortex-M
2 Kinetis Recovery (MDM-AP)

The LPC824 is detected (as LPC82x):

(gdb) monitor swdp_scan
Target voltage: 3.3V
Available Targets:
No. Att Driver
1 LPC82x

But loading always fails:

(gdb) load lpc824.axf
Loading section .text, size 0x6954 lma 0x0
Load failed

Most of the time, it fails with:

Error erasing flash with vFlashErase packet

GDB gave a hint about the following:

warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.

But using ‘file’ failed too:

Load new symbol table from "lpc824.axf"? (y or n) y
Reading symbols from lpc824.axf...
Could not read registers; remote failure reply 'EFF'

This sounds like a problem of BMP firmware, but I had no time to investigate further.

Summary

The Black Magic Probe implements a GDB server on the probe itself. I managed to get it working with the FRDM-KL25Z both in command line mode and Eclipse. The probe is rather expensive compared to the $20 USD of an NXP LPC-Link2 or 20 Euros for a Segger J-Link EDU Mini, but on the other side, this supports an open-source development, so I’m OK with it. The included UART-2-Serial converter is a plus. Flash programming (compared to other probes), at least for Kinetis, is slow.

I had it working quickly for the Kinetis KL25Z (FRDM-KL25Z) board but failed to get it working with the NXP LPC boards I tried. If I find a solution, I’ll update this article with it.

Happy Black Magic Spelling!

Helpful Links

• GitHub: https://github.com/blacksphere/blackmagic/wiki
• 1 Bit Squared: https://1bitsquared.com/products/black-magic-probe
• Adafruit: https://www.adafruit.com/product/3839