ardupilot/Tools/debug

Hardware Debugging with ArduPilot

This directory contains files that are useful for setting up to debug ArduPilot using either a black magic probe or a stlink-v2 with openocd.

This assumes you are debugging a ChibiOS based firmware on a STM32 board.

Debugging with a Black Magic Probe

If you have a black magic probe (see https://1bitsquared.com/products/black-magic-probe) then first make sure it has the latest firmware. See the wiki here for details: https://github.com/blacksphere/blackmagic/wiki

Next, copy the file gdb-black-magic.init to the ArduPilot source directory, in the same directory where you will be starting the debugger. Rename the file to ".gdbinit"

Now either edit the .gdbinit to give the path to the serial port for your black magic probe, or install the provided udev rules file so that the probe will be loaded as /dev/ttyBmpGdb

Now make sure you have the right version of arm-none-eabi-gdb installed. We recommend version 10-2020-q4-major, which is available here: https://firmware.ardupilot.org/Tools/STM32-tools/

Now build ArduPilot with the --debug configure option. You may also like to include the --enable-asserts. Enabling asserts will slow down the firmware quite a lot, but will help catch ChibiOS API usage bugs.

For example:

./waf configure --board Pixhawk1 --debug --enable-asserts

Now build and install your firmware:

./waf copter --upload

After it is loaded you can attach with gdb like this:

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

then you can use normal gdb commands. If you are not familiar with gdb then do a google search.

Note that for a source view the command "layout src" or "layout spit" is useful.

Debugging with a STLink-v2

If you have a STLink-V2 adapter (or one of the very cheap clones) then you can debug with openocd. Using openocd has the advantage that you can debug threads properly, unlike the black magic probe which can't see ChibiOS threads.

Start by installing the latest version of openocd, then copy the openocd.cfg file from this directory to the directory where you will be debugging.

You may need to edit the openocd.cfg file to set the MCU type. The one in this directory is setup for a STM32F4 board. If you have a STM32F7 or STM32H7 then edit the file in the obvious way.

Now start openocd in a terminal. You should get output like this:

Open On-Chip Debugger 0.10.0+dev-00272-gedb6796 (2018-01-19-17:26)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 1800 kHz
adapter_nsrst_delay: 100
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
Info : clock speed 1800 kHz
Info : STLINK v2 JTAG v29 API v2 SWIM v18 VID 0x0483 PID 0x374B
Info : using stlink api v2
Info : Target voltage: 3.253404
Info : stm32h7x.cpu: hardware has 8 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections

the above output is for a STM32H743 Nucleo board, but others are similar

In another terminal, copy the gdb-openocd.init file to the directory where you will be debugging, calling it .gdbinit.

Now build and load the debug enabled firmware for ArduPilot in the same manner as given above for the Black Magic probe, and start arm-none-eabi-gdb in the same manner.

To see ChibiOS threads use the "info threads" command. See the gdb documentation for more information.