Steps to use FreeRTOS with newlib reentrant Memory Allocation

Reentrancy is an attribute of a piece of code and basically means it can re-entered by another execution flow, for example by an interrupt or by another task or thread. This is an important concept and still a lot of code ‘in the wild’ does violate reentrancy. As a result the application crashes immediately in the best case. Worse it crashes randomly or even worse it behaves incorrectly 😦 .

Reentrancy is always a concern if using standard library functions, including printf() or malloc(). FreeRTOS offers a reentrant wrapper to the standard malloc() and free() (Memory Scheme 3)

Running FreeRTOS with reentrant newlib

Running FreeRTOS with reentrant newlib

In this article I show you how you can enable in FreeRTOS a reentrant newlib malloc wrapper, both for FreeRTOS and the rest of the application.

💡 The ‘heap scheme 6’ has been contributed by Dave Nadler. For technical details about how it works I highly recommend that you read his material on http://www.nadler.com/embedded/newlibAndFreeRTOS.html

In this article I’m using the NXP i.MX RT1064 EVK with the MCUXpresso IDE 11.2.1 and MCUXpresso SDK. I’m using FreeRTOS 10.4.1. But in general the steps apply to any IDE, FreeRTOS version and board. The project used in this article is on GitHub.

Enable the Heap Scheme

First, enable the heap scheme 6 (reentrant newlib). One way is to change the following define:

 
#define configUSE_HEAP_SCHEME (6) /* either 1 (only alloc), 2 (alloc/free), 3 (malloc), 4 (coalesc blocks), 5 (multiple blocks), 6 (newlib) */
Heap scheme

Heap scheme

If using a different FreeRTOS port, make sure that heap 1 – 5 are either excluded or removed from the the project. The port used here automatically switches to the correct heap implementation using the above macro.

Heap use newlib

Heap use newlib

Library

As we are going to use the standard library free and malloc with the reentrancy hooks, need make sure either newlib or newlib-nano is used. So check your linker settings for this. In MCUXpresso IDE I can easily set the library here:

Setting Library

Setting Library

You might check as well the setting in the linker:

Linker Library Settings

Linker Library Settings

Heap Size

Now as we are using the standard library heap, the usual FreeRTOS configTOTAL_HEAP_SIZE has no meaning: I have to configure the heap size in the linker file. The MCUXpresso IDE uses a smart linker files, so the only thing I have to do is to set the heap size for the linker in the project properties:

Heap Size in Linker properties

Heap Size in Linker properties

That’s it. Build the application and use the debugger to verify your application. In case FreeRTOS barks about running out of heap memory, increase the heap size depending on your tasks and task stack sizes.

Running FreeRTOS with reentrant newlib

Running FreeRTOS with reentrant newlib

Note that heap_useNewlib.c comes with a custom sbrk() implementation: so make sure this and the linker symbols matches the comments in the source. As for FreeRTOS port used, the symbols are automatically detected and assigned :-).

Happy mallocing 🙂

Links

6 thoughts on “Steps to use FreeRTOS with newlib reentrant Memory Allocation

  1. Hi Erich, I know that this is a matter of personal preferences, but the coloured text on the dark background is very difficult to read.

    Like

    • Hi Liviu,
      yes, and indeed it can be hard to read. Maybe I should change the theme used. The interesting thing is once you get used to it (at least working with a dark tool and desktop theme) it gets more comfortable. I realized that maybe 60% of students in my class used a black theme and was wondering the same as you. But then I tried it out and after a few days I feel it is really better than the ‘bright’ theme. Yes, it is a personal preference, but I have realized that there are benefits.
      Still I think that on a projection (classroom, beamer) I still find the ‘dark’ not as good. Maybe I should run a survey on this?

      Like

      • > Maybe I should run a survey on this?

        Well, surveys are democratic, but it does not mean that the results are scientifically correct, healthy or beneficial, they may just reflect a fashion.

        I personally think that, for the eye, unless you are an astronomer, focusing on a white surface in a moderately lit environments, is less fatiguing, since it keep the iris partly closed most of the time.

        In a dark environment, with a dark screen, the iris opens as much as possible, but as soon as you look at a white or brightly coloured area, it has to close, and this constant effort to adapt to the intensity of light brings eye fatigue.

        Not to mention that printed books use a white background.

        Like

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.