Debugging with GDB on STM32

This page describes how to setup GDB on Linux to debug issues on STM32. The specific commands were tested on Ubuntu 13.10. GDB can also be set-up on Windows but there is an issue passing the Ctrl-C command to GDB which makes it difficult to use effectively.


This page has not be maintained from some time, if something is wrong please contact us on Gitter/ArduPilot.


GDB (the GNU Debugger) “allows you to see what is going on `inside’ another program while it executes or what another program was doing at the moment it crashed.” which can be useful when investigating very low-level failures with the STM32 (it cannot be used with the APM1/APM2)

This guide assumes that you have already successfully built the firmware on your machine following the instructions for Windows, Mac or Linux.

A BlackMagic probe or ST-Link V2 JST debugger is also required. A BlackMagic probe can be purchased in the US from Transition Robotics, Tag-Connect or 1 Bit Squared or in NewZealand from Greenstage.

Connecting the probe to the Pixhawk


The BlackMagic probe should be connected to the Pixhawk’s JTAG connector using the grey 10wire cable that came with the probe. Note that most Pixhawk come with no headers soldered onto the JTAG connector because it interferes with the case.

Installing GDB

If using Ubuntu, GDB is likely already installed on your machine and it will likely work although we recommend using the version available for download here

The gcc-arm-none-eabi*-linux.tar.bz2 file contains both the recommended compiler and the recommended version of gdb.

If you will be using the ST-Link debugger, please install the gdb version found in the gcc-arm-none-eabi-6-2017-q2-update-linux.tar.bz2 file.

After installation you should find you have a tool called arm-none-eabi-gdb.

Installing OpenOCD

You will need to install OpenOCD if you are using the ST-Link debugger.

OpenOCD requires libusb which you can install using sudo apt-get install libusb-1.0-0-dev libusb-1.0-0.

Next, download OpenOCD from the project’s SourceForge page. Make sure you just install version 0.10 as other versions may not be compatible. Unpack the file, and navigate to the folder from the command line. Next, execute the following commands

sudo make install
Download this openocd.cfg
to the directory where you have built the arducopter.elf file.

Now, to start gdb. First, type openocd in your terminal in the directory where you downloaded the openocd.cfg file. Note: there are 2 versions of the ST-link debugger on eBay, so if the command does not work, change the first line to source [find interface/stlink-v2-1.cfg].

In another window, type arm-none-eabi-gdb arducopter.elf. Next, type target extended-remote :3333. Now you have connected to the gdb debugging session and can use the commands from the next section.

Starting GDB and running some commands

GDB requires both the firmware file that’s been uploaded to the board (i.e. arducopter.apj) which can normally be found in Copter, Plane or APMRover2 directory and the firmware.elf file that can be found in the build directory.

Change to your firmware directory and type the following:

arm-none-eabi-gdb build/fmuv3/bin/arducopter


Some useful commands:

r – restarts the process

b function-name – i.e. b setup – sets a breakpoint at the start of the “setup” function. Note a class name can be prepended such as b AC_AttitudeControl::init

Ctrl-C – stops the code from executing so you can set breakpoints, etc

continue – continues the code from wherever it was stopped

show interrupted-thread – shows address where execution has stopped (see below)

info line * <address> – shows c++ line for a given address (i.e. from show interrupted-thread)

disassemble <address> – converts given address into assembler code

exit – exits from the GDB