Cortex-M debugging probe

The Black Magic Debug Probe (BMP) v2.1 was launched through a Kickstarter campaign. It is an Open Hardware, Open Source device that enables attachment of a source-level debug tool to an embedded Cortex-M MCU using either JTAG or SWD. The software for the device has a comprehensive build system that allows building for multiple platforms in addition to the Blacksphere v2.1 hardware. However, if one is a Windows-centric developer building the code can be challenging. This article aims to detail the process for building the BMP software on a Windows development computer.

Installation of required tools.

Since the build system for BMP requires some Linux features the first prerequisite is the Cygwin Linux-like environment for Windows. It may be downloaded from cygwin.com and installed by following the instructions on the web site. In addition to the default packages installed also select and install:

• make: The GNU version of the ‘make’ utility

BMP makes use of the Open Source Cortex-M3 hardware abstraction library libOpenCM3, a submodule of the BMP repository. This library has some dynamic file generation that requires Python, it may be downloaded and installed from the python.org web site. Note that it is recommended to use v2.7 of Python. There may be issues using v3.x. Once Python is installed add the path to “python.exe” to your system path so that it is found when executed from the Cygwin terminal. TO test this open the Cygwin terminal and execute “python –version”:

If you do not already have git installed go to the git web site and download and install it. When the installation is complete you may test it by entering the command “git –version”:

Finally the GNU ARM Embedded Toolchain should be installed from the developer.arm.com web site. When the installation completed dialog appears make sure to check the “Add path to environment variable” option. Once the installation is complete, start the Cygwin terminal and execute the command “arm-none-eabi-gcc –version” to check the installation:

Getting the source code.

I like to keep my project files under a single root folder to make backup a little easier, rather than having to backup multiple locations. This folder is named “C:\DataRoot\Projects” and I cloned any Github repositories into this folder. This requires and extra step or two to have the project source available to the Cygwin terminal, this is described below.

The source code for the BMP is hosted on GitHub. The recommended procedure to acquire the source is to following these steps:

• Clone the repository, or fork and clone. If you are using git on the command line it would be something like:
  • git clone https://github.com/blacksphere/blackmagic.git
• Initialize the libOpenCM3 sub-module using the following steps:
  • Set you current working directory to the root of the BMP source, e.g. <path to the root>/blackmagic.
  • execute -> git submodule init
  • execute -> git submodule update

If you cloned the BMP repository into the Cygwin file structure you are ready to begin the build process. If however, you have the source outside the Cygwin file structure you will need to mount it for Cygwin to work with it. My BMP repository is cloned into “c:\DataRoot\Projects\blackmagic” and I use the following commands in Cygwin to mount the source:

Building libOpenCM3

In spite of using the Cygwin environment there is still an issue with the environment that does not allow the building of all of the various libOpenCM3 MCU libraries using the Makefile supplied. The following procedure is based upon information gleaned from the article “Install libopencm3 for Cygwin” on the CompuSilli blog. I would love to directly cite the author but so far have been unable to identify them.

For the build procedures described below I will use “<project root>” to indicate the folder into which the BMP repo was cloned. On my computer that would be “c:\DataRoot\Projects\blackmagic.”

Start by running the Cygwin command to open a Cygwin terminal window. In order to access the BMP repo it is necessary to mount the repo in the Cygwin environment, I chose to create a folder in the Cygwin home folder called “projects” and to create a folder inside that called “blackmagic.”

Next, mount the actual “blackmagic” repo on the Cygwin “home/projects/blackmagic folder just created:

• mount <project root> ~/Projects/blackmagic

The main makefile of the BMP build runs some Python scripts that generate some header files required for the libOpenCM3 builds. This presents a small “catch 22” scenario because the main makefile will not run to completion without the library files being built for the chosen platform. However, the main makefile does the script running first and therefore we can run it just to generate the header files required. So, even though it will result in an error do the following next:

• change to the root folder of the repository
  • In my case ~/projects/blackmagic
• execute
  • make clean
  • make

Now we need to choose the library to build for the platform supporting the BMP. If you are building software for the BMP v2.1 hardware you will need to build the library for the STM32F1xx; use the following commands to build the library.

• cd libopencm3/lib/stm32/f1
• make clean
• make

To build the “native” BMP software for the v2.1 hardware use the following commands:

• cd src
• make

To build for a different platform, for example the Nucleo STLinkV2 replace the last line above with:

• make PROBE_HOST=stlink

Flashing the new software onto the BMP

Updating the firmware on Windows requires a driver installation and the use of a tool called DF-Util.

The driver (on Windows 10) is installed using a utility from http://zadig.akeo.ie/. Black Magic Probe uses a driver called libusbK, a selection offered by the Zadig tool.

Place the BMP into DFU mode by cycling the power while holding down the small button on the probe. If the probe enters DFU mode all three LEDs will flash. Then in a command window enter the following command:

• dfu-util.exe -d 1d50:6018,:6017 -E 20 -s 0x08002000:leave -D blackmagic.bin

Cycle the power on the BMP and the new software should be running.

Should you discover any issues with the above procedure or have suggestions for improvements please leave a comment below and I will check it out and if appropriate update the article.

Happy debugging!

Twitter @sjp_software

LinkedIn https://www.linkedin.com/in/sid-price-software-design/

Facebook https://www.facebook.com/sidpricedesign/