P&E ARM Cortex-M Debugging with FreeRTOS Thread Awareness and Real Time Expressions for GDB and Eclipse

P&E has a new version of their GDB/Eclipse debug plugins available on their Eclipse update site, and it comes with to great features: Real Time Expressions (show variables while target is running) and  FreeRTOS thread awareness 🙂

FreeRTOS Thread Awareness

FreeRTOS Thread Awareness

Outline

This post is about two new and great features for P&E based run control for ARM Cortex-M, and how to install and use the new features.

With FreeRTOS as one of the most popular realtime operating systems, there is growing support for it in the industry. Both OpenOCD and Segger have support for FreeRTOS thread aware debugging built into their run control. Now P&E has added that too: with this the gdb/Eclipse thread view shows all the running tasks and it is easy to switch and debug them.

But not only that: The other thing with the Freescale/NXP move from CodeWarrior to Kinetis Design Studio is that I have lost the CodeWarrior ability to show/update variables/expressions while the target is running (see “Live View for Variables and Memory“). Now this is back in Kinetis Design Studio or any other Eclipse using this new P&E Plugin :-).

I have used it both the OpenSDA P&E firmware and with native P&E probes like the Multilink Universal:

P&E Multilink Universal

P&E Multilink Universal

Installation

I have used the plugin for a few days with NXP Kinetis Design Studio V3.2.0 and the GNU ARM Eclipse plugins, and it worked great. To install it, get the P&E plugins from the following P&E Eclipse update site using the Eclipse menu Help > Install New Software:

http://www.pemicro.com/eclipse/updates
Updating P&E Plugins in Eclipse

Updating P&E Plugins in Eclipse

The version you are looking for is the 2.8.5 (or later).

💡 An earlier version of the plugin available from P&E crashed if configUSE_PORT_OPTIMISED_TASK_SELECTION  was set to 0 which I have reported to P&E. The version 2.8.5 works now fine.

The update site lists as well the E200 plugin which should not be enabled for ARM/Kinetis Development. Click ‘Next’ and go through the usual installation process. Restart Eclipse at the end of the installation.

FreeRTOS Thread Awareness

With using the new plugins and debugging a FreeRTOS application, it shows the FreeRTOS threads in the Eclipse debug view:

FreeRTOS Thread Awareness

FreeRTOS Thread Awareness

Clicking on a Thread changes the context (stack frame, registers, variables). So with this, I can see and debug all the FreeRTOS threads running.

The plugin uses FreeRTOS global variables (e.g. list of tasks) for the thread awareness. This is done automatically in the background. I have not seen any problems with it, but just in case, there is an option in the Eclipse launch configuration to turn it off.

With adding

-kernel=none

to the Server Parameters, it turns it off:

Disabling P&E FreeRTOS Kernel Awareness

Disabling P&E FreeRTOS Kernel Awareness

💡 I really like the fact that the feature is turned on by default. If I really do not want it (which I think never will be the case) or if there would be any side effects, I still can turn it off.

configTASK_RETURN_ADDRESS

FreeRTOS on ARM usually sets the return address of a task to zero. For this I have the following defined in my FreeRTOSConfig.h

#define configTASK_RETURN_ADDRESS   0  /* return address of task is zero */

For smaller code, I have usually that macro defined.

If that define is not defined, the tasks are setup to use a special function prvTaskExitError() as the caller function. This function does catch the case if the task returns (which would be a programming error), defined in port.c:

void prvTaskExitError(void) {
  /* A function that implements a task must not exit or attempt to return to
  its caller as there is nothing to return to.  If a task wants to exit it
  should instead call vTaskDelete( NULL ).

  Artificially force an assert() to be triggered if configASSERT() is
  defined, then stop here so application writers can catch the error. */
  configASSERT(uxCriticalNesting == ~0UL);
  portDISABLE_INTERRUPTS();
  for(;;) {
    /* wait here */
  }
}

The screenshot below shows such a case where the Led task is leaving the task scope:

Stackframe with prvTaskExitError

Stackframe with prvTaskExitError

While catching the error works (great!), you can see that the stack unwinding is not correct, showing uxListRemove(). I did an investigations if this is a problem with gdb or with the initial stack layout, and I have not come to a conclusion. For me it is not a problem, as I have configTASK_RETURN_ADDRESS set to zero. So I recommend that you use

#define configTASK_RETURN_ADDRESS   0  /* return address of task is zero */

Realtime Expressions View

Another great feature which gets added with the update is the ‘Realtime Expressions View’, accessible through Window > Show View > Other:

P&E Realtime Expressions View

P&E Realtime Expressions View

This adds a new view where I can add expressions. The expressions are updated  while the target is running:

Realtime Expressions View

Realtime Expressions View

That way I can easily watch the state of my application without the need to stop it :-). The view mirrors the variables present in the normal expressions view, but is able to read them while the target is running:

Expressions View

Expressions View

There is a button which I can press to pause the update. This is useful for when I’m concerned about intrusiveness (but I did not really see any impact with a handful of variables):

Disabling Update in Live Expressions View

Disabling Update in Realtime Expressions View

The view reads the variable content from the memory of the running target. If dereferencing a pointer it would mean that the debugger needs to read the pointer, then indirect it to read the targeting memory. Because this requires two accesses, the expression might not be right:

Dereferenced Pointer

Dereferenced Pointer

Summary

I have used the plugin with FreeRTOS V9.0.0 (McuOnEclipse port) successfully and it works like a charm. I have not tested it with older FreeRTOS versions, but I know for other FreeRTOS kernel aware support e.g. in OpenOCD it heavily depends on the version of RTOS used. So I recommend that you use the latest RTOS. You can find a snapshot of FreeRTOS for ARM Cortex-M as part of the McuOnEclipse Library on GitHub.

The Realtime Expressions view closes a big gap left with the move from CodeWarrior to Kinetis Design Studio and is really helpful to inspect variables while the target is running.

Debugging FreeRTOS on NXP FRDM-K64F with P&E Multilink Universal

Debugging FreeRTOS on NXP FRDM-K64F with P&E Multilink Universal

Happy P&E’ing 🙂

Links

Advertisements

20 thoughts on “P&E ARM Cortex-M Debugging with FreeRTOS Thread Awareness and Real Time Expressions for GDB and Eclipse

  1. Pingback: Comparing CodeWarrior with Kinetis Design Studio | MCU on Eclipse

  2. Thanks Erich as always.
    Does P&E FreeRTOS-aare debug also require FreeRTOSConfig.h to include:
    #define configUSE_PORT_OPTIMISED_TASK_SELECTION 0 // Note: 1 causes FreeRTOS Eclipse plug-in to crash…
    #define configTASK_RETURN_ADDRESS 0 // place 0 task return address on stack to help FreeRTOS-aware debugger (GDB unwind thread stack)
    Perhaps remind readers if so?
    Thanks again,
    Best Regards, Dave

    Like

    • Hi Dave,
      good question! Indeed, I have reported a bug to P&E with configUSE_PORT_OPTIMISED_TASK_SELECTION set to 0 which is fixed in that latest version used in this article.
      About configTASK_RETURN_ADDRESS: I always have set that to zero, and I know there were some issues (GDB, not P&E?) if this is not set to zero.
      I did a quick test using the task exit error handler and that worked fine, except that for the ‘normal’ stack layout it showed a bogus entry. To me this shows up on other thread awareness, so sounds like a GDB issue to me.
      In any case, I have extended now the article about this topic too.
      Thanks for the questions!
      Erich

      Like

    • I did not had to upgrade the firmware, probably because I always have it updated to the latest version. About seeing only global variabes: that’s normal, because only global variables have a fixed address. Watching local/stack variables does not make any sense.

      Like

      • Erich, your blog has saved me countless hours. Thank you for sharing your knowledge. I have updated KDS and I can now see variable update in real time. This is great!! Now I don’t need to use Freemaster to read variables (unless I want a graphical representation). Thanks again!

        Like

  3. Pingback: What is “Realtime Debugging”? | MCU on Eclipse

  4. Pingback: Better FreeRTOS Debugging in Eclipse | MCU on Eclipse

  5. Pingback: Embedded World Nürnberg 2017 Impressions: MCUXpresso, Hexiwear, NTAG, LPC800-DIP and Alan Hawse | MCU on Eclipse

  6. Hi Erich,

    Is there any option for FreeRTOS task-aware debugging with P&E hardware on Codewarrior 10.7? Looks like the Eclipse version is too old for this plugin.

    Thanks!

    Like

  7. For “Realtime Expressions”, what resources of the Cortex-M are used, to implement this? E.g. ITM + SWO, or some other combination.

    Like

    • I cannot really answer that, this is more of a question to P&E. But my thinking is that it does not depend on things like ITM or SWO, as it works for ARM v6 as well. My guess is that it uses a recent addition to GDB which allows to access the target while it is running. So they could poll the device from the probe firmware and notify the gdb client about it.

      Like

  8. Pingback: Troubleshooting Tips for FreeRTOS Thread Aware Debugging in Eclipse | MCU on Eclipse

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s