Debugging Guide¶

Being able to debug your code is pretty much an essential skill for developing embedded firmware. While printf statements are a perfectly valid way of debugging, modern debugging tools exist to supercharge your bug tracking. Some features of modern debuggers include setting breakpoints, stepping through code, watching variables, and much more.

Any modern debugging tool that supports ARM Cortex-M microcontrollers will probably work for debugging STM32 chips, but GDB is the officially supported debugging engine for mJackets. GDB, the GNU Project 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. GDB can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act:

Start your program, specifying anything that might affect its behavior.
Make your program stop on specified conditions.
Examine what has happened, when your program has stopped.
Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.

The following sections will detail getting GBD set up with your development environment.

Install Required Tools¶

Several tools are required to debug STM32 microcontrollers:

ARM GCC Toolchain (https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads) - provides arm-none-eabi-gdb and related tools
J-Link Software Tools (https://www.segger.com/downloads/jlink) - provides the J-Link GDB Server for J-Link based debuggers

Installing J-Link Software¶

The J-Link Software Pack can be downloaded at: <https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack> .

For Ubuntu you want to download the file labeled as ‘J-Link Software and Documentation pack for Linux, DEB installer, 64-bit’

For Windows you want to download the file labeled as ‘J-Link Software and Documentation pack for Windows’

Provided that file was stored in your downloads folder you can use the below to install the package:

sudo dpkg -i ~/Downloads/JLink_Linux_V656a_x86_64.deb
sudo apt install -f

After installing the J-Link software package please restart your terminal emulator and try to tab complete and open the program JLinkExe. If you are successful you will be greeted by the following:

SEGGER J-Link Commander V6.56 (Compiled Nov 22 2019 17:14:15)
DLL version V6.56, compiled Nov 22 2019 17:14:02
Followed by a can not connect error if the J-Link is not connected. Close JLinkExe with exit.

JLink Ozone debugger¶

Ozone is a free cross-platform debugger and performance analyzer for J-Link and J-Trace. It’s advantages are that it is completely standalone and that it is very quick to get it set up with your project. This is a very capable debugger with far too many features to list here, so check out the website for more information on what Ozone can do.

It is reccommended that you use the JLink EDU Mini or JLink EDU debugger probes with Ozone.

You can download the appropriate version of Ozone for your OS from the website.

Setup¶

Once you have downloaded and installed Ozone onto your computer, and have installed the J-Link Software Pack, you are ready to set up the debugger with your project.

Launch Ozone
Run the New Project Wizard by going to File->New->New Project Wizard
Under Device, select the target STM32 chip that you are debugging and click next.
Change the Target and Host Interface settings to match your debugger probe and click next.
Select the compiled executable of your program located in the build folder of your project. To get all of the debug symbols, you will want to use the *.elf output file. Click finish to complete setup.

That’s it! You are now ready to debug your application.

Basic Debugging¶

This guide will go over some basic features to get you started debugging, and you can check out the Ozone User’s Manual for a complete reference on how to use the program.

Connect to Target and Download Application¶

Make sure that your board is power up, and that you have connected your debug probe to the board and your host computer.
Click on Debug->Start Debug Session->Download and Reset Program to start the debugging session and set a breakpoint at the beginning of the application’s main() function.

Breakpoints and Stepping Through the Code¶

Watching Variables¶

VSCode / VSCodium Setup¶

Cortex-Debug¶

The Cortex-Debug extension is the glue that pulls in all of the capabilites of GDB into VSCode. You will need to enable the extension from the extension marketplace.

In your VSCode .vscode/settings.json file, add the following line to let Cortex-Debug know where your JLink GDB server executable lives:

“cortex-debug.JLinkGDBServerPath”: “/opt/SEGGER/JLink/JLinkGDBServerCLExe”

You then need to add a debug configuration to your .vscode/launch.json. For the reccommended setup, use the below configuration, editing the device, interface, and executable parameters to match your project.

{

“version”: “0.2.0”, “configurations”: [

{
“name”: “Debug”, “cwd”: “${workspaceRoot}”, “executable”: “./build/debug/myApp.elf”, “request”: “launch”, “type”: “cortex-debug”, “servertype”: “jlink”, “interface”: “jtag”, “device”: “STM32F769NI”, “runToMain”: true, “preRestartCommands”: [

“load”, “enable breakpoint”, “monitor reset”

]

}

]

}