The ‘Black Magic Probe’ (or in short: BMP) is a very small and open source JTAG/SWD debug probe with a build-in GDB Server. I saw that probe referenced in different places, so I thought I try it out with a few of my NXP LPC and Kinetis boards:
The probe is designed by 1BitSquared in collaboration with Black Sphere Technologies and is open source. It runs on a ‘native’ probe hardware (which I bought) or the firmware can be programmed on different STLink hardware.
I ordered the BMP from Adafruit ($60). 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.
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
💡 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.
The board enumerates under Windows with two serial ports (the first one is the debug port, the second one the UART-2-USB port).
💡 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 seems to be experimental. More information in this link.
Different than other GDB JTAG/SWD with the client/server concept, this probe already implements the GDB server *inside* the probe. So instead 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 connecting from the GDB to a USB or TCP port, I have to connect using the
gdb command. 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: warning: Couldn't determine a path for the index cache directory. GNU gdb (GNU Tools for Arm Embedded Processors 8-2018-q4-major) 220.127.116.1181213-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:
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):
Then load the binary with
💡 be patient, flashing is rather slow (~2 KB/sec) for KL25Z.
Then ‘kill’ the program which will reset and run the target:
Finally, I can now exit the GDB with:
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 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’:
In the ‘Debugger’ Tab, point to the gdb executable with ‘use remote target’ unchecked:
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
With this I can use Eclipse and source level debug the board 🙂 :
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
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.
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 of an NXP LPC-Link2 or Euro 20 for a Segger J-Link EDU Mini, but on the other side this supports an open source development so I’ 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 🙂
- GitHub: https://github.com/blacksphere/blackmagic/wiki
- 1 Bit Squared: https://1bitsquared.com/products/black-magic-probe
- Adafruit: https://www.adafruit.com/product/3839
- Example script files: https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/BlackMagicDebugProbe
Since the Black Magic Probe is an open source project, there are alternative sources of hardware, such as this one on Tindie: https://www.tindie.com/products/electronutlabs/bumpy-blackmagic-probe-compatible-swd-debugger/ (currently $12 U.S.). Many small boards based on the STM312F103 can use the Black Magic Probe firmware.
If you (or your employer) can afford it, it’s good to support the originators of the project by buying an original. It’s still more affordable than the non-edu versions of the J-Link probe, for example. Though if you cannot, or perhaps need to equip an entire classroom, there are more affordable choices.
If doing a commercial product, then I think spending the money for a P&E and J-Link should be a no-brainer: you get a professional and well supported debug probe which works for many, many devices. And in the case of P&E: it pretty much supports nearly every ARM Cortex on the planet :-). The ‘Edu’ version of the J-Link is not only for educational, but as well for any non-commercial (i.e. hobby) projects. So for $20/Euro 20 every student can get a debug probe which is fast and works out of the box. The BMP is a really cool device and I like it, and I understand that open source is mostly community driven. The challenge on the debug probe side is that things are very fragmented for the open source ones, and say building the JTAG/SWD hardware probe is not the challenge. The challenge is getting decent device and tools support these days.
Your suggestion on checking for support for your specific model before purchase is a sound one. The definitive list is the source on github (https://github.com/blacksphere/blackmagic/blob/master/src/target/).
However, adding another part isn’t that hard. In my case, LPC81x and LPC82x are partially supported, but not the LPC802 & LPC804 parts I’m using. So I’m in the process of adding the entire LPC8xx series. Though I can only test with a few parts, the majority of the code is common, I’m just adding the code to identify the parts and set up their memory configuration correctly.
Thanks for that link. I saw that earlier, but I was hoping there would be a list with the devices somewhere. Having ‘LPC8xx’ would indicate that all LPC8xx are supported (which I wrongly expected).
I’ll have a look what I would have to add (I already saw https://github.com/blacksphere/blackmagic/wiki/Adding-target-drivers)
Yep, I made the same assumption.
I’ve already added all the LPC8xx varients to my fork, but haven’t had a chance to test it yet. See https://github.com/paul-chambers/blackmagic
Once I’ve had a chance to test it, I’ll submit a pull request.
Hi Erich, thanks for the great tutorial. this was exactly what i needed to know to get bmp working with stm32cubeide 🙂 thank you very much!
great to hear it was useful for you!
Thanks for the feedback,
Thanks for this wonderful Tutorial. I’m planning to use this as an alternative to the expensive Lauterbach to flash and debug the M4 core of my i.MX8DXL platform. The BMP wiki (https://github.com/blacksphere/blackmagic/wiki) says only the LPC series of NXP Targets are supported. Can you please shed your views whether it is supported ? if not, then I shall avoid to muck around with the setup and straight away buy the Segger Jlink for myself.
Building a hardware debug probe is very easy compared to the software/tools support. In my case the black magic debug probe is collecting dust because it does not support well the devices I’m mostly using, to bad. My recommendation is that you go straight using the J-Link, you will get much better and professional support that way.
So I have the same fdrm kl25z board but have yet to manage to get started with it because of some weird driver issues. The board refuses to have a driver installed for it, refuses to stay in mass storage mode for longer than a second etc and I have yet to figure out what is going on via bmp/gdb (although I would have been even more lost without your article) any chance you want to help me figure this out or know where to start looking for the answer?
LikeLiked by 1 person
I did not had much success with the Black Magic debug probe on my side, so pretty much it is getting covered with dust. I still hope I could use it somehow in the future, but with limited time I don’t really have the cycles to investigate further, I’m sorry.
CDT 10.7.0 and later versions provide more explicit support for the Black Magic Probe. Select “Black Magic Probe” from the list of debug servers on the “Debugger” page of a “GDB Hardware Debugging” debug configuration.
LikeLiked by 1 person
Were you able to get it working well with any NXP parts?
I have not experimented with the Black Magic Probe in conjunction with NXP devices. The new debug configuration settings simply allow for easier setup of the launch sequence (use of the GDB extended-remote protocol).
The easier setup of the launch sequence for sure is a plus, but it does not help for devices which do not work or are not supported. A few months ago I tried my BlackMagic with latest software/firmware, but was the same for me with NXP devices. To me, as with OpenOCD: it is a good thing if your particular device works and is supported well, otherwise it is very frustrating.