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)
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) */
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.
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:
You might check as well the setting in the linker:
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:
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.
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 🙂
- FreeRTOS Memory schemes: https://www.freertos.org/a00111.html
- Using FreeRTOS with newlib: https://mcuoneclipse.com/2017/07/02/using-freertos-with-newlib-and-newlib-nano/
- Article by Dave Nadler: http://www.nadler.com/embedded/newlibAndFreeRTOS.html
- Project used in this article: https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/MCUXpresso/i.MX%20RT1064_EVK/MIMXRT1064_FreeRTOS
Thanks Erich 😉
Big thanks to you, Dave!
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.
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?
> 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.
Yes, I agree. But I think that research shows as well some impact of the amount of ‘blue’/white light we are exposed to.
At the end, it is good to have a choice, and I tend to agree with you that for screenshots/articles I probably should switch the theme back to ‘light’, so many thanks for the feedback!
Anyway, because I’m interested in what readers think, I have started a survey: https://mcuoneclipse.com/2020/11/18/dark-or-light-what-is-your-preference/