Hacking

The Black Magic Probe consists of both hardware and firmware components. The hardware design resides in the 'hardware' directory and the firmware resides in the 'src' directory.

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 src 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.

Programming the native hardware

You can boot the STM32 into the bootloader by pressing the button and connecting the USB port. Observe the flashing red led once the STM32 is booted in DFU mode.

If you already have a JTAG/SWD debug probe, that can be used to load these binaries to your target hardware. If not the SystemMemory bootloader can be used to load the DFU bootloader:

../scripts/bootprog.py blackmagic_dfu.bin

This requires an appropriate cable to connect the PC serial port to the probe. See the schematic for more information.

Once the DFU bootloader is loaded, the Black Magic application can be loaded over USB:

../scripts/stm32_mem.py blackmagic.bin

The device should reset and re-enumerate as a CDC-ACM device implementing the GDB protocol.

Alternative Hardware

A number of users have contributed alternative hardware designs that are compatible with the native firmware. Some of these designs are in hardware/contrib. 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.

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.

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.