Skip to content

Hacking

Robert Navado edited this page Dec 17, 2018 · 25 revisions

The Black Magic Probe consists of both hardware and firmware components. Both are under open-source licenses and available on Github.

Getting the project source

The project resides in a GitHub git repository

Clone this repository (or fork and clone) using your desired method. Typically:

git clone https://github.com/blacksphere/blackmagic.git

The project uses libopencm3, which is included as a git submodule. Thus, prior to building the project, one must initialize this submodule:

cd /path/to/blackmagic
git submodule init
git submodule update

Compiling for the native hardware

To build the firmware for the standard hardware platform run make in the top-level directory. You will require a GCC cross compiler for ARM Cortex-M3 targets. A good option is gcc-arm-embedded. The default makefile assumes the target prefix is arm-none-eabi-, but you can override this on the command line:

make CROSS_COMPILE=arm-cortexm3-eabi-

This will result in binary files:
blackmagic - ELF binary of the Black Magic debug probe.
blackmagic.bin - Flat binary of the Black Magic debug probe, load at 0x8002000.
blackmagic_dfu - ELF binary of the Black Magic DFU bootloader.
blackmagic_dfu.bin - Flat binary of the DFU bootloader, load at 0x8000000.

Alternative Hardware

A number of users have contributed alternative hardware designs that are compatible with the native firmware. Some of these designs are in the hardware repo. Check the README files for details.

There have also been efforts to port the firmware to other hardware platforms, most notably the ST-Link and discovery boards, as these are very cheap and common. See this tutorial.

Building on Windows

Sid Price wrote a detailed step by step guide describing how to set up CygWin and compile the Black Magic Probe firmware.

Compiling as a PC application using FT2232 hardware

The Black Magic application can also be compiled as a native PC application which will use an FT2232 device to implement the physical JTAG interface. This is not the intended mode of operation, but is useful for debugging, experimentation, and if you don't have the actual hardware. Pending patches (May 2018) bring programming speed for MPSSE FTDI devices to similar speed as the original BMP.

Compile the application with the command:

make PROBE_HOST=libftdi

Running the application blackmagic -c <cable> will start a GDB server on TCP port 2000. <cable> is a string identifier for your particular FTDI JTAG cable. See src/platforms/libftdi/platform.c for valid options.

Enabling DEBUG() messages

First compile in the debug messages when building the firmware:

make ENABLE_DEBUG=1

Then enable debug messages in gdb with the new command

monitor debug_bmp enable

The debug messages appear on the debug UART. On a BMP the USB UART device is used.

screen /dev/ttyACM2 115200

Updating firmware

There is an update tool in upgrade subfolder. Build it with the default make file residing there.

$ cd upgrade
$ make
gcc    -c -o bindata.o bindata.S
gcc -Wall -Wextra -std=gnu99 -O0 -g -MD -mno-ms-bitfields   -c -o dfu.o dfu.c
gcc -Wall -Wextra -std=gnu99 -O0 -g -MD -mno-ms-bitfields   -c -o stm32mem.o stm32mem.c
gcc -Wall -Wextra -std=gnu99 -O0 -g -MD -mno-ms-bitfields   -c -o main.o main.c
gcc -Wall -Wextra -std=gnu99 -O0 -g -MD -mno-ms-bitfields -o blackmagic_upgrade bindata.o dfu.o stm32mem.o main.o -lusb

The process produces executable binary blackmagic_upgrade

Upgrade procedure:

  • Build the firmware according your needs
  • Important Build the upgrade tool after the firmware built. Upgrade tool includes the firmware statically!!!
  • Optionally Reboot device holding the button (Valid at least for BMP 2.1). Running LED indication on the device is the sign of the upgrade mode. blackmagic_upgrade knows to reset the target
  • Run blackmagic_upgrade with privileges (sudo ./blackmagic_upgrade in Linux based systems or from administrative shell in Windows)

NOTICE: The content of this wiki has been moved to http://black-magic.org website. Please update your links.

Clone this wiki locally