STM32CubeIDE programmer and ST-LINK GDB server on Linux

This article discusses how to create a minimal set-up for running a gdb server on Linux using ST tools.

ST provides the STM32CubeIDE, which is an IDE based on Eclipse and designed to include the entire STM32 workflow. I am not super fan of all this super complex and bloated IDEs, as they tend force a fixed development strategy on the user. I therefore tried to look for alternatives.

The obvious choice is to use the J-Link from Segger, which is straightforward to use and support tons of different platforms, but commercial licenses are quite expensive.

An open-source option is to use the Black Magic Probe, which also includes a gdb server and VCOM running directly on the probe. It can be bought from the developer (and support the project) or even flashed into the famous Blue Pill (STM32F103x8) or in the STLink. It can be even used as a software layer on top of the STLinks V2-1, which is the programming boards included in all Nucleo boards, and is a very handy feature. All the reviews are great and it works very well, but does not support thread awareness out of the box, which is sometimes a limiting factor.

There are also many other open alternatives, as OpenOCD, pyOCD and texane/stlink. OpenOCD has tons of features, supports thread awareness but is not always straightforward to use and install. pyOCD is very easy to use and works very well, it is thread aware (at least with FreeRTOS, Zephyr, and some others), but has some bugs with the CMSIS packs and therefore I haven’t managed yet to flash the firmware. You need to use one of the other methods to flash it. I haven’t tried texane/stlink, so I cannot comment on that.

Anyway, if you want to minimize every possible problem and avoid compatibility issues, it is also possible to use tools directly provided by ST, but on the command line and without having to use the entire STM32CubeIDE.

So, as an example, you can flash the firmware using STM32CubeProg and then run the GDB server using pyOCD and have a fully thread aware debugging tool, or just use STM32CubeIDE ST-LINK GDB server if you don’t need thread awareness.

Installing STM32CubeProg

STM32CubeProg can be downloaded directly from ST Website.

To install it, unzip the downloaded file, and run the installer. Do not create any shortcut or launcher at the end of the installation.

./SetupSTM32CubeProgrammer*.linux

After the installation is completed, open the folder in your home. With the default path it should be:

cd ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/

You need to update the udev rules in order to properly enumerate the device. This can be done with:

sudo cp ./Drivers/rules/*.rules /etc/udev/rules.d/

If you want to be able to run the command from the cli without having to add the path, you need to add the executable to a folder that is in the PATH variable.

Check with echo ${PATH} if there already is a user folder. It could be ~/bin or ~/.local/bin. I have both. If not add it to your .bashrc with

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc

Now create the launcher in ~/bin with a small bash script to launch the STM32CubeProgrammer and make it executable

cat << EOF > STM32_Programmer_CLI
#!/bin/bash
cd ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/
bash STM32_Programmer.sh "\$@"
EOF
chmod +x STM32_Programmer_CLI

You should now be able to run it from you cli. If not, try to open a new one or to source ~/.bashrc, as the path needs to be updated.

The manual for STM32CubeProg can be found searching for UM2237.

The following is an example command to flash and verify the hex executable image.hex through SWD.

STM32_Programmer_CLI -c port=SWD -w $(pwd)/image.hex -v -ob displ -rst

ST-LINK GDB server

The GDB server can be connected by a GDB client compiled for the ARM platform and then used directly or by using a GDB gui, as gdbgui.

Install ST-LINK server

The ST-LINK server is an application to share the debug interface of a single ST-LINK board among several host applications, typically a debugging tool and a monitoring tool.

Is is not really mandatory in order to use the GDB server, but it is used for the option -t, --shared. It is therefore optional to install.

It can be downloaded directly from ST. Unpack the archive and simply copy the executable in

~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin

create a symlink from ~/bin to the executable above

cd ~/bin
ln -s ../STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/stlink-server.1.1.1-3 stlink-server

replace the version (here 1.1.1-3) with your version.

Install STM32CubeIDE ST-LINK GDB server

I have not been able to find a standalone gdb server, but it needs to be installed from STM32CubeIDE.

The first step is to download the generic Linux installer for STM32CubeIDE from ST website It is quite heavy, around 700Mb at the time of writing. It includes a complete IDE and lot of other software, from openOCD to a patched ARM compiler. Download it in a independent folder, for example in mkdir en.st-stm32cubeide. The ST website requires to accept a license before downloading, therefore it cannot be done using wget (or curl, aria2, …).

The downloaded archive contains a Makeself bash archive that ca be used to install the IDE. It is not required to install it to get the gdb server, but it needs to be uncompressed, which is simply done by running

unzip en.st-stm32cubeide*
bash st-stm32cubeide* --noexec
cd st-stm32cubeide*.root
tar xvzf st-stm32cubeide*.tar.gz
cd plugins

You can see that there are tons of plugins available, including the software that we installed in the previous steps. However, I prefer to install them individually as they might be more recent.

The gdb server is included in com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64*, and to install it

cd com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64*/tools
cp -r * ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/ --verbose

cat << EOF > ~/bin/ST-LINK_gdbserver
#!/bin/bash
cd ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/
./ST-LINK_gdbserver --verify -c config.txt -cp . "\$@"
EOF
chmod +x ~/bin/ST-LINK_gdbserver

The entire procedure can be placed in a single script if desired.

To start the gdb server

ST-LINK_gdbserver

by default it listens on the port 61234.

Then to start the gbd client, run in another terminal session

arm-none-eabi-gdb 

Consider that the gdb client shall be compiled for cross debugging. The arm gcc toolchain in the plugins or the gcc toolchain that can be downloaded from ARM’s website are already compiled with proper flags.

Once the gdb client has started, connect to the server by issuing

target extended-remote localhost:61234

For more example and help, please refer to the ST-LINK_gdbserver manual that can be found searching UM2576

I hope your gdb is now up and running and ready to debug.

pyOCD

Since there is a bug in pyOCD, you need to stop the gdb server and flash the firmware using another flashing tool and not GDB.

This can be done for example with

STM32_Programmer_CLI -c port=SWD -e all -w $(pwd)/build/image.hex -v -ob displ -rst

Then start pyOCD gdb server and connect a client, which can be a GDB client compiled for the ARM platform and then used directly or by using a GDB gui, as gdbgui.