Troubleshooting Tips for FreeRTOS Thread Aware Debugging in Eclipse

FreeRTOS seems to be getting more and more popular, and I think that's partially because more and more debuggers and Eclipse IDE vendors have added dedicated debugging support for it.

FreeRTOS threads in Eclipse

This article describes tips and tricks to get FreeRTOS thread aware debugging in Eclipse, organized by debug probe connection/vendor. For thread awareness, the debugger needs to know some well-known symbols of the RTOS. So besides checking if thread awareness is turned on, have a look at the debug output. If the symbols are not present, it might be because of linker optimizations or not turning on FreeRTOS features.

P&E (Multilink)

The P&E debug connection has no special setting for FreeRTOS thread aware debugging and does it automatically, so there is no option to turn it on or off.

Thread Aware FreeRTOS Debugging with P&E

The P&E GDB servers should report this at the beginning in the console:

Successfully initialized kernel symbols.

P&E successfully initialized kernel symbols

The P&E GDB Server console should show:

Kernel thread information now available.

Kernel thread information available

Segger (J-Link)

FreeRTOS thread aware debugging with J-Link

Debugging with Segger J-Link

Thread aware debugging needs to be turned on for Segger with the following command

-rtos GDBServer/RTOSPlugin_FreeRTOS

That option can be specified in the launch configuration (GNU ARM (now MCU) Eclipse plugins, e.g. in Kinetis Design Studio 3.2.0):

FreeRTOS thread awareness option in Launch Configuration

In MCUXpresso IDE v10.0.2, there is a drop-down setting for this in the debug configuration:

MCUXpresso IDE Segger FreeRTOS setting

Check in the JLinkServer Eclipse console view to see if the needed symbols are present in the application:

Loading RTOS plugin: GDBServer/RTOSPlugin_FreeRTOS...
RTOS plugin (v1.0) loaded successfully
RTOS plugin initialized successfully.
Received symbol: pxCurrentTCB (0x2000B084)
Received symbol: pxReadyTasksLists (0x2000B088)
Received symbol: xDelayedTaskList1 (0x2000B0EC)
Received symbol: xDelayedTaskList2 (0x2000B100)
Received symbol: pxDelayedTaskList (0x2000B114)
Received symbol: pxOverflowDelayedTaskList (0x2000B118)
Received symbol: xPendingReadyList (0x2000B11C)
Received symbol: xTasksWaitingTermination (0x2000B130)
Received symbol: xSuspendedTaskList (0x2000B148)
Received symbol: uxCurrentNumberOfTasks (0x2000B15C)
Received symbol: uxTopUsedPriority (0x20000038)
Received symbol: uxTopReadyPriority (0x2000B164)
Received symbol: vPortEnableVFP (0x00016968)
All mandatory symbols successfully loaded.

Segger J-Link checking FreeRTOS Symbols

NXP (LinkServer)

Debugging FRDM-K64F with LinkServer (LPC-Link2)

With the LinkServer (MCUXpresso IDE) threads are shown like below:

FreeRTOS Thread Awareness with LinkServer

If threads are not shown, increase the Debug Level to 4 in the launch configuration:

LinkServer debug level

 I recommend to switch the debug level back to the default of 2, as it produces a lot of output.

In the Debug Messages Console view, check that all the needed symbols are found:

FreeRTOS symbol(s) found:
- "pxReadyTasksLists" 0x200028C0
- "xPendingReadyList" 0x20002950
- "xSuspendedTaskList" 0x20002980
- "xDelayedTaskList1" 0x200028A8
- "xDelayedTaskList2" 0x2000296C
- "pxDelayedTaskList" 0x2000289C
- "pxOverflowDelayedTaskList" 0x2000294C
- "xTasksWaitingTermination" 0x20002924
- "xSchedulerRunning" 0x200028A0
- "uxCurrentNumberOfTasks" 0x20002968
- "pxCurrentTCB" 0x2000293C
- "FreeRTOSDebugConfig" 0x0000474C
FreeRTOS stack backtrace is enabled

LinkServer debug messages

Read the MCUXpresso_IDE_FreeRTOS_Debug_Guide.pdf inside the MCUXpresso IDE installation folder.

Make sure you have the following turned on in FreeRTOSConfig.h:

#define configINCLUDE_FREERTOS_TASK_C_ADDITIONS_H    1
#define configUSE_TRACE_FACILITY                     1

Make sure you have “freertos_tasks_c_additions.h” present in your project (You can find a version of it in the NXP SDKs or here on GitHub).

If the FreeRTOSDebugConfig structure is missing (e.g. because of optimizations), make sure it is referenced/used from the application, e.g. with the following code in main():

extern uint8_t FreeRTOSDebugConfig[];
int main(void) {
    if (FreeRTOSDebugConfig[0]==0) { /* just use it, so the linker cannot remove FreeRTOSDebugConfig[] */
        for(;;); /* FreeRTOSDebugConfig[0] should always be non-zero, so this should never happen */
    }
    /* other code in main */
}

If xTasksWaitingTermination() is missing, check that you have the following enabled in FreeRTOSConfig.h:

#define INCLUDE_vTaskDelete   1

OpenOCD

For OpenOCD, see FreeRTOS Thread Debugging with Eclipse and OpenOCD.

Debugging with onboard OpenSDA and OpenOCD

FreeRTOS thread aware debugging depends on the debug connection used. In most cases, it might fail because some symbols are not present in the application to help the debugger to show the threads. I hope that this article helps you to find and possibly fix any issues.

Happy threading!

Links

• P&E ARM Cortex-M Debugging with FreeRTOS Thread Awareness and Real Time Expressions for GDB and Eclipse
• Adding FreeRTOS Thread Awareness to GDB and Eclipse
• FreeRTOS Thread Debugging with Segger GDB in Eclipse
• FreeRTOS Thread Debugging with Eclipse and OpenOCD