Introduction#

All the SimpleLink™ Software Development Kits (SDKs) include the ability to use FreeRTOS™ (as well as the TI-RTOS7). This workshop will explain what this really means.

Here’s what we’ll learn:

  • How TI Drivers work with FreeRTOS

  • POSIX support with FreeRTOS

  • Understand parts of FreeRTOS kernel projects

Prerequisites#

FreeRTOS Installation#

Just to be very clear and not surprise you at the end, the FreeRTOS kernel is not bundled into the SimpleLink SDK. You’ll need to download FreeRTOS yourself from www.freertos.org. Please refer to the <SimpleLink_SDK_Install_Dir>/docs/Documentation_Overview.html file to find the “Quick Start Guide” and “Release Notes” for the recommended version and how to plug FreeRTOS into your IDE.

Lab: Getting started#

This lab will explore some of the configuration parameters of FreeRTOS.

Software#

  • CCS as specified by your SimpleLink SDK Release Notes (CCS Cloud is also possible, but the steps below will assume you are using the desktop CCS)

  • Any SimpleLink SDK

Note

In order for the example code to function correctly the compiler needs to be changed from “z” to “0”, otherwise the compiler will overlook some of our changes, optimizing out the buf/malloc; follow the steps below in order to rectify the issue, as well as make the example more universal between the device families.

  1. To modify the FreeRTOSConfig.h file you first need to unlink the file from the autogeneration from sysconfig, follow the following to disable autogeneration empty.syscfg > FreeRTOS > show generated files > slide FreeRTOSConfig.h to not include in build; this will exclude the file from auto generation and allow the modification of the ‘FreeRTOSConfig.h’ file.

../../../_images/empty_freertos_exclude.png

  1. Now to you will need to move the FreeRTOSConfig.h out debug (after building the project at least once) follow debug > syscfg > select FreeRTOSConfig.h to move the file out of sysconfig to the header of the project, as shown in the image.

../../../_images/empty_freertosconfig.png

  1. Finally change the compiler optimizer from “z” to “0”, follow these steps: right click the project > properties > build > arm compiler > optimization > select optimization paradigm/level change “z” to “0”.

../../../_images/freertos_compiler_level.png

Hardware#

Task 1: Import FreeRTOS Empty Driver Project#

In Resource Explorer, import the FreeRTOS empty example in examples/rtos/*Board*/drivers/empty directory. You can select from GCC, IAR, or TI Clang Compiler.

../../../_images/freertos_empty.png

Task 2: Add a bogus malloc()#

In empty.c at the beginning of mainThread(), add an allocation of a very large size (e.g. malloc(0x80000)).

empty.c#
void *mainThread(void *arg0)
{
    char *buf;
    buf = malloc(0x80000);
    if (buf != 0)
    {
       GPIO_write(CONFIG_GPIO_LED_0, 1);
    }
    return (0);
}

Task 3: Modify FreeRTOSConfig.h#

Let’s add the malloc failure hook function feature into FreeRTOS. This is done by editing FreeRTOSConfig.h in the kernel project. Please change the 0 to a 1 for the configUSE_MALLOC_FAILED_HOOK constant.

FreeRTOSConfig.h#
#define configUSE_MALLOC_FAILED_HOOK    1

Task 4: Add Hook Function#

In empty.c at the bottom of the file, add following hook function.

empty.c#
void vApplicationMallocFailedHook()
{
    /* Handle Memory Allocation Errors */
    while(1)
    {
        GPIO_write(CONFIG_GPIO_LED_0, 0);
    }
}

Task 5: Build#

Build and load the project. Before you run, set a hardware breakpoint in the vApplicationMallocFailedHook() function in main_freertos.c.

Warning

If you still do not have the FREERTOS_INSTALL_DIR set you’ll get a build error. Please refer to the SimpleLink SDK Quick Start Guide, or the Example header above for details on how to set this up.

Task 6: Run#

Run the application. You should be in vApplicationMallocFailedHook() now.

../../../_images/malloc_failed_breakpoint2.png

What happened? You tried to allocate too big of a block of memory and the malloc falled. The configUSE_MALLOC_FAILED_HOOK is set to 1 in FreeRTOSConfig.h in the FreeRTOS kernel project. Therefore, if an allocation failure occurs, the vApplicationMallocFailedHook() is called.

Try running the project without debug, and notice that the Red LED is off. This means that the program has entered the vApplicationMallocFailedHook(), and set the Red LED to zero.

Let’s see how much memory we have in the heap. Open Tools->Runtime Object View. Select FreeRTOS and in the new view, select Heap Stats.

../../../_images/heap_usage.png

As you can see 0x80000 is larger than 31552 (depending on your device, the size might be different), so it makes sense the hook function was called.

Note: to open additional FreeRTOS views (e.g. Task Instances), select the view icon slightly to the right of FreeRTOS.

../../../_images/more_views.png

Task 7: Remove the hook function#

Edit the FreeRTOSConfig.h file in the FreeRTOS kernel project and change configUSE_MALLOC_FAILED_HOOK to back 0.

FreeRTOSConfig.h#
#define configUSE_MALLOC_FAILED_HOOK    0

Task 8: Build and run#

Build and load the empty project. Now step over the malloc() call and you see that

  1. The hook function was not called.

  2. The malloc() call returned NULL.

Now run the project again without debug, notice that this time the Red LED stays on, indicating that vApplicationMallocFailedHook() has not been called, and malloc() has returned NULL.

Quizzes#

Let’s see if you picked up some key points…

## TI Drivers can be used with FreeRTOS? 1. [x] Yes > You are correct! 1. [ ] No > TI Drivers work with FreeRTOS! ## To use FreeRTOS, do you have to use POSIX? 1. [ ] Yes > You are not required, but using POSIX allows your application to be OS-agnostic. 1. [x] No > You are not required, but using POSIX allows your application to be OS-agnostic. ## Can you change the FreeRTOSConfig.h file to tailor the kernel to your needs? 1. [x] Yes > You are correct! 1. [ ] No > Yes you can! However, please note that the provided FreeRTOSConfig.h file was used for all regression testing. ## Should application code use DPL directly? 1. [ ] Yes > DPL is an OS abstraction for just the TI Drivers. You should not use it directly. 1. [x] No > DPL is an OS abstraction for just the TI Drivers. You should not use it directly.

Additional Resources#

Additional training and reference material for FreeRTOS is available in the following places:

General FreeRTOS Support

SimpleLink Academy

SimpleLink SDK

TI Drivers APIs

Forums