Zephyr RTOS project step debugging with OpenOCD on Eclipse IDE

The Zephyr RTOS project from Linux Foundation has gained a lot of popularity recently. It is one of the best-in-class small, scalable, real-time operating system (RTOS) optimized for resource-constrained devices, across multiple architectures.

In firmware development debugging the code is essential to make sure everything works. The Zephyr project provides all the necessary tools to build, flash and debug our applications, but configuring everything to work from an IDE is not straight forward. I spent days figuring it out. Below I will show the steps required for debugging a Zephyr project on Eclipse IDE using OpenOCD.

Example

To demonstrate we will use the hello_world sample from Zephyr available at zephyr/tree/main/samples/hello_world and step debug it on STM32F3DISCOVERY board. While the Zephyr documentation for this board provides information on how to flash and debug, it does not tells us how to configure the Eclipse IDE and step debug applications.

Required tools

Before proceeding, please make sure you have the following tools installed:

1. Eclipse CDT IDE

2. Zephyr RTOS and its dependencies

Prepare the project

First, copy the hello_world project to your preferred directory and create a directory called source and move the contents of hello_world into source. Then move the source directory into hello_world. The source directory is needed because Zephyr’s build tool west uses CMake and the CMake generator expects the files along with the main CMakeLists.txt file inside of a folder (source in our case) when generating for Eclipse IDE.

$ cp -r ~/zephyrproject/zephyr/samples/hello_world/ ~/my_workspace/
$ cd ~/my_workspace/
$ mkdir -p source
$ mv hello_world/* source/
$ mv source/ hello_world/
$ cd hello_world/

At this point the contents of the hello_world directory should look like this:

$ ls -lR
.:
total 4
drwxrwxr-x 3 user user 4096 Mar 28 12:29 source

./source:
total 20
-rw-rw-r-- 1 user user  194 Mar 28 12:21 CMakeLists.txt
-rw-rw-r-- 1 user user   15 Mar 28 12:21 prj.conf
-rw-rw-r-- 1 user user  610 Mar 28 12:21 README.rst
-rw-rw-r-- 1 user user  324 Mar 28 12:21 sample.yaml
drwxrwxr-x 2 user user 4096 Mar 28 12:21 src

./source/src:
total 4
-rw-rw-r-- 1 user user 196 Mar 28 12:21 main.c

Generate the Eclipse Project

Now, we must build the Zephyr project and use CMake’s generator to generate an Eclipse project for us. So, source the zephyr environment and build the project for STM32F3DISCOVERY board with the following commands:

$ source ~/zephyrproject/.venv/bin/activate
$ source ~/zephyrproject/zephyr/zephyr-env.sh
$ west build -p always -d build/ source/ -b stm32f3_disco -G"Eclipse CDT4 - Ninja"

Now, import the project into Eclipse from File -> Import -> General -> Existing Projects into Workspace -> Next -> Browse for the hello_world project -> Finish

Set the Debug Configurations

Select the project on the Project Explorer and go to Run -> Debug Configurations.

Then right click on GDB Open OCD Debugging and create a new configuration.

Now, set the following options are per below points and screenshots

1. Open the “Main” tab of Debug Configurations

2. Type the C/C++ Application name as zephyr/zephyr.elf

3. Open the “Debugger tab”

4. Browse for the OpenOCD executable file inside the zephyr SDK installation directory.

5. Verify the path of the selected OpenOCD executable.

6. Enter TCL port 6333

7. Enter the following OpenOCD config options. Please verify the paths according to your system.

-s /home/<username>/zephyrproject/zephyr/boards/arm/stm32f3_disco/support

-s /home/<username>/zephyr-sdk-0.16.3/sysroots/x86_64-pokysdk-linux/usr/share/openocd/scripts

-f /home/<username>/zephyrproject/zephyr/boards/arm/stm32f3_disco/support/openocd.cfg

8. Browse for the GDB executable file inside the zephyr SDK installation directory.

9. Click Debug to start debugging.

Debug the project

All settings are done, now you can step debug the project.

Thanks for reading!

Rohan Dey