Using VS Code for FreeRTOS™ application debugging

Sarra.S · ‎2025-01-15

Introduction

In this article, we explore how to set up and debug a FreeRTOS™ project for the STM32H753 microcontroller using visual studio code (VS Code). We cover the necessary extensions, step-by-step project creation, and debugging processes, including using the XRTOS view for enhanced debugging capabilities.

1. Prerequisites

1.1 Hardware

NUCLEO-H753ZI - STM32 Nucleo-144 development board
USB cable with Micro-AB

1.2 Software

2. Extensions needed

For the first VS Code IDE setup with STM32 VS Code extension, you can refer to: How to use VS Code with STM32 microcontrollers.

To work with FreeRTOS™ projects in VS Code, you need the following extensions:

C/C++ extension: This extension provides C++ language support, including syntax highlighting and IntelliSense. This extension can be downloaded in the VS Code IDE.
CMake tools extension: This extension provides a full-featured, convenient, and powerful workflow for CMake-based projects in visual studio code.
Cortex®-Debug extension: This extension allows you to deploy and debug your FreeRTOS™ application on your target device. It supports various hardware debuggers and software.

Needed Extensions

3. Creating a FreeRTOS™ project

For this project, we focus on RTOS tasks to demonstrate the utility of RTOS views in VS Code.

A task is a C function, that should be run within in an infinite loop like:

for(;;)
{
/* Task code */
}

It can be used to generate any number of tasks (separate instances), and has its own part of stack and priority.

4. STM32CubeMX configuration

To get started with configuring FreeRTOS™ in STM32CubeMX, you can refer to: How to enable FreeRTOS™ within a project for STM32U5 MCUs

In the [Pinout & Configuration] tab, select [FreeRTOS] in [Middleware and Software Packs].
In [Tasks and Queues], create 2 tasks besides the default task as follows.

Tasks creation.png

Make sure that [vTaskDelay] is set to [Enabled] in [Include parameters].

vTaskDelay

To generate the code for VS Code IDE go to the [Project manager] tab and select [CMake] as toolchain/IDE.

Project generation

5. Code configuration

You can find the complete project in the following GitHub Hotspot: Debug_STM32_FreeRTOS_with_VS_Code

First, any component in FreeRTOS™ needs to have a handler

/* Private variables ---------------------------------------------------------*/
osThreadId_t defaultTaskHandle;
osThreadId_t Task1Handle;
osThreadId_t Task2Handle;

And task function prototypes:

/* Private function prototypes -----------------------------------------------*/

void StartDefaultTask(void *argument); void StartTask1(void *argument); void StartTask2(void *argument);

Also, before any OS component creation, we need to initialize the kernel:

/* USER CODE END 2 */
  /* Init scheduler */
  osKernelInitialize();

We can create already defined tasks and other OS components before the scheduler is started (it is possible to create and delete tasks within working OS as well).

Modifications in main.c are needed:

Start the scheduler, this function should never end.

  /* Start scheduler */
  osKernelStart();

Note: If the function ends, it means that you are out of declared heap size and there was not enough memory space to create a new task

Once the scheduler selects a task for execution, an assigned function is called. In the case of Task1 it is StartTask1(). Add Task_action() and osDelay() functions like below:

Similar code should be added for defaultTask and Task2.

Compile the code

To debug the project, some modifications need to be done in the launch.json file generated by VS Code.
You can refer to the full GitHub project.

"version": "0.2.0",
    "configurations": [     
{
            
     "name": "Build & Debug Microcontroller - ST-Link",
     "cwd": "${workspaceFolder}",
     "type": "cortex-debug",
     "executable": "${command:cmake.launchTargetPath}",
  // Let CMake extension decide executable: "${command:cmake.launchTargetPath}"
  // Or fixed file path: "${workspaceFolder}/path/to/filename.elf"
     "request": "launch",
     "servertype": "stlink",
     "device": "STM32H753ZITx", //MCU used
     "interface": "swd",
     "serialNumber": "",        //Set ST-Link ID if you use multiple at the same time
     "runToEntryPoint": "main",
   "svdFile":${config:STM32VSCodeExtension.cubeCLT.path}/STMicroelectronics_CMSIS_SVD/STM32H753.svd",
     "v1": false,               //Change it depending on ST Link version
     "serverpath": "${config:STM32VSCodeExtension.cubeCLT.path}/STLink-gdb-server/bin/ST-LINK_gdbserver",
            "stm32cubeprogrammer":"${config:STM32VSCodeExtension.cubeCLT.path}/STM32CubeProgrammer/bin",
     "stlinkPath": "${config:STM32VSCodeExtension.cubeCLT.path}/STLink-gdb-server/bin/ST-LINK_gdbserver",   
     "armToolchainPath": "${config:STM32VSCodeExtension.cubeCLT.path}/GNU-tools-for-STM32/bin",
     "gdbPath":"C:/Program Files/gcc-arm-none-eabi/bin/arm-none-eabi-gdb",            
            "serverArgs": [
                "-m","0",
            ],
   //"preLaunchTask": "Build + Flash"
   /* If you use external loader, add additional arguments */
   //"serverArgs": ["--extload", "path/to/ext/loader.stldr"],
        },

Note that the "gdbPath", "GNU-Tools-for-STM32", "serverpath" and stlinkPath could be different depending on your installation.

6. Debugging

The tasks created can exist in several states, each a different stage of execution or waiting, the primary states are shown in the figure below:

RTOS states

The XRTOS view in VS Code provides a comprehensive visualization of these task states. When debugging your FreeRTOS™ application, the XRTOS view allows you to see the status of each task in real time. You can monitor which tasks are running, which are ready to run, and which are blocked or suspended. This detailed insight helps to understand the behavior of your application and diagnose issues related to task scheduling and synchronization.

You can download the RTOS Views extension that allows you to deploy and debug your FreeRTOS™ application on your target device. It supports various hardware debuggers and software. This extension automatically detects the presence of an RTOS by looking for specific global variables.

RTOS Views download

To start a debug session, click on (Ctrl+Shift+D) and start debugging:

To use this view, you need to launch a debugging session and use the XRTOS view to monitor your RTOS tasks and system rate, this also could be used to monitor the stack usage.

XRTOS view